Metadata-Version: 2.4
Name: conscribe
Version: 2.1.0
Summary: Automatic class registration and config typing stub generation for layered Python architectures
Project-URL: Homepage, https://github.com/QLYYLQ/conscribe
Project-URL: Documentation, https://github.com/QLYYLQ/conscribe/tree/master/conscribe/docs
Project-URL: Repository, https://github.com/QLYYLQ/conscribe
Project-URL: Issues, https://github.com/QLYYLQ/conscribe/issues
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: attrs>=22.0; extra == 'dev'
Requires-Dist: docstring-parser>=0.15; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: docstring
Requires-Dist: docstring-parser>=0.15; extra == 'docstring'
Description-Content-Type: text/markdown

# Conscribe

**Inheritance is registration. `__init__` signature (plus `__wiring__`) is config schema.**

Conscribe is a Python library that provides **automatic class registration** and **config typing stub generation** for layered architectures. It eliminates two categories of boilerplate:

1. **Manual registration** — Write a class, inherit a base → it's registered. No `registry["foo"] = FooClass`.
2. **Config guesswork** — Your `__init__` parameters become the config schema, and `__wiring__` adds the cross-registry fields on top. Users get IDE autocomplete for their YAML configs, and your framework gets one pydantic model that validates the whole config when it is loaded.

```
pip install conscribe
```

Version 2.1.0 requires Python >= 3.10 and pydantic >= 2.7, < 3. Install `conscribe[docstring]` to turn docstring `Args:` sections into field descriptions.

[Declaration provenance](conscribe/docs/provenance.md) explains which class declared each config field, which inherited declarations it overrides, why observed parameters were excluded, and where a constructor walk stopped. Use `Registrar.get_config_provenance(key)` with the layer’s own settings, or `extract_config_provenance(cls)`; `wiring_provenance(cls)` also exposes wiring exclusions and declaration-only entries without registry lookups.


---

## Who Is This For?

**Framework developers** building config-driven systems with pluggable layers (agents, LLM providers, browser backends, etc.) who need registries, factories, protocol checks, and config schemas — without N layers × boilerplate.

**Framework users** who write YAML configs and want IDE autocomplete, parameter docs, and a config that is checked when it is loaded instead of crashing N steps in.

---

## Quick Start

### 1. Define a Layer

```python
from typing import Protocol, runtime_checkable
from conscribe import create_registrar

@runtime_checkable
class ChatModelProtocol(Protocol):
    def chat(self, messages: list[dict]) -> str: ...

LLMRegistrar = create_registrar(
    "llm",
    ChatModelProtocol,
    discriminator_field="provider",
    strip_prefixes=["Chat"],
)
```

### 2. Create a Base Class

```python
class ChatBaseModel(metaclass=LLMRegistrar.Meta):
    __abstract__ = True
```

### 3. Write Implementations (auto-registered)

```python
class ChatOpenAI(ChatBaseModel):
    """OpenAI LLM provider.

    Args:
        model_id: Model identifier, e.g. gpt-4o
        temperature: Sampling temperature, 0-2
    """
    def __init__(self, *, model_id: str, temperature: float = 0.0):
        self.model_id = model_id
        self.temperature = temperature

    def chat(self, messages): ...

# Registered as "open_ai". No decorator. No registry call.
```

### 4. Discover & Use

```python
from conscribe import discover

discover("my_app.llm.providers")

llm_cls = LLMRegistrar.get("open_ai")   # -> ChatOpenAI
llm = llm_cls(model_id="gpt-4o")
print(LLMRegistrar.keys())              # ['anthropic', 'open_ai']
```

`discover()` imports every module of the package. If one of them fails to import, `discover()` raises instead of skipping it, and the error names the module. Name optional dependencies in `allow_missing=[...]` and packages that should never be imported in `exclude=[...]`.

---

## Config Typing

Your `__init__` signature is the config schema. Conscribe extracts it, builds a pydantic discriminated union, and generates a Python source file and a JSON Schema for IDE autocomplete:

```python
from conscribe import build_layer_config, generate_layer_config_source

result = build_layer_config(LLMRegistrar)
source = generate_layer_config_source(result)
```

