praxo-core 0.2.1__tar.gz

praxo_core-0.2.1/API.md

@@ -0,0 +1,135 @@
+# Python API Reference
+
+Normative contract: [`spec/`](../../spec/README.md). This page lists the public
+Python surface. The checked-in snapshot is `api/<version>.txt`.
+
+## `praxo.model`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Model` | Async `generate(request) -> Response` protocol |
+| `StreamingModel` | Adds `generate_stream(request, on_delta)` |
+| `Provider` | Chat-oriented `chat` / `chat_stream` contract |
+| `ChatModel` | Adapts a `Provider` to `Model` |
+| `Message`, `ContentBlock`, `ToolCall`, `ToolSpec` | Wire-compatible model types |
+| `Request`, `Response`, `Usage` | Request/response envelopes |
+| `ResponseFormat`, `CacheHint` | Provider-neutral structured output and cache hints |
+
+## `praxo.tool`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Tool` | `name`, `description`, async `invoke(args)` |
+| `FuncTool` | Function-backed tool |
+| `Registry` | Name-indexed tool registry with sorted specs |
+| `Gateway`, `GatewayInfo`, `GatewayTool` | External tool gateway seam |
+
+## `praxo.event`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Event` | Lifecycle event envelope |
+| `Sink` | Async `emit(event)` |
+| `MultiSink` | Fail-fast fan-out |
+| `FilterSink` | Predicate-filtered forwarding |
+
+## `praxo.policy`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Hook`, `FuncHook` | Async authorization hook |
+| `Action`, `Decision` | Authorization input/output |
+| `PathGrant`, `PathChecker` | Deny-by-default filesystem containment |
+
+## `praxo.memory`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Store` | Async `put` / `search` contract |
+| `Record`, `Frame` | Typed memory record |
+| `MemoryStore` | In-memory store, newest-first search |
+| `ContextAssembler` | Query-relevant memory retrieval |
+
+## `praxo.checkpoint`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Checkpoint`, `Message`, `RunSnapshot`, `EffectCursor` | Durable snapshot types |
+| `Store` | Async checkpoint store contract |
+| `Allowlist` | Typed envelope marshal/unmarshal allowlist |
+
+## `praxo.context`
+
+| Symbol | Purpose |
+| --- | --- |
+| `ContextBudget` | Deterministic prompt compaction |
+| `estimate_tokens` | Provider-neutral token estimate |
+| `ContextCompactor`, `ModelSummarizer` | Optional summarization pass |
+| `Offloader`, `OffloadFunc` | Large tool-result offload seam |
+| `load_agents_md` | Bounded `AGENTS.md` loading |
+| `MaxAgentsMDBytes` | Combined AGENTS.md limit |
+
+## `praxo.middleware`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Middleware`, `ModelCall`, `ToolCall`, `ToolResult`, `RunState` | Middleware contracts |
+| `call_limit_middleware` | Per-run model/tool call budgets |
+| `fallback_model` | Fallback model middleware |
+| `PIIRedactor`, `PIIRule`, `default_pii_rules`, `pii_middleware` | PII redaction |
+| `StructuredOutput` | JSON schema binding, validation, repair |
+| `ToolSelector`, `ModelToolSelector`, `tool_selection_middleware` | Per-run tool narrowing |
+
+## `praxo.agent`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Agent` | Governed async agent loop |
+| `AgentOptions` | Model, tools, events, policy, context, middleware, limits |
+| `Session`, `Result` | Run scope and outcome |
+
+## `praxo.toolcall`
+
+| Symbol | Purpose |
+| --- | --- |
+| `parse_tool_call` | Parse supported model tool-call formats |
+| `strip_tool_call_markup` | Remove recognized tool-call markup |
+| `parse_input_json` | Tolerant JSON object parsing |
+
+## `praxo.jsonschema`
+
+| Symbol | Purpose |
+| --- | --- |
+| `Schema`, `ValidationError` | Documented JSON Schema subset |
+| `from_json`, `validate` | Parse and validate helpers |
+
+## `praxo.plugin`
+
+| Symbol | Purpose |
+| --- | --- |
+| `parse_manifest` | Strict Manifest v1 parse and validation |
+| `validate_trust` | Signed/unsigned trust profile |
+| `KINDS`, `STATES`, `EVENT_KINDS`, `CALL_ERROR_CODES` | Frozen enums |
+
+## `praxo.adapters.openaicompat`
+
+| Symbol | Purpose |
+| --- | --- |
+| `OpenAIConfig` | Base URL, key, model, timeout, headers |
+| `OpenAICompatibleModel` | Non-streaming and SSE streaming adapter |
+
+## Snapshot
+
+```bash
+python api-snapshot.py
+python api-snapshot.py --check
+python api-signatures.py
+python api-signatures.py --check
+```
+
+`api/<version>.txt` records exported names and top-level function signatures.
+`api/<version>.signatures.txt` adds class constructors, dataclass fields and
+defaults, methods, properties, functions, and exported constants. The signature
+snapshot was added after `0.2.0`; it does not rewrite the historical name
+snapshot or imply that the released package already contained this gate. It is a
+source-API check, not a runtime, serializer, or ABI guarantee.

praxo_core-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AxisVela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

