fix: sync doc with extraction scope, remove boundary violation, add ProviderRegistryPort #5

2026-05-21T06:52:40Z

hurui200320 commented

2026-05-21 06:52:40 +00:00

Summary

This PR addresses documentation gaps and code issues identified after the LLM-assisted extraction of cleveractors-core from cleveragents-core.

When the library was extracted, the LLM failed to properly scope it. Three categories of problems were found and fixed here:

A file that belongs to the host (acms/index.py) was copied into the library in violation of ADR-001.
A port (ProviderRegistryPort) was referenced in docs but never implemented, leaving graphs unable to resolve LLM agents at execution time.
Nine design documents covering the actor abstraction, YAML schema, compiler, and preprocessing pipeline existed in cleveragents-core but had no equivalent here.

The PR has been squashed to a single commit and all review feedback has been addressed (see review responses below).

Changes

Documentation fixes (post-review)

docs/reference/actors_schema.md: Added provider field to LLM Actor and GRAPH Actor required fields; added full provider field definition with description, common values, and ADR-005 cross-reference; added provider to all YAML examples; added missing provider validation error message.
docs/reference/actor_config.md: Added provider alongside model in basic structure and hierarchical graph examples; fixed error message to match actual validator output; added missing provider error case.

Boundary fix — `acms/index.py` deleted

src/cleveractors/acms/index.py contained ACMSIndex, FileTraversalEngine, IndexEntry, FileType, and TierLevel. ADR-001 is explicit:

cleveractors.acms — Pure UKO vocabulary data; the indexer / storage / strategy runtime stays in cleveragents-core.

The implementation is bound to the CLI use case of cleveragents-core and has no relationship to actor YAML parsing or LangGraph compilation. It already exists in cleveragents-core at cleveragents/acms/index.py; it is deleted here and all re-exports removed from acms/__init__.py.

`ProviderRegistryPort` — new port

New file src/cleveractors/ports/provider_registry.py, following the same structural-typing pattern as ToolRegistryPort (ADR-002):

@runtime_checkable
class ProviderRegistryPort(Protocol):
    def get(self, provider: str, model: str) -> Agent | None: ...