```python
# Generated by conscribe 2.1.0
# Auto-generated by conscribe. DO NOT EDIT.
# Layer: llm
# Discriminator: provider
# Entries (2): anthropic, open_ai

from __future__ import annotations

from typing import Annotated, Literal, Union

from pydantic import BaseModel, ConfigDict, Field


class AnthropicLLMConfig(BaseModel):
    model_config = ConfigDict(extra="forbid")

    model_id: str = Field(description='Model identifier')
    max_tokens: int = Field(default=1024, description='Upper bound on generated tokens')
    provider: Literal['anthropic'] = 'anthropic'


class OpenAiLLMConfig(BaseModel):
    model_config = ConfigDict(extra="forbid")

    model_id: str = Field(description='Model identifier, e.g. gpt-4o')
    temperature: float = Field(default=0.0, description='Sampling temperature, 0-2')
    provider: Literal['open_ai'] = 'open_ai'


# Rebuild models for deferred annotation resolution
AnthropicLLMConfig.model_rebuild()
OpenAiLLMConfig.model_rebuild()


LLMConfig = Annotated[
    Union[AnthropicLLMConfig, OpenAiLLMConfig],
    Field(discriminator="provider"),
]
```

The descriptions come from the docstrings (Tier 1.5 below). The in-process models (`result.union_type`) and generated source preserve these declarations. JSON Schema (`generate_layer_json_schema(result)`) describes their fields, defaults, constraints, aliases and descriptions, but cannot run Python validators. If a validator cannot be reproduced in source, generation emits an `ExtractionWarning` and a header note; unsupported defaults or types raise `ConfigRenderError`.

