legio

A queue-based agentic orchestration engine. Independent library, domain-free: all domain knowledge lives in patterns (YAML as data) and a tool registry provided by the consumer. The library never knows about any specific consumer; validation happens through the in-repo examples (examples/) and external consumer repositories kept separate (AGENTS.md rule 7).

Quick start

uv run legio server --config examples/transform/legio.yaml --host 127.0.0.1 --port 8000

Then submit and poll status (see docs/CONSUMER_GUIDE.md for the full walkthrough; the headless transform example boots with no LLM needed and runs from the repo root).

Docs surface

• docs/CONSUMER_GUIDE.md — executable walkthrough: register a tool → write a pattern → configure → boot → submit → status (validated by CI).
• docs/GLOSSARY.md — canonical definitions for the identifiers and architecture terms.
• docs/ARCHITECTURE.md — the architecture (read before any work).
• docs/AGENT_LIFECYCLE.md — the class/instance lifecycle (§4.8) and the three schemas (§4.11).
• docs/CONTRIBUTING.md — methodology, development flow, review checklist.
• docs/PLAN.md — the plan and issue roadmap; docs/CONTRACTS/ holds the per-issue approved specs.
• docs/DEPENDENCIES.md — the approved dependency list.
• docs/JOURNALS/ — turn-by-turn journaling; read the latest before working.

Examples

examples/ ships five self-contained, domain-free example nodes — each with its own patterns/ (Schema 1 YAML), tools.yaml (Schema 3), node-local tools.py and legio.yaml (LEG-017): transform, summarize, extract-and-summarize, distribute-summary and document_processing. Each node is copy-and-adapt: its relative paths resolve against its own legio.yaml and its tools resolve beside it, so the quick-start command runs from the repo root unchanged. The same files are exercised by the test suite — drift breaks the build (LEG-100, no bitrot; LEG-104 boots the shipped config as a subprocess).

Engine in one breath

The public API never pushes (polling only, next_run_at scheduling): the host drives runtime.manager.run() one pass per dispatch; each standing agent polls its own beaver queue; the immutable Schema 2 FlowToken (schema_version, level_route, current_index, end_of_level_queue, level, launcher_class, task_id, branch_id, root) travels the routes (payload and message_type live on the ExecutionRequest/ExecutionResult messages, not on the token); the final result lands on the agent's shared final-result queue and is collected into the task's outbox record that /status reads. Errors are typed (legio.errors) and never silent (rule 9); every module logs structured key=value events under the legio.* tree (rule 11).

Core capabilities (current)

• Schemas: S1 one-spec-per-pattern YAML with mandatory symmetric contracts; S2 the route token; S3 available_tools (implementation + policy).
• Standing agents: atomic tool and linguistic agents materialized at boot, and unified composite agents whose branches reference other agents by name (the built-in composite build merges the branch payloads under the composite's output_as; a non-merge composition overrides the seam).
• Dynamic lifecycle: class/instance verbs (create/enable/disable/destroy), pools as capacity intent, bring-up leaves-first over the served catalog.
• Runtime surface: REST submit/status plus class/instance verb classes over beaver queues with a client token store; legio server and legio agent <verb> CLI.
• Federation: per-node catalogs, roster-based step routing over a beaver routing proxy, an inbound peer allowlist (federation.allowlist, 403 for an unknown peer) — peers never widen scope (rule 9).

State

R-0..R-9 core is shipped on the three-schema, decoupled polling engine (exact per-issue status lives in docs/CONTRACTS/ and docs/JOURNALS/). R-10 (Hardening & release) is the current track: the LEG-103 audit-hardening series (contract-first slices, all green) and this session's LEG-100 docs & examples hardening (consumer guide + glossary + example tree) await maintainer review; LEG-101 (semver, packaging, changelog, tags) and LEG-102 come next on the release track.

Development

make ci mirrors the CI gate exactly: lint (ruff check) + format check (ruff format --check) + typecheck (pyright) + full pytest, all green. Convenience targets: make sync, make lint, make format, make format-check, make typecheck, make test, make build (wheel/archive), make validate-release (release-artifact smoke), make clean, make tag/make release (maintainer only; release runs release-guard first). Everything in this repo is English (AGENTS.md rule 1); work is per-issue, contract-first, and every turn ends with a journal commit.

Developed By

Legio is a collaborative open-source project co-developed by:

• GIA-UH — Grupo de Inteligencia Artificial, Universidad de La Habana
• Syalia S.R.L.

License

This project is licensed under the MIT License. See the LICENSE file for details.