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:
- Manual registration — Write a class, inherit a base → it's registered. No
registry["foo"] = FooClass. - 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. 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
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) |
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:
| 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.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| conscribe-2.1.0.tar.gz | 387.7 kB | Without provenance | Details for conscribe-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| conscribe-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for conscribe-2.1.0-py3-none-any.whl |
Total release size: 805.5 kB
Release files / conscribe-2.1.0.tar.gz
| Download URL | conscribe-2.1.0.tar.gz |
|---|---|
| Size | 387.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a84977dda75e4a5c1fbbda2b4ccf38f5eb0bc6ea747cc652dc5321ce0bda955
|
|
BLAKE2b-256 checksum How to use checksums |
1f3abdf8f9b94f67749153ac27dc42f531a10cd9b503ad1b1c92abca2e1f7a8b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / conscribe-2.1.0-py3-none-any.whl
| Download URL | conscribe-2.1.0-py3-none-any.whl |
|---|---|
| Size | 417.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
70cae0216c44ab958591180cbd501ca95074354de9c193bf1617276e327ae10a
|
|
BLAKE2b-256 checksum How to use checksums |
7a27bf6fd9c1c3f54d13de1c2172eb81c6795db5615f990c64ff5db701589d37
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for conscribe 2.1.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.