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.

Install

pip install praxo-core==0.3.0

For a source checkout:

pip install ./language/python

Quickstart

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.0 is published from tag python/v0.3.0; 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.