praxo_core-0.2.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include API.md
+recursive-include api *.txt
+recursive-include conformance *.py
+recursive-include tests *.py

praxo_core-0.2.1/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: praxo-core
+Version: 0.2.1
+Summary: Python SDK for the PRAXO-CORE agent contract
+Author: AxisVela
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/axisvela/praxo-core
+Project-URL: Documentation, https://axisvela.github.io/praxo-core/languages/python/
+Project-URL: Source, https://github.com/axisvela/praxo-core/tree/main/language/python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PRAXO-CORE Python SDK
+
+Python implementation of the PRAXO-CORE contract. The normative contract is
+[`spec/`](../../spec/README.md); 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 builds are
+verified; PyPI publication is pending. Use the source installation below.
+
+Package version: `0.2.1` source candidate; the latest released source tag is
+`python/v0.2.0`. Supported contract: `SPEC_VERSION` `0.2.0`
+(`praxo.SPEC_VERSION`).
+
+## Requirements
+
+- Python 3.11 or newer
+- No runtime dependencies
+
+## Install
+
+```bash
+pip install ./language/python
+```
+
+## Usage
+
+```python
+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
+
+| Module | Contract |
+| --- | --- |
+| `praxo.model` | `Model`, `Request`, `Response`, messages, tool specs, usage |
+| `praxo.tool` | `Tool`, `Registry`, `FuncTool` |
+| `praxo.event` | `Event`, `Sink`, `MultiSink`, `FilterSink` |
+| `praxo.policy` | `Hook`, `Action`, `Decision`, `PathChecker` |
+| `praxo.memory` | `Store`, `Record`, `MemoryStore`, `ContextAssembler` |
+| `praxo.checkpoint` | `Checkpoint`, `Allowlist` |
+| `praxo.agent` | `Agent`, `AgentOptions`, `Session`, `Result` |
+| `praxo.context` | `ContextBudget`, `ModelSummarizer`, `Offloader`, `load_agents_md` |
+| `praxo.middleware` | call limits, fallback, PII, structured output, tool selection |
+| `praxo.toolcall` | `parse_tool_call`, `strip_tool_call_markup` |
+| `praxo.jsonschema` | `Schema`, `ValidationError` |
+| `praxo.plugin` | Manifest v1 parsing and validation |
+
+Wire codecs preserve the Go names, including `image_url`, `runId`,
+`contentBlocks`, and plugin `plugin_id`.
+
+## Conformance
+
+From this directory:
+
+```bash
+python conformance/run.py
+python -m unittest discover -s tests -v
+```
+
+Both commands read `../../spec/vectors/*.json`. A released SDK must pass every
+vector and keep `spec/parity.md` current.
+
+## API Reference and Build
+
+See [API.md](API.md). Refresh the checked-in symbol snapshot after a public API
+change:
+
+```bash
+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](../../LICENSE).

praxo_core-0.2.1/README.md

@@ -0,0 +1,117 @@
+# PRAXO-CORE Python SDK
+
+Python implementation of the PRAXO-CORE contract. The normative contract is
+[`spec/`](../../spec/README.md); 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 builds are
+verified; PyPI publication is pending. Use the source installation below.
+
+Package version: `0.2.1` source candidate; the latest released source tag is
+`python/v0.2.0`. Supported contract: `SPEC_VERSION` `0.2.0`
+(`praxo.SPEC_VERSION`).
+
+## Requirements
+
+- Python 3.11 or newer
+- No runtime dependencies
+
+## Install
+
+```bash
+pip install ./language/python
+```
+
+## Usage
+
+```python
+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
+
+| Module | Contract |
+| --- | --- |
+| `praxo.model` | `Model`, `Request`, `Response`, messages, tool specs, usage |
+| `praxo.tool` | `Tool`, `Registry`, `FuncTool` |
+| `praxo.event` | `Event`, `Sink`, `MultiSink`, `FilterSink` |
+| `praxo.policy` | `Hook`, `Action`, `Decision`, `PathChecker` |
+| `praxo.memory` | `Store`, `Record`, `MemoryStore`, `ContextAssembler` |
+| `praxo.checkpoint` | `Checkpoint`, `Allowlist` |
+| `praxo.agent` | `Agent`, `AgentOptions`, `Session`, `Result` |
+| `praxo.context` | `ContextBudget`, `ModelSummarizer`, `Offloader`, `load_agents_md` |
+| `praxo.middleware` | call limits, fallback, PII, structured output, tool selection |
+| `praxo.toolcall` | `parse_tool_call`, `strip_tool_call_markup` |
+| `praxo.jsonschema` | `Schema`, `ValidationError` |
+| `praxo.plugin` | Manifest v1 parsing and validation |
+
+Wire codecs preserve the Go names, including `image_url`, `runId`,
+`contentBlocks`, and plugin `plugin_id`.
+
+## Conformance
+
+From this directory:
+
+```bash
+python conformance/run.py
+python -m unittest discover -s tests -v
+```
+
+Both commands read `../../spec/vectors/*.json`. A released SDK must pass every
+vector and keep `spec/parity.md` current.
+
+## API Reference and Build
+
+See [API.md](API.md). Refresh the checked-in symbol snapshot after a public API
+change:
+
+```bash
+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](../../LICENSE).