System on an Agent
Instead of system on a chip, system on an agent.
A system on a chip,
but on an agent.
A system on a chip puts a CPU, memory, I/O, and a bus on one piece of silicon. A system on an agent puts the same parts into one agent: a planner as the processor, memory and skills as storage, connectors as input and output, and a bus that ties them together.
The same blocks, retitled
The floorplan stays the same. Each SoC block has a counterpart on the agent.
- CPUPlanner
- MemoryMemory + Skills
- I/OConnectors
- BusBus / Router
The core
Four parts, and only these four. Optional add-ons plug in later, beside the core, never into it.
Processor
Planner
Takes a goal, builds a plan, and runs it step by step. The default planner is deterministic and rule-based; no language model is required. An optional language-model provider can be attached later. If the model fails to return a valid plan, the rule-based planner is the fallback.
Storage
Memory and skills
Working memory holds short-lived values for the current run. Long-term memory stores facts, optionally persisted as JSON. The skill library is a set of reusable named procedures the planner can run.
Input / output
Connectors
A pluggable I/O surface. The core ships a local file connector and an echo (mock) connector, and new connectors can be registered on the same interface.
Interconnect
Bus / Router
Routes messages between the planner, memory, skills, and connectors, and fires add-on hooks around each step without those add-ons living in the core.
Quickstart
Python 3.10 or newer. The demo below is a real run of the mock connector, from the core on this repository.
$ python -m pip install -e ".[dev]"
$ soa run "echo hello from system on an agent"
goal: echo hello from system on an agent
plan: 1 step (rules)
1. Send "hello from system on an agent" through the echo connector
ok: true
output: hello from system on an agent
Also available: soa skills list and soa connectors list.
Optional add-ons
Add-ons sit beside the core. They never live inside it, and loading or omitting
them does not require a core change. Load one from a Python file or a directory
with soa_addon.py or addon.py. It declares a manifest
and the hooks it implements.
soa --addon path/to/addon.py run "echo hello"
before_plan(plan, context)
after_plan(plan, report, context)
before_step(step, context)
after_step(step, result, context)
on_error(step, error, context)
Two names are reserved for later work. They are documented as placeholders only: there is no implementation and no dependency for either one in the core.
Future add-on
heatgate
Power throttling from measured temperature and grid readings. A future
heatgate add-on would hook before_step to pause, delay, or skip
work when those readings are high. It would be optional power management,
not part of the processor, storage, or I/O of the agent itself.
Future add-on
lex-loop
An 8-step robot loop (READ → RESTART) used as a clock. A future lex-loop add-on would hook plan execution so each tick advances one phase of that loop. It would be an optional clock, not part of the core planner.
Get started
Clone the repository, install the package, and run a goal through the mock connector.
Planner
The processor. It turns a goal into a plan and runs it step by step, with no language model required.
Memory and skills
Storage for the run, long-term facts, and a library of reusable named procedures.
Connectors
Pluggable input and output, including a local file connector and an echo (mock) connector.
Bus / Router
The interconnect that routes messages between the other parts and fires add-on hooks.