Returns Agent (the library's own minimal ABC) rather than BaseChatModel to avoid coupling to a specific LangChain version. Host applications wrap their concrete models in an Agent subclass and return it from get().

Compiler — `actor/compiler.py`

_map_node now accepts actor_provider/actor_model as defaults and merges them into AGENT node metadata via setdefault, so per-node config values still take precedence. compile_actor passes config.provider/config.model through.

Node executor — `langgraph/nodes.py`

Node.__init__ gains an optional provider_registry: ProviderRegistryPort | None = None parameter. _execute_agent resolution order is:

Pre-resolved agents dict — existing behaviour, unchanged.
provider_registry.get(provider, model) using values from node metadata — new; allows hosts to supply LLM models without pre-building an agents dict.
Graceful synthetic "Agent {provider}/{model} not found" response — fallback format now matches ADR-005 specification.

BDD coverage — `features/` (7 scenarios, 30 steps)

New scenarios beyond the original ProviderRegistryPort happy-path test:

Graceful fallback when provider_registry.get() returns None
Graceful fallback when no provider_registry is supplied
Pre-resolved agents dict takes precedence over provider registry
Assertion strengthened to verify stub agent response content (not just message role)

Documentation

Doc	Content
`docs/adr/ADR-003-actor-abstraction-definition.md`	Ported from `cleveragents-core` ADR-031
`docs/adr/ADR-004-jinja2-yaml-template-preprocessing.md`	Ported from `cleveragents-core` ADR-032
`docs/adr/ADR-005-provider-registry-protocol.md`	New ADR for `ProviderRegistryPort`
`docs/reference/actors_schema.md`	Full YAML schema reference
`docs/reference/actor_compiler.md`	Compilation pipeline and error types
`docs/reference/actor_config.md`	Practical authoring guide
`docs/reference/actor_hierarchy.md`	Per-node LSP bindings, tool-source refs
`docs/reference/actors_examples.md`	Comprehensive YAML examples
`docs/api/actor.md`	Full public API reference
`mkdocs.yml`	Nav extended with all new docs

Quality gates

nox -e lint       ✅ PASS
nox -e typecheck  ✅ PASS (0 errors, 0 warnings)
nox -e unit_tests ✅ PASS (7 scenarios, 30 steps)
nox -e coverage_report ✅ PASS

Checklist

acms/index.py boundary violation removed
ProviderRegistryPort protocol created and wired into the node executor
ADR-003, ADR-004, ADR-005 written and cross-linked
Five reference docs written and linked
API reference written and linked
mkdocs.yml nav updated
provider field added to reference docs (post-review fix)
Fallback message format matches ADR-005 spec (post-review fix)
# type: ignore directive removed from smoke_steps.py (post-review fix)
BDD assertion strengthened to verify agent response content (post-review fix)
New BDD scenarios for fallback, no-registry, and agents-dict precedence (post-review fix)
Commit squashed with ISSUES CLOSED: #4 footer
Move acms/index.py back into cleveragents-core if needed — tracked separately; the file already exists there

CLOSE #4

## Summary This PR addresses documentation gaps and code issues identified after the LLM-assisted extraction of `cleveractors-core` from `cleveragents-core`. When the library was extracted, the LLM failed to properly scope it. Three categories of problems were found and fixed here: 1. A file that belongs to the host (`acms/index.py`) was copied into the library in violation of ADR-001. 2. A port (`ProviderRegistryPort`) was referenced in docs but never implemented, leaving graphs unable to resolve LLM agents at execution time. 3. Nine design documents covering the actor abstraction, YAML schema, compiler, and preprocessing pipeline existed in `cleveragents-core` but had no equivalent here. The PR has been squashed to a single commit and all review feedback has been addressed (see review responses below). --- ## Changes ### Documentation fixes (post-review) - **`docs/reference/actors_schema.md`**: Added `provider` field to LLM Actor and GRAPH Actor required fields; added full `provider` field definition with description, common values, and ADR-005 cross-reference; added `provider` to all YAML examples; added missing `provider` validation error message. - **`docs/reference/actor_config.md`**: Added `provider` alongside `model` in basic structure and hierarchical graph examples; fixed error message to match actual validator output; added missing `provider` error case. ### Boundary fix — `acms/index.py` deleted `src/cleveractors/acms/index.py` contained `ACMSIndex`, `FileTraversalEngine`, `IndexEntry`, `FileType`, and `TierLevel`. ADR-001 is explicit: > `cleveractors.acms` — Pure UKO vocabulary data; **the indexer / storage / strategy runtime stays in cleveragents-core.** The implementation is bound to the CLI use case of `cleveragents-core` and has no relationship to actor YAML parsing or LangGraph compilation. It already exists in `cleveragents-core` at `cleveragents/acms/index.py`; it is deleted here and all re-exports removed from `acms/__init__.py`. ### `ProviderRegistryPort` — new port New file `src/cleveractors/ports/provider_registry.py`, following the same structural-typing pattern as `ToolRegistryPort` (ADR-002): ```python @runtime_checkable class ProviderRegistryPort(Protocol): def get(self, provider: str, model: str) -> Agent | None: ... ``` Returns `Agent` (the library's own minimal ABC) rather than `BaseChatModel` to avoid coupling to a specific LangChain version. Host applications wrap their concrete models in an `Agent` subclass and return it from `get()`. ### Compiler — `actor/compiler.py` `_map_node` now accepts `actor_provider`/`actor_model` as defaults and merges them into AGENT node `metadata` via `setdefault`, so per-node config values still take precedence. `compile_actor` passes `config.provider`/`config.model` through. ### Node executor — `langgraph/nodes.py` `Node.__init__` gains an optional `provider_registry: ProviderRegistryPort | None = None` parameter. `_execute_agent` resolution order is: 1. Pre-resolved `agents` dict — existing behaviour, unchanged. 2. `provider_registry.get(provider, model)` using values from node `metadata` — new; allows hosts to supply LLM models without pre-building an agents dict. 3. Graceful synthetic `"Agent {provider}/{model} not found"` response — fallback format now matches ADR-005 specification. ### BDD coverage — `features/` (7 scenarios, 30 steps) New scenarios beyond the original ProviderRegistryPort happy-path test: - Graceful fallback when `provider_registry.get()` returns `None` - Graceful fallback when no `provider_registry` is supplied - Pre-resolved agents dict takes precedence over provider registry - Assertion strengthened to verify stub agent response content (not just message role) ### Documentation | Doc | Content | |-----|---------| | `docs/adr/ADR-003-actor-abstraction-definition.md` | Ported from `cleveragents-core` ADR-031 | | `docs/adr/ADR-004-jinja2-yaml-template-preprocessing.md` | Ported from `cleveragents-core` ADR-032 | | `docs/adr/ADR-005-provider-registry-protocol.md` | New ADR for `ProviderRegistryPort` | | `docs/reference/actors_schema.md` | Full YAML schema reference | | `docs/reference/actor_compiler.md` | Compilation pipeline and error types | | `docs/reference/actor_config.md` | Practical authoring guide | | `docs/reference/actor_hierarchy.md` | Per-node LSP bindings, tool-source refs | | `docs/reference/actors_examples.md` | Comprehensive YAML examples | | `docs/api/actor.md` | Full public API reference | | `mkdocs.yml` | Nav extended with all new docs | ### Quality gates ``` nox -e lint ✅ PASS nox -e typecheck ✅ PASS (0 errors, 0 warnings) nox -e unit_tests ✅ PASS (7 scenarios, 30 steps) nox -e coverage_report ✅ PASS ``` ## Checklist - [x] `acms/index.py` boundary violation removed - [x] `ProviderRegistryPort` protocol created and wired into the node executor - [x] ADR-003, ADR-004, ADR-005 written and cross-linked - [x] Five reference docs written and linked - [x] API reference written and linked - [x] `mkdocs.yml` nav updated - [x] `provider` field added to reference docs (post-review fix) - [x] Fallback message format matches ADR-005 spec (post-review fix) - [x] `# type: ignore` directive removed from smoke_steps.py (post-review fix) - [x] BDD assertion strengthened to verify agent response content (post-review fix) - [x] New BDD scenarios for fallback, no-registry, and agents-dict precedence (post-review fix) - [x] Commit squashed with `ISSUES CLOSED: #4` footer - [ ] Move `acms/index.py` back into `cleveragents-core` if needed — tracked separately; the file already exists there CLOSE #4

hurui200320 self-assigned this 2026-05-21 06:52:40 +00:00

hurui200320 added a new dependency 2026-05-21 06:55:28 +00:00

#4 Design doc gaps and boundary violations in cleveractors-core

hurui200320 force-pushed fix/doc-sync from 7084e175a2 to 6d24090ee0

2026-05-21 08:07:01 +00:00

Compare

hurui200320 changed title from ~~WIP: Sync doc with extraction scope, remove boundary violation, add ProviderRegistryPort~~ to fix: sync doc with extraction scope, remove boundary violation, add ProviderRegistryPort

2026-05-21 08:08:16 +00:00

hurui200320 added the

Type

Documentation

label 2026-05-21 08:09:00 +00:00

hurui200320 referenced this pull request

2026-05-21 08:09:42 +00:00

Design doc gaps and boundary violations in cleveractors-core #4

hurui200320 force-pushed fix/doc-sync from 6d24090ee0 to 7084e175a2

2026-05-21 08:23:56 +00:00

Compare

hurui200320 force-pushed fix/doc-sync from 7084e175a2 to 4870db2806