cleveragents/cleveractors-core
0
0
Fork 0
Code Issues 17 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

feat(public-api): expose all router-facing APIs at cleveractors package level; update README #48

Open
hurui200320 wants to merge 1 commits from feature/17-public-api into master
pull from: feature/17-public-api
merge into: cleveragents:master
Conversation 0 Commits 1 Files Changed 9
+480 -43

1 Commits

Author SHA1 Message Date
hurui200320 88ca16e238 feat(public-api): expose all router-facing APIs at cleveractors package level; update README
CI / quality (pull_request) Successful in 34s
Details
CI / lint (pull_request) Failing after 38s
Details
CI / unit_tests (pull_request) Failing after 39s
Details
CI / build (pull_request) Successful in 40s
Details
CI / typecheck (pull_request) Successful in 1m6s
Details
CI / security (pull_request) Successful in 1m4s
Details
CI / coverage (pull_request) Has been skipped
Details
CI / integration_tests (pull_request) Successful in 1m5s
Details
CI / status-check (pull_request) Failing after 3s
Details 
Added 'Router-facing API' section to README.md documenting all 8 router-facing
exports introduced in waves C1–C7: validate_dict, merge_configs, create_executor,
Executor, ActorResult, NodeUsage, ExecutionError, and ConfigurationError.

The new section includes:
- A summary table listing each export with a one-line description.
- A complete end-to-end usage example following the ADR-2024 API contract
  (validate_dict → merge_configs → create_executor → execute → bill from nodes).
  The example now defines actor_yaml_text as a placeholder to avoid an undefined
  variable reference.
- Individual subsections for each API with focused code snippets.
- Streaming documentation for Executor.execute_stream() and last_result,
  including explicit notes on early-abandonment (last_result stays None) and
  ExecutionError partial-result billing semantics.
- Documentation of the state= input parameter for stateless graph resumption
  (execute(message, state=prev_result.state)).
- A reference table for ExecutionError.kind and .reason values with recommended
  HTTP status codes per ADR-2029.

'Package structure' table updated to list all new v2.1.0 exports, including
NodeType in the cleveractors.langgraph row (previously omitted).

'Key exports' section reorganised to show the router-facing surface first, then
the legacy CLI-facing surface, then sub-module imports for advanced use.
TemplateRegistry is now re-exported from cleveractors.templates.__init__ so the
Key exports import block is runnable without ImportError.

ADR citation on create_executor corrected: the executor-per-request pattern is
ADR-2024 (Library API Contract), not ADR-2026 (per-request credential injection).

Also fixed a pre-existing test-isolation bug in features/environment.py:
ReactiveCleverAgentsApp.__init__ sets the root logger level globally (verbose=0
→ CRITICAL, verbose=1 → ERROR, etc.). Under slipcover, this contaminated
subsequent scenarios that relied on WARNING-level log records propagating to the
root logger (execute_stream.feature:192–225). The fix saves and restores the root
logger level across each scenario via before_scenario/after_scenario hooks.
The save is now the very first statement in before_scenario and the restore is
the very first action in after_scenario, making the isolation guarantee
independent of any exception in the surrounding setup/teardown code.

A follow-up issue (#49) has been filed to address the production-side root cause
in ReactiveCleverAgentsApp.__init__ (move verbosity logic to a child logger).

All 2596 BDD scenarios and 227 Robot integration tests pass; coverage 96.8%.

ISSUES CLOSED: #17
 2026-06-12 19:57:16 +00:00