Metadata-Version: 2.4
Name: legio
Version: 0.1.3
Summary: Queue-based agentic orchestration engine (domain-free library).
Keywords: agents,orchestration,workflow,queue,beaver,polling
Author: GIA-UH — Grupo de Inteligencia Artificial, Universidad de La Habana, Syalia S.R.L.
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Dist: beaver-db>=2.4,<3
Requires-Dist: lingo-ai>=2.1,<3
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: httpx
Requires-Dist: typer
Requires-Python: >=3.13
Project-URL: Repository, https://github.com/gia-uh/legio
Project-URL: Changelog, https://github.com/gia-uh/legio/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/gia-uh/legio/issues
Description-Content-Type: text/markdown

# 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

```bash
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](LICENSE) file for details.