feat(actor): add actor registry and loader #294

Closed
opened 2026-02-22 23:41:00 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit: feat(actor): add actor registry and loader
  • Branch: develop-aditya

Subtasks

  • Implement actor loader/registry with namespaced lookup, cache invalidation, and file discovery in actors/ and examples/actors/.
  • Normalize actor file paths, reject non-.yaml files, and emit a single consolidated error when duplicates are found across search roots.
  • Store and compare a content hash for actor configs to avoid reloading unchanged actors (mtime + hash fallback).
  • Add registry integration with Tool Registry so tool nodes resolve at load time.
  • Validate actor namespaced names on load and apply default local/ when namespace omitted.
  • Add docs/reference/actors_loading.md with discovery rules and namespaces.
  • Tests (Behave): Add features/actor_loading.feature for discovery, duplicates, and namespace lookup.
  • Tests (Robot): Add robot/actor_loading.robot for loader smoke tests.
  • Tests (ASV): Add benchmarks/actor_loading_bench.py for registry load performance.
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
  • Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Section: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead]
Status: Completed

## Metadata - **Commit**: `feat(actor): add actor registry and loader` - **Branch**: `develop-aditya` ## Subtasks - [x] Implement actor loader/registry with namespaced lookup, cache invalidation, and file discovery in `actors/` and `examples/actors/`. - [x] Normalize actor file paths, reject non-`.yaml` files, and emit a single consolidated error when duplicates are found across search roots. - [x] Store and compare a content hash for actor configs to avoid reloading unchanged actors (mtime + hash fallback). - [x] Add registry integration with Tool Registry so tool nodes resolve at load time. - [x] Validate actor namespaced names on load and apply default `local/` when namespace omitted. - [x] Add `docs/reference/actors_loading.md` with discovery rules and namespaces. - [x] Tests (Behave): Add `features/actor_loading.feature` for discovery, duplicates, and namespace lookup. - [x] Tests (Robot): Add `robot/actor_loading.robot` for loader smoke tests. - [x] Tests (ASV): Add `benchmarks/actor_loading_bench.py` for registry load performance. - [ ] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. **Section**: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead] **Status**: Completed
freemo added this to the v3.1.0 milestone 2026-02-22 23:41:00 +00:00
Author
Owner

Implementation Notes — C2.loader: Actor Registry and Loader

2026-02-19: Task C2.loader Complete - Actor Registry and Loader

  • Created src/cleveragents/actor/loader.py (277 lines) — ActorLoader class with thread-safe discovery, SHA-256 content-hash caching, and namespace management.
  • 23 Behave scenarios, 4 Robot test cases, 4 ASV benchmarks. Coverage: 98%.
  • Key design decisions: SHA-256 content hashing (not mtime) for deterministic cache invalidation, single consolidated ValidationError for duplicates/errors, tool reference resolution at load time via optional ToolRegistry, local/ default namespace applied during YAML parsing.

(Migrated from docs/implementation-notes.md)

## Implementation Notes — C2.loader: Actor Registry and Loader **2026-02-19**: Task C2.loader Complete - Actor Registry and Loader - Created `src/cleveragents/actor/loader.py` (277 lines) — `ActorLoader` class with thread-safe discovery, SHA-256 content-hash caching, and namespace management. - 23 Behave scenarios, 4 Robot test cases, 4 ASV benchmarks. Coverage: 98%. - Key design decisions: SHA-256 content hashing (not mtime) for deterministic cache invalidation, single consolidated `ValidationError` for duplicates/errors, tool reference resolution at load time via optional `ToolRegistry`, `local/` default namespace applied during YAML parsing. *(Migrated from `docs/implementation-notes.md`)*
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#354 Epic: Actor & Skill Schema + CLI (C0)
cleveragents/cleveragents-core
Depends on
#126 develop-aditya
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#294
No description provided.