See the [Config Typing Guide](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/guide-alice.md#step-5-generate-config-files) for full details.

### Config Tiers

| Tier | What You Write | What Users Get |
|------|---------------|---------------|
| **1** | Plain `__init__(self, *, x: int = 5)` | Names + types + defaults |
| **1.5** | + Google/NumPy docstring with `Args:` (needs `pip install conscribe[docstring]`) | + descriptions |
| **2** | + `Annotated[int, Field(ge=0)]` | + constraints, aliases, titles, examples |
| **3** | `__config_schema__ = MyModel` | Your model's fields, validators and `model_config`; an unset `extra` policy defaults to `"forbid"` |

### Nested Config (Hierarchical Keys)

For layers with natural hierarchies (e.g., model_type → provider):

```python
LLM = create_registrar(
    "llm", ChatModelProtocol,
    discriminator_fields=["model_type", "provider"],
    key_separator=".",
)
```

Produces hybrid YAML configs where level 0 is flat and level 1+ is nested:

```yaml
llm:
  model_type: openai        # flat (level 0)
  temperature: 0.7          # flat (level 0 param)
  provider:                 # nested (level 1)
    name: azure
    deployment: my-deploy
```

### Cross-Registry Wiring

Declare which values from other registries a class accepts. Conscribe constrains the config field to `Literal[...]`:

```python
# Given: a "loop" registry holding "react" and "codeact"

class BaseAgent(metaclass=AgentRegistrar.Meta):
    __abstract__ = True
    __wiring__ = {"loop": "loop"}  # all keys of the "loop" registry

    def step(self) -> None: ...


class SWEAgent(BaseAgent):
    __wiring__ = {"loop": ("loop", ["react"])}  # narrowed to a subset

    def __init__(self, *, loop: str, max_steps: int = 10): ...
```

Generated config:

```python
class SweAgentConfig(BaseModel):
    model_config = ConfigDict(extra="forbid")

    loop: Literal['react']  # wired from: loop
    max_steps: int = 10
    name: Literal['swe'] = 'swe'
```

Three modes:
- `"loop": "agent_loop"` — every key of the registry
- `"loop": ("agent_loop", ["react", "codeact"])` — explicit subset; a third element lists optional keys: `("observation", ["terminal"], ["filesystem"])`
- `"browser": ["chromium", "firefox"]` — literal list (no registry)

The registry-backed modes can also be written as a dict, which adds two options: a `default` key and `declare_only`:

```python
class CodingAgent(BaseAgent):
    __wiring__ = {
        "env": {"registry": "env", "default": "bash"},  # used when the config omits it
        "obs": {                                         # read by the framework, never injected
            "registry": "observation",
            "keys": ["terminal"],
            "optional_keys": ["screenshot"],
            "declare_only": True,
        },
    }

    def __init__(self, *, env: EnvProtocol, max_steps: int = 10): ...
```

```python
class CodingAgentConfig(BaseModel):
    model_config = ConfigDict(extra="forbid")

    env: Literal['bash', 'browser'] = 'bash'  # wired from: env
    max_steps: int = 10
    loop: Optional[Literal['codeact', 'react']] = None  # wired from: loop
    obs: Optional[Literal['terminal', 'screenshot']] = None  # wired from: observation
    name: Literal['coding'] = 'coding'
```

A wired field is called a *receptor*. Its *runtime slot*, when present, is a constructor parameter or non-`ClassVar` class annotation. A scalar constructor slot is required unless the slot or wiring entry provides a default (`env` above); an annotation-only slot admitting `None` is also optional without a class-body value. A container slot (`list[X]`, `dict[str, X]`) makes a list of keys. An entry without any slot (`loop`, inherited from `BaseAgent`) is optional: it names an attribute the framework sets after construction, and conscribe gives the class a `WiredField` placeholder that raises a clear `AttributeError` until then. `declare_only` entries are pure constraints: no placeholder, no stub attribute.

Inheritance: a child's `__wiring__` merges with its parent's (a child entry replaces the parent's entry). Use `None` to exclude: `{"llm": None}`.

Every wiring problem is an error. `build_layer_config()` and `build_composed_config()` check every registered class first and report all problems at once; grammar mistakes fail when the class is created. See [Fail-Fast Diagnostics](#fail-fast-diagnostics).

#### Capability-relative keys

When the target registry was created with a `key_separator`, an explicit key list may name a bare **trailing segment** instead of a fully-qualified key. Conscribe expands it to every registered key that ends with that segment, so a class does not have to name the provider it will run against:

```python
# Registered: "browser.click", "desktop.click", "browser.scroll"

class PortableAgent(BaseAgent):
    __wiring__ = {"action": ("action", ["click"], ["scroll"])}
    # -> Literal["browser.click", "desktop.click", "browser.scroll"]

class PinnedAgent(BaseAgent):
    __wiring__ = {"action": ("action", ["browser.click"])}  # escape hatch
    # -> Literal["browser.click"]
```

A key that already contains the separator is passed through unchanged. This is not a fourth mode — it only relaxes how the key strings inside the existing modes are matched, and it is inert for registries without a `key_separator`. A `default` key is never expanded: it must be spelled out in full.

If a short name matches several providers, **all** of them land in the `Literal[...]`. Conscribe expands; it does not arbitrate. Config generation cannot know which providers a given assembled runtime will hold, so every candidate is legitimately possible at that point; picking one belongs to the consuming framework, at the moment it knows the concrete provider set.

### Composed Config (Multi-Layer Inline Wiring)

Combine multiple layers into a single config schema. Wired fields become full inline config objects instead of key selectors — enabling recursive IDE autocompletion across layers:

```python
from conscribe import build_composed_config, generate_composed_json_schema

result = build_composed_config(
    {"llm": LLMRegistrar, "agent": AgentRegistrar},
    inline_wiring=True,   # wired fields become the target layer's union (the default)
)
schema = generate_composed_json_schema(result)
```

YAML config with inline wiring:

```yaml
agent:
  - name: browser_use
    use_vision: true
    llm:                        # a full LLM config inline -- the IDE completes every field
      provider: open_ai
      model_id: gpt-4o
      temperature: 0.7
  - name: react
    llm:
      provider: anthropic
      model_id: claude-sonnet-4-5
```

Use `inline_wiring=False` to keep wired fields as `Literal[...]` key selectors. With inline wiring, a slot-less entry becomes an optional inline config and a `declare_only` entry stays a key selector.

The top level only accepts the layer sections: an unknown key such as `agents:` is a validation error (the JSON Schema says `additionalProperties: false`). Pass `top_level_extra="ignore"` or `"allow"` if your config carries other sections.

Inline-only layers have no top-level section at all; their instances live inside other layers' receptors. Declare them on the registrar. A receptor whose wiring names a `default` key gets that key's whole config as its default:

```python
from pydantic import ValidationError

Hook = create_registrar("hook", HookProtocol, discriminator_field="name")
Archiver = create_registrar("archiver", ArchiverProtocol, discriminator_field="name", inline_only=True)


class ArchiverBase(metaclass=Archiver.Meta):
    __abstract__ = True


class DiskArchiver(ArchiverBase):
    __registry_key__ = "disk"

    def __init__(self, *, path: str = "traces/"): ...


class HookBase(metaclass=Hook.Meta):
    __abstract__ = True


class TraceWriter(HookBase):
    __registry_key__ = "trace_writer"
    __wiring__ = {"archive": {"registry": "archiver", "default": "disk"}}

    def __init__(self, *, archive: object): ...


ComposedConfig = build_composed_config({"hook": Hook, "archiver": Archiver}).top_level_type

config = ComposedConfig.model_validate({"hook": [{"name": "trace_writer"}]})
print(config.hook[0].archive)       # the default instance

try:
    ComposedConfig.model_validate({"archiver": [{"name": "disk"}]})
except ValidationError as exc:
    print(exc.errors()[0]["msg"])
```

```
path='traces/' name='disk'
layer 'archiver' is inline-only; write its instances under: hook[trace_writer].archive
```

### Cross-Registry Diamond Inheritance

Register a class in multiple registries:

```python
LLM = create_registrar("llm", LLMProtocol, discriminator_field="provider")
Agent = create_registrar("agent", AgentProtocol, discriminator_field="name")

CombinedMeta = LLM.Meta | Agent.Meta

class LLMAgentBase(metaclass=CombinedMeta):
    __abstract__ = True

class SelfPromptingAgent(LLMAgentBase):
    def chat(self, messages: list) -> str: ...
    def step(self) -> None: ...

print(LLM.keys(), Agent.keys())   # ['self_prompting_agent'] ['self_prompting_agent']
```

---

## Fail-Fast Diagnostics

A declaration conscribe cannot honour is an error. Grammar mistakes in `__wiring__` and invalid registry keys raise when the class is created (and the class is not registered); everything else raises when a config is built or generated. Every message names the class, the field and the bad value, and says what to change; a build reports all wiring problems at once:

```python
from conscribe import WiringResolutionError, build_layer_config

# Given: an "act" registry holding the key "click"

class Bad(BaseAgent):
    __wiring__ = {"action": ("act", ["kick"])}

    def __init__(self, *, action: str): ...


class Worse(BaseAgent):
    __wiring__ = {"tool": ("act", ["click"], ["kick"]), "llm": "llms"}


try:
    build_layer_config(AgentRegistrar)
except WiringResolutionError as exc:
    print(exc)
```

```
3 wiring problems:
  - Bad (key 'bad') wiring 'action': unknown key 'kick' in registry 'act'; registered: ['click']
  - Worse (key 'worse') wiring 'tool': unknown optional key 'kick' in registry 'act'; registered: ['click']
  - Worse (key 'worse') wiring 'llm': unknown registry 'llms'; known registries: ['act', 'agent']
```

| Error | Raised when |
|---|---|
| `WiringResolutionError` | A `__wiring__` entry is malformed or names an unknown or empty registry, an unknown key, or an invalid default. `.problems` lists every problem with a stable `kind`. |
| `ConfigAnnotationError` | An annotation names something that exists nowhere (a typo, a missing import). |
| `ConfigDeclarationError` | A declaration contradicts itself or cannot be honoured (two different defaults, `Field(exclude=...)` on a parameter, an inline-only layer nothing can hold). |
| `ConfigRenderError` | A value or type cannot be written faithfully into generated source. |
| `EmptyLayerError` | A layer has no registered classes (the message names modules `discover()` failed to import). |
| `InvalidRegistryKeyError` | A registry key is not a non-empty string. |

Warnings cover what conscribe cannot read or leaves to you: `ExtractionWarning` (part of a class it cannot read, such as a signature it cannot introspect, or a module `discover(strict=False)` skipped), `DegradationWarning` (a field type fell back to `Any`, e.g. a name imported only under `if TYPE_CHECKING:`), `StaleStubWarning` (old generated `.pyi` files nothing needs any more) and `IsolationWarning` (a test isolation block kept registrations made by modules it imported). All of them subclass `ConscribeWarning`, and warnings about a class point at its definition. To make them errors in your tests: `filterwarnings = error::conscribe.ConscribeWarning`.

---

## Testing

Registration is a side effect of class creation, so a class one test defines would otherwise stay registered for every later test. `conscribe.testing.isolated_registries()` restores every registry when the block ends:

```python
from conscribe.testing import isolated_registries

with isolated_registries():
    class ChatFake(ChatBaseModel):
        def chat(self, messages):
            return "canned answer"

    assert "fake" in LLMRegistrar.keys()   # registered as usual inside the block

assert "fake" not in LLMRegistrar.keys()   # and gone afterwards
```

pytest users add `pytest_plugins = ["conscribe.testing.pytest_plugin"]` to their root `conftest.py` and request the `conscribe_isolated` fixture. See the [testing guide](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/testing.md).

---

## Introspection

`conscribe.introspect` exposes the rules conscribe itself uses to read a class: which names the constructor accepts (following `**kwargs` up the MRO), which attributes can receive a wired value and in what shape. Frameworks use it to route config values:

```python
from conscribe.introspect import init_param_names, wiring_slots

class BrowserUse(BaseAgent):
    __wiring__ = {"llm": "llm"}

    def __init__(self, *, llm: object, use_vision: bool = False): ...

print(init_param_names(BrowserUse))          # names BrowserUse(...) accepts
slot = wiring_slots(BrowserUse)["llm"].slot  # where the wired LLM goes
print(slot.via, slot.shape)                  # 'init' = pass it to the constructor
print(wiring_slots(BrowserUse)["loop"].slot) # None = no slot: set after construction
```

```
('llm', 'use_vision')
init scalar
None
```

---

## API Reference

### Registration

| API | Purpose |
|-----|---------|
| `create_registrar(name, protocol, ...)` | Create a layer registrar (recommended entry point); `inline_only=True` for inline-only layers |
| `Registrar.get(key)` / `Registrar.keys()` / `Registrar.get_all()` | Look up registered classes |
| `Registrar.children(prefix)` / `Registrar.tree()` | Query hierarchical keys |
| `Registrar.bridge(external_cls)` | Create a bridge base for an external class |
| `Registrar.register(key)` | Manual registration decorator |
| `Registrar.unregister(key, *, missing_ok=False)` | Remove a key; returns the removed class |
| `Registrar.build_config()` / `Registrar.config_union_type()` | The layer's config result / its union type, for validation |
| `discover(*packages, strict=True, allow_missing=(), exclude=())` | Import modules to trigger registration |
| `scan_registrar_definitions(root)` | Static AST scan for registrar definitions (`conscribe.scanner`) |
| `list_registries(root, ...)` | Runtime list of all registered content (`conscribe.scanner`) |
| `isolated_registries()` | Scope registrations to a block (`conscribe.testing`) |

### Wiring

| API | Purpose |
|-----|---------|
| `validate_wiring(registrars)` | Report every wiring problem of every registered class at once |
| `check_wiring_declaration(cls)` | Grammar-only check of a class's `__wiring__` |
| `wired_field(cls, name)` / `wired_fields(cls)` | Look up `WiredField` placeholders without triggering them |
| `init_param_names`, `receptor_slots`, `wiring_slots` | How a class receives values (`conscribe.introspect`) |

### Config Typing

| API | Purpose |
|-----|---------|
| `extract_config_schema(cls, mro_scope, mro_depth)` | Extract a pydantic model from `__init__` + `__wiring__` |
| `build_layer_config(registrar)` | Build the discriminated union (flat or nested mode) |
| `generate_layer_config_source(result)` | Generate Python source |
| `generate_layer_json_schema(result)` | Generate JSON Schema |
| `build_composed_config(registrars, *, inline_wiring=True, top_level_extra="forbid")` | Build a multi-layer composed config |
| `generate_composed_json_schema(result)` | Generate the composed JSON Schema |
| `generate_composed_config_source(result)` | Generate composed Python source |
| `write_layer_stubs(registrar, output_dir=None, *, prune=False)` | Write `.pyi` stubs for injected attributes (`conscribe.stubs`) |
| `compute_registry_fingerprint(registrar)` | Hash of a layer's generated outputs |
| `get_registry(name)` | Look up a registry by name |

---

## Design Principles

- **Zero registration burden** — Inherit a base class = registered
- **`__init__` + `__wiring__` are the single source of truth** — No duplicate config definitions
- **Fail-fast** — A declaration conscribe cannot honour raises at class creation or build time, and the message says how to fix it
- **One model, three artifacts** — The in-process model, the generated source and the JSON Schema describe the same config
- **Domain-agnostic** — Pure infrastructure, knows nothing about agents or LLMs
- **Stubs and runtime are separate** — Stubs only help type checkers; stale ones are reported

---

## Documentation

Full documentation is shipped inside the package (accessible at `site-packages/conscribe/`) and [browsable on GitHub](https://github.com/QLYYLQ/conscribe/tree/master/conscribe/docs):

| Document | Description |
|----------|-------------|
| [`llms.txt`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/llms.txt) | AI entry point — package summary and navigation |
| [`docs/overview.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/overview.md) | Core concepts and architecture |
| [`docs/guide-alice.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/guide-alice.md) | Tutorial: building a framework with conscribe |
| [`docs/guide-bob.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/guide-bob.md) | Tutorial: consuming a conscribe-based framework |
| [`docs/api-reference.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/api-reference.md) | Full API signatures and examples |
| [`docs/recipes.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/recipes.md) | Task-oriented "how do I X?" |
| [`docs/registration.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/registration.md) | Registration subsystem internals |
| [`docs/config-typing.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/config-typing.md) | Config typing pipeline internals |
| [`docs/mro-and-degradation.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/mro-and-degradation.md) | MRO chains and type degradation |
| [`docs/testing.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/testing.md) | Test isolation for registries |
| [`docs/cli.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/cli.md) | CLI reference (`scan`, `list`, `inspect`, `generate-*`) |
| [`docs/migrating-to-2.0.md`](https://github.com/QLYYLQ/conscribe/blob/master/conscribe/docs/migrating-to-2.0.md) | Upgrading from conscribe 1.x |

---

## License

MIT
