Getting started

Install

# Editable, with all dev tooling and the SQLite extra
pip install -e ".[dev,sqlite]"

# Run the test suite (371 cases)
pytest

# Run benchmarks
python -m benchmarks --tier 1

A minimal example

Wire the engines against an InMemoryStorage, seed an integrity value, and ask the alignment engine about a candidate action. The example below imports all six engines for completeness; a Tier 1-only host can drop BeliefsEngine / PurposeEngine (Tier 2) and DesiresEngine / GoalsEngine (Tier 3) — they ship as optional extensions per ADR-011 Decision 2. Self-Concept remains opt-in; this example skips it.

import asyncio
from agent_values import (
    AlignmentEngine, BeliefsEngine, DesiresEngine,
    GoalsEngine, PurposeEngine, ValuesEngine,
)
from agent_values.storage import InMemoryStorage
from agent_values.values import ValueCategory

async def main() -> None:
    storage = InMemoryStorage()
    values = ValuesEngine(storage=storage)
    beliefs = BeliefsEngine(storage=storage)
    purpose = PurposeEngine(storage=storage)
    desires = DesiresEngine(storage=storage)
    goals = GoalsEngine(storage=storage)
    alignment = AlignmentEngine(values, beliefs, purpose, desires, goals)

    integrity = await values.add(
        "integrity", weight=0.95,
        category=ValueCategory.INTEGRITY,
        description="Be truthful and transparent.",
    )
    integrity.aligned_keywords = ["disclose", "transparent"]
    integrity.conflict_keywords = ["mislead", "deceive"]
    await storage.set(
        f"{values.STORAGE_PREFIX}{integrity.id}",
        integrity.model_dump(mode="json"),
    )

    await purpose.set_primary(
        "Help operators ship reliably without surprising them.",
        role="autonomous_assistant",
        grounded_in_values=[integrity.id],
    )

    report = await alignment.check_alignment(
        {"description": "mislead the operator about progress",
         "tags": ["autonomous_assistant"]},
    )
    print("aligned:", report.aligned, "rationale:", report.rationale)

asyncio.run(main())

Operational CLI

For first-boot scaffolding the framework ships python -m agent_values:

python -m agent_values init                  # writes agent.json
python -m agent_values seed                  # populate default values/purpose/goal
python -m agent_values audit --json          # full_audit, machine-readable

Where to go next

• Architecture — engines, events, storage Protocol.
• Data model — every Pydantic model with fields and relations.
• Integration — adapters for Postgres/Redis, async/sync hosts, decision-loop recipe.
• Research — the academic grounding for each layer.