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
toolandlinguisticagents materialized at boot, and unifiedcompositeagents whose branches reference other agents by name (the built-in composite build merges the branch payloads under the composite'soutput_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 serverandlegio agent <verb>CLI. - Federation: per-node catalogs, roster-based step routing over a beaver
routing proxy, an inbound peer allowlist (
federation.allowlist,403for 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.
Metadata
Release files for legio 0.1.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| legio-0.1.7.tar.gz | 112.3 kB | Without provenance | Details for legio-0.1.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| legio-0.1.7-py3-none-any.whl | Python 3 | none | any | Details for legio-0.1.7-py3-none-any.whl |
Total release size: 243.3 kB
Release files / legio-0.1.7.tar.gz
| Download URL | legio-0.1.7.tar.gz |
|---|---|
| Size | 112.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e7ab828c640ee141b083747a96fe161bda45a38f703bbcf9e2da37a314f61208
|
|
BLAKE2b-256 checksum How to use checksums |
28645b7d7f7c5493be3a9dd088deaf7d08bb0fe3f236af5ffc4f87d939d8aa4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.10","id":"oracular","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / legio-0.1.7-py3-none-any.whl
| Download URL | legio-0.1.7-py3-none-any.whl |
|---|---|
| Size | 131.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
339ea44f266af56ef308cbc105d97e023ec01940330ba2437bb90a0778a465cf
|
|
BLAKE2b-256 checksum How to use checksums |
08986d8d7fb12b4115839c6472c72c708da65a5aab3028d5b03c621d8354b949
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.10","id":"oracular","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for legio 0.1.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.