PRAXO-CORE: Python Agent Framework

PRAXO-CORE is a dependency-free Python framework for building tool-using AI agents. It provides the agent runtime, not a model or hosted service, so you keep control of your models, tools, storage, and sandboxing.

It is for teams that want a small, explicit agent loop instead of a large orchestration platform:

• Async-first models, tools, events, and sessions.
• Policy hooks, approvals, path checks, PII redaction, and call limits.
• Context budgets, checkpoints, middleware, and fallback models.
• Streaming, cancellation, and an OpenAI-compatible adapter.
• No runtime dependencies; Python 3.11 or newer.

Registry and Coding-Agent Entry

• Registry introduction: REGISTRY.md
• Machine-readable entry: llms.txt and llms.md
• Coding-agent contract: docs/getting-started/coding-agents.md
• Registry: PyPI

Install

pip install praxo-core==0.3.2

For a source checkout:

pip install ./language/python

Quickstart

For a complete application with explicit tool scope, policy denial tests, and virtual-environment package checks, use the independent Python consumer.

import asyncio

from praxo.agent import Agent, AgentOptions, Session
from praxo.event import Event
from praxo.model import Message, Response, Usage
from praxo.tool import FuncTool, Registry


class EchoModel:
    async def generate(self, request):
        return Response(message=Message(role="assistant", content="hello"))


class LogSink:
    async def emit(self, event: Event) -> None:
        print(event.to_wire())


async def main() -> None:
    tools = Registry()
    tools.register(FuncTool("echo", "Echo input", lambda args: args))
    agent = Agent(
        AgentOptions(model=EchoModel(), tools=tools, events=LogSink())
    )
    result = await agent.run(Session(id="session-1"), "hi")
    print(result.output, result.steps, result.usage)


asyncio.run(main())

What you get

Contract and status

The normative contract is spec/; Go remains the reference implementation. This package supports SPEC_VERSION 0.2.0 and passes all eleven conformance vector groups. Source version 0.3.2 is released from tag python/v0.3.2; the PyPI package is published by that tag. VFS and plugin hosts are not yet implemented.

Requirements

• Python 3.11 or newer
• No runtime dependencies

Contract Surface

Wire codecs preserve the Go names, including image_url, runId, contentBlocks, and plugin plugin_id.

Conformance

From this directory:

python conformance/run.py
python -m unittest discover -s tests -v

Both commands read ../../spec/vectors/*.json. A released Core implementation must pass every vector and keep spec/parity.md current.

API Reference and Build

See API.md. Refresh the checked-in symbol snapshot after a public API change:

python api-snapshot.py
python api-snapshot.py --check
python api-signatures.py --check
python -m build --wheel --sdist .

The name snapshot and signature snapshot are checked independently. The signature baseline covers class constructors, dataclass fields/defaults, methods, properties, functions, and exported constants. Both are source-API gates, not runtime or ABI guarantees.

CI installs the built wheel and sdist into separate clean virtual environments and runs tests/installed_smoke.py from outside the source tree. This verifies the packaged artifacts, not the checkout. It does not prove PyPI publication or installation from a package registry.

License

MIT. See LICENSE.