PRAXO-CORE Python Core

Python implementation of the PRAXO-CORE contract. The normative contract is spec/; Go remains the reference implementation.

Status: Core plus streaming, context management, middleware, and an OpenAI-compatible adapter. The package passes all eleven conformance vector groups. VFS and plugin hosts are not yet implemented. Wheel and sdist are published to PyPI.

Package version: 0.2.3; source tag python/v0.2.3. Supported contract: SPEC_VERSION 0.2.0 (praxo.SPEC_VERSION).

Requirements

• Python 3.11 or newer
• No runtime dependencies

Install

pip install praxo-core==0.2.3

For a source checkout:

pip install ./language/python

Usage

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())

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.