Add examples/ directory with a calculator actor example demonstrating cleveractors-core usage #148

New issue

Open

opened 2026-08-25 13:51:55 +00:00 by CoreRasurae · 0 comments

CoreRasurae commented

2026-08-25 13:51:55 +00:00

Member

Metadata

Commit Message: feat(examples): add calculator actor example demonstrating registry-based library usage
Branch: feature/m1-calculator-actor-example

Background and context

cleveractors-core has no examples/ directory, so there is no runnable,
end-to-end demonstration of how a host application is expected to use the
library: resolving a local: package reference through LocalPackageStore /
PackageContentResolver, building an executor from a graph specification, and
running an LLM actor with skills and tools attached.

Current behavior

No examples/ directory exists in the repository.
There is no CLI harness, actor configuration, or skill package checked into
version control that demonstrates end-to-end usage of the library, and no
README walking through it.

Expected behavior

An examples/ directory exists at the repository root (per the project's
file-organization rules), containing one canonical, self-contained example:
- A CLI harness that resolves a local: package reference and runs an
  actor built from it.
- One actor configuration (YAML) for a small "Calculator App Builder" LLM
  actor that writes a Tkinter calculator application to disk.
- The skill package the actor depends on (e.g. a programming-patterns
  skill), plus any packaging/validation tooling genuinely needed to build
  or validate that package.
- A README describing what the example demonstrates and the exact steps to
  run it (local package store layout, required env vars, invocation
  command).

Acceptance criteria

examples/ exists at the repository root and contains the CLI harness, the
actor configuration, the skill package it depends on, and a README.
Running the documented command in the README successfully resolves the
local: package reference via LocalPackageStore/PackageContentResolver
and builds an executor from the actor graph without error.
No editor backup files or log files are present under examples/.
nox -s lint and nox -s typecheck pass on the example's Python files.

Supporting information

None.

Subtasks

Create the examples/ directory per the project's file-organization rules.
Add a CLI harness to examples/ that resolves a local: package
reference and runs the actor built from it.
Author one canonical actor configuration YAML for the Calculator App
Builder actor in examples/.
Add the skill package the actor depends on (and any packaging/
validation scripts genuinely needed) to examples/.
Write a README for the example (purpose, prerequisites, exact run steps).
Verify the example runs end-to-end against a local package store.
Run nox -s lint and nox -s typecheck on the new files, fix any errors.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line matches the Commit Message in
Metadata exactly.
The commit is pushed to the branch matching the Branch in Metadata exactly.
The commit is submitted as a PR to master, reviewed, and merged.

## Metadata Commit Message: feat(examples): add calculator actor example demonstrating registry-based library usage Branch: feature/m1-calculator-actor-example ## Background and context `cleveractors-core` has no `examples/` directory, so there is no runnable, end-to-end demonstration of how a host application is expected to use the library: resolving a `local:` package reference through `LocalPackageStore` / `PackageContentResolver`, building an executor from a graph specification, and running an LLM actor with skills and tools attached. ## Current behavior - No `examples/` directory exists in the repository. - There is no CLI harness, actor configuration, or skill package checked into version control that demonstrates end-to-end usage of the library, and no README walking through it. ## Expected behavior - An `examples/` directory exists at the repository root (per the project's file-organization rules), containing one canonical, self-contained example: - A CLI harness that resolves a `local:` package reference and runs an actor built from it. - One actor configuration (YAML) for a small "Calculator App Builder" LLM actor that writes a Tkinter calculator application to disk. - The skill package the actor depends on (e.g. a `programming-patterns` skill), plus any packaging/validation tooling genuinely needed to build or validate that package. - A README describing what the example demonstrates and the exact steps to run it (local package store layout, required env vars, invocation command). ## Acceptance criteria - `examples/` exists at the repository root and contains the CLI harness, the actor configuration, the skill package it depends on, and a README. - Running the documented command in the README successfully resolves the `local:` package reference via `LocalPackageStore`/`PackageContentResolver` and builds an executor from the actor graph without error. - No editor backup files or log files are present under `examples/`. - `nox -s lint` and `nox -s typecheck` pass on the example's Python files. ## Supporting information None. ## Subtasks - [ ] Create the `examples/` directory per the project's file-organization rules. - [ ] Add a CLI harness to `examples/` that resolves a `local:` package reference and runs the actor built from it. - [ ] Author one canonical actor configuration YAML for the Calculator App Builder actor in `examples/`. - [ ] Add the skill package the actor depends on (and any packaging/ validation scripts genuinely needed) to `examples/`. - [ ] Write a README for the example (purpose, prerequisites, exact run steps). - [ ] Verify the example runs end-to-end against a local package store. - [ ] Run `nox -s lint` and `nox -s typecheck` on the new files, fix any errors. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the first line matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching the Branch in Metadata exactly. - The commit is submitted as a PR to master, reviewed, and merged.

Rows
Columns