Skip to main content

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 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

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

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

3. Write Implementations (auto-registered)

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

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:

from conscribe import build_layer_config, generate_layer_config_source

result = build_layer_config(LLMRegistrar)
source = generate_layer_config_source(result)
# 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 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):

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:

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[...]:

# 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:

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:

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): ...
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. A composed build of part of the implementations relaxes two of these checks on request (coverage="partial", see Composed Config). See 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:

# 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:

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:

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:

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

A framework that imports only the packages one config names can say so with coverage="partial". The build then leaves out keys of declare_only entries that are not registered, and keeps a receptor wired to an empty registry when its default selects no implementation (None, []). Such a field accepts only values that select nothing, and any other value fails with the error type no_implementation, naming the empty layer. result.unresolved_wiring lists what the build left out. The default, coverage="complete", keeps every check, so run it where everything is imported (code generation, CI):

# Only an android capability was imported: its two actions, and no archiver at all.
result = build_composed_config({"action": Action, "agent": Agent, "hook": Hook}, coverage="partial")
for item in result.unresolved_wiring:
    print(item, item.missing_optional_keys, item.registry_empty)
agent[dom].action ('scroll', 'drag') False
hook[trace_writer].archive () True

The full example, with the rules for what a partial build still refuses, is in Partial builds.

Cross-Registry Diamond Inheritance

Register a class in multiple registries:

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:

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:

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.


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:

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, *, coverage="complete") 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", coverage="complete") Build a multi-layer composed config (coverage="partial": from part of the implementations)
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:

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

License

MIT

Metadata

Release files for conscribe 2.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for conscribe 2.2.0
File Size Uploaded Provenance Actions
conscribe-2.2.0.tar.gz 401.8 kB Without provenance Details for conscribe-2.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for conscribe 2.2.0
File Interpreter ABI Platform Actions
conscribe-2.2.0-py3-none-any.whl Python 3 none any Details for conscribe-2.2.0-py3-none-any.whl

Total release size: 832.5 kB

Release files / conscribe-2.2.0.tar.gz

Download URL conscribe-2.2.0.tar.gz
Size 401.8 kB
Tags Source
SHA-256 checksum
How to use checksums
80474ac7a2861bbd275b42c45f7c9089d5a569f95bd3bf08887925219a4aea65
BLAKE2b-256 checksum
How to use checksums
0ed474d53044e735df6b5405f2492449e45863a68544c569df591a3ca6c311ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / conscribe-2.2.0-py3-none-any.whl

Download URL conscribe-2.2.0-py3-none-any.whl
Size 430.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fa30c5b2ef683560371b98f8e67fca5e413f1e3baf63513879871975f3e14440
BLAKE2b-256 checksum
How to use checksums
c0702634b732083247c23dd8995bc4ff61e003e9a37c26af566a00f18cbb570a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for conscribe 2.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page