elkpi-oxa 1.0.0__tar.gz

elkpi_oxa-1.0.0/.gitignore

@@ -0,0 +1,45 @@
+# Go artifacts (per-language, under go/)
+go/bin/
+go/dist/
+go/vendor/
+go/*.test
+go/*.exe
+go/go.work.sum
+
+# Test and coverage artifacts
+*.out
+*.test
+coverage.txt
+coverage.html
+*.prof
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store
+*.swp
+*.swo
+*~
+
+# veccheck binary (built locally, never committed)
+go/veccheck
+
+# Rust artifacts (per-language, under rust/)
+/rust/target/
+rust/**/*.rs.bk
+
+# Python artifacts (per-language, under python/)
+python/.venv/
+python/**/__pycache__/
+python/**/*.py[cod]
+python/.pytest_cache/
+python/.mypy_cache/
+python/.ruff_cache/
+python/dist/
+python/build/
+python/*.egg-info/
+
+# C++ artifacts (per-language, under cpp/)
+cpp/build/
+cpp/Testing/
+

elkpi_oxa-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: elkpi-oxa
+Version: 1.0.0
+Summary: Pure, in-process protocol-conversion library for OpenAI and Anthropic
+Author: oxa contributors
+License-Expression: Apache-2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# oxa — Python Reference Implementation
+
+Pure, in-process protocol-conversion library for OpenAI Chat Completions,
+OpenAI Responses, and Anthropic Messages in Python.
+
+Like the Go and Rust implementations, oxa in Python is not a proxy, HTTP
+client, router, retry layer, authentication service, or model capability
+database. It provides deterministic, pure conversions between protocol wire
+structures and oxa's shared Intermediate Representation (IR).
+
+## Architecture
+
+- **Hub-and-spoke**: Spoke packages (`oxa.openai.chatcompletions`,
+  `oxa.openai.responses`, `oxa.anthropic.messages`) implement only `face → IR`
+  and `IR → face`. No direct face-to-face conversions.
+- **Zero runtime dependencies**: Pure Python standard library only
+  (`dataclasses`, `typing`, `json`, `enum`, etc.).
+- **Opaque tool inputs (INV-1)**: Tool call arguments and streaming delta
+  fragments remain unparsed raw JSON text.
+- **Shared Golden Vectors**: Conforms to the exact same shared `vectors/` golden
+  suite as Go and Rust.
+
+## Installation
+
+```bash
+pip install elkpi-oxa
+```
+
+Import in Python:
+
+```python
+import oxa
+from oxa.openai.chatcompletions import decode_request
+```
+
+## Development
+
+The project uses [`uv`](https://docs.astral.sh/uv/) for development and
+environment management:
+
+```bash
+cd python
+
+# Sync virtualenv and development dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run mypy
+
+# Lint & format check
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## Vectors Location Convention
+
+Test harnesses locate the shared `vectors/` suite by walking up parent
+directories from `python/` until finding a directory containing both `vectors/`
+and `.git/`. Tests skip cleanly if the repository root is absent (e.g. when
+building a standalone package archive).

elkpi_oxa-1.0.0/README.md

@@ -0,0 +1,63 @@
+# oxa — Python Reference Implementation
+
+Pure, in-process protocol-conversion library for OpenAI Chat Completions,
+OpenAI Responses, and Anthropic Messages in Python.
+
+Like the Go and Rust implementations, oxa in Python is not a proxy, HTTP
+client, router, retry layer, authentication service, or model capability
+database. It provides deterministic, pure conversions between protocol wire
+structures and oxa's shared Intermediate Representation (IR).
+
+## Architecture
+
+- **Hub-and-spoke**: Spoke packages (`oxa.openai.chatcompletions`,
+  `oxa.openai.responses`, `oxa.anthropic.messages`) implement only `face → IR`
+  and `IR → face`. No direct face-to-face conversions.
+- **Zero runtime dependencies**: Pure Python standard library only
+  (`dataclasses`, `typing`, `json`, `enum`, etc.).
+- **Opaque tool inputs (INV-1)**: Tool call arguments and streaming delta
+  fragments remain unparsed raw JSON text.
+- **Shared Golden Vectors**: Conforms to the exact same shared `vectors/` golden
+  suite as Go and Rust.
+
+## Installation
+
+```bash
+pip install elkpi-oxa
+```
+
+Import in Python:
+
+```python
+import oxa
+from oxa.openai.chatcompletions import decode_request
+```
+
+## Development
+
+The project uses [`uv`](https://docs.astral.sh/uv/) for development and
+environment management:
+
+```bash
+cd python
+
+# Sync virtualenv and development dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run mypy
+
+# Lint & format check
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## Vectors Location Convention
+
+Test harnesses locate the shared `vectors/` suite by walking up parent
+directories from `python/` until finding a directory containing both `vectors/`
+and `.git/`. Tests skip cleanly if the repository root is absent (e.g. when
+building a standalone package archive).

elkpi_oxa-1.0.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "elkpi-oxa"
+version = "1.0.0"
+description = "Pure, in-process protocol-conversion library for OpenAI and Anthropic"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    { name = "oxa contributors" },
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oxa"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "N",   # pep8-naming
+    "W",   # pycodestyle warnings
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+]
+ignore = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["oxa"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["oxa"]
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

elkpi_oxa-1.0.0/src/oxa/__init__.py

@@ -0,0 +1,52 @@
+"""oxa — pure, in-process protocol-conversion library for OpenAI and Anthropic."""
+
+from oxa.ir import (
+    Block,
+    Event,
+    EventStream,
+    ImageBlock,
+    InputJsonDelta,
+    Loss,
+    Message,
+    MessageDelta,
+    MessageDone,
+    MessageStart,
+    Params,
+    Request,
+    Response,
+    TextBlock,
+    TextDelta,
+    Tool,
+    ToolChoice,
+    ToolResultBlock,
+    ToolUseBlock,
+    Usage,
+)
+from oxa.modelmap import Table
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "Request",
+    "Response",
+    "Message",
+    "Block",
+    "TextBlock",
+    "ImageBlock",
+    "ToolUseBlock",
+    "ToolResultBlock",
+    "Tool",
+    "ToolChoice",
+    "Params",
+    "Usage",
+    "Loss",
+    "Event",
+    "EventStream",
+    "MessageStart",
+    "MessageDelta",
+    "MessageDone",
+    "TextDelta",
+    "InputJsonDelta",
+    "Table",
+]

elkpi_oxa-1.0.0/src/oxa/anthropic/__init__.py

@@ -0,0 +1 @@
+"""Anthropic protocol faces."""

elkpi_oxa-1.0.0/src/oxa/anthropic/messages/__init__.py

@@ -0,0 +1,72 @@
+"""Anthropic Messages face implementation (spec/12)."""
+
+from oxa.anthropic.messages.constants import (
+    BLOCK_TYPE_IMAGE,
+    BLOCK_TYPE_TEXT,
+    BLOCK_TYPE_TOOL_RESULT,
+    BLOCK_TYPE_TOOL_USE,
+    DELTA_TYPE_INPUT_JSON_DELTA,
+    DELTA_TYPE_TEXT_DELTA,
+    EVENT_TYPE_CONTENT_BLOCK_DELTA,
+    EVENT_TYPE_CONTENT_BLOCK_START,
+    EVENT_TYPE_CONTENT_BLOCK_STOP,
+    EVENT_TYPE_MESSAGE_DELTA,
+    EVENT_TYPE_MESSAGE_START,
+    EVENT_TYPE_MESSAGE_STOP,
+    ROLE_ASSISTANT,
+    ROLE_USER,
+    SOURCE_TYPE_BASE64,
+    SOURCE_TYPE_URL,
+    STOP_REASON_END_TURN,
+    STOP_REASON_MAX_TOKENS,
+    STOP_REASON_REFUSAL,
+    STOP_REASON_STOP_SEQUENCE,
+    STOP_REASON_TOOL_USE,
+    TOOL_CHOICE_TYPE_ANY,
+    TOOL_CHOICE_TYPE_AUTO,
+    TOOL_CHOICE_TYPE_NONE,
+    TOOL_CHOICE_TYPE_TOOL,
+    TYPE_MESSAGE,
+)
+from oxa.anthropic.messages.decode import decode_request, decode_response
+from oxa.anthropic.messages.encode import encode_request, encode_response
+from oxa.anthropic.messages.streamin import StreamDecoder
+from oxa.anthropic.messages.streamout import StreamEncoder
+
+__all__ = [
+    # Constants
+    "ROLE_USER",
+    "ROLE_ASSISTANT",
+    "BLOCK_TYPE_TEXT",
+    "BLOCK_TYPE_IMAGE",
+    "BLOCK_TYPE_TOOL_USE",
+    "BLOCK_TYPE_TOOL_RESULT",
+    "SOURCE_TYPE_BASE64",
+    "SOURCE_TYPE_URL",
+    "TOOL_CHOICE_TYPE_AUTO",
+    "TOOL_CHOICE_TYPE_ANY",
+    "TOOL_CHOICE_TYPE_NONE",
+    "TOOL_CHOICE_TYPE_TOOL",
+    "STOP_REASON_END_TURN",
+    "STOP_REASON_MAX_TOKENS",
+    "STOP_REASON_STOP_SEQUENCE",
+    "STOP_REASON_TOOL_USE",
+    "STOP_REASON_REFUSAL",
+    "EVENT_TYPE_MESSAGE_START",
+    "EVENT_TYPE_CONTENT_BLOCK_START",
+    "EVENT_TYPE_CONTENT_BLOCK_DELTA",
+    "EVENT_TYPE_CONTENT_BLOCK_STOP",
+    "EVENT_TYPE_MESSAGE_DELTA",
+    "EVENT_TYPE_MESSAGE_STOP",
+    "DELTA_TYPE_TEXT_DELTA",
+    "DELTA_TYPE_INPUT_JSON_DELTA",
+    "TYPE_MESSAGE",
+    # Functions
+    "decode_request",
+    "decode_response",
+    "encode_request",
+    "encode_response",
+    # Streaming Classes
+    "StreamDecoder",
+    "StreamEncoder",
+]

elkpi_oxa-1.0.0/src/oxa/anthropic/messages/constants.py

@@ -0,0 +1,35 @@
+"""Anthropic Messages wire protocol constants (spec/12)."""
+
+ROLE_USER = "user"
+ROLE_ASSISTANT = "assistant"
+
+BLOCK_TYPE_TEXT = "text"
+BLOCK_TYPE_IMAGE = "image"
+BLOCK_TYPE_TOOL_USE = "tool_use"
+BLOCK_TYPE_TOOL_RESULT = "tool_result"
+
+SOURCE_TYPE_BASE64 = "base64"
+SOURCE_TYPE_URL = "url"
+
+TOOL_CHOICE_TYPE_AUTO = "auto"
+TOOL_CHOICE_TYPE_ANY = "any"
+TOOL_CHOICE_TYPE_NONE = "none"
+TOOL_CHOICE_TYPE_TOOL = "tool"
+
+STOP_REASON_END_TURN = "end_turn"
+STOP_REASON_MAX_TOKENS = "max_tokens"
+STOP_REASON_STOP_SEQUENCE = "stop_sequence"
+STOP_REASON_TOOL_USE = "tool_use"
+STOP_REASON_REFUSAL = "refusal"
+
+EVENT_TYPE_MESSAGE_START = "message_start"
+EVENT_TYPE_CONTENT_BLOCK_START = "content_block_start"
+EVENT_TYPE_CONTENT_BLOCK_DELTA = "content_block_delta"
+EVENT_TYPE_CONTENT_BLOCK_STOP = "content_block_stop"
+EVENT_TYPE_MESSAGE_DELTA = "message_delta"
+EVENT_TYPE_MESSAGE_STOP = "message_stop"
+
+DELTA_TYPE_TEXT_DELTA = "text_delta"
+DELTA_TYPE_INPUT_JSON_DELTA = "input_json_delta"
+
+TYPE_MESSAGE = "message"

elkpi_oxa-1.0.0/src/oxa/anthropic/messages/decode.py

@@ -0,0 +1,203 @@
+"""Anthropic Messages face → IR conversions (spec/12 §4)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from oxa.anthropic.messages.constants import (
+    ROLE_ASSISTANT as AN_ROLE_ASSISTANT,
+    ROLE_USER as AN_ROLE_USER,
+    STOP_REASON_END_TURN,
+    STOP_REASON_MAX_TOKENS,
+    STOP_REASON_REFUSAL,
+    STOP_REASON_STOP_SEQUENCE,
+    STOP_REASON_TOOL_USE,
+)
+from oxa.anthropic.messages.normalize import (
+    decode_block,
+    decode_content,
+    decode_system,
+    decode_tool_choice,
+    loss,
+    require_json_object,
+)
+from oxa.ir import (
+    LOSS_UNMAPPED_FIELD,
+    LOSS_UNMAPPED_VALUE,
+    ROLE_ASSISTANT,
+    ROLE_USER,
+    STOP_END_TURN,
+    STOP_MAX_TOKENS,
+    STOP_OTHER,
+    STOP_REFUSAL,
+    STOP_STOP_SEQUENCE,
+    STOP_TOOL_USE,
+    Block,
+    Loss,
+    Message as IrMessage,
+    Params,
+    Request,
+    Response,
+    Tool,
+    Usage,
+)
+from oxa.modelmap import Table
+
+
+def decode_request(
+    wire: dict[str, Any],
+    raw_text: str = "",
+    table: Table | None = None,
+) -> tuple[Request, list[Loss]]:
+    """Converts an Anthropic Messages wire request to the IR (face → IR)."""
+    losses: list[Loss] = []
+
+    max_tokens = wire.get("max_tokens")
+    if max_tokens is None or max_tokens <= 0:
+        raise ValueError("anthropic: max_tokens is required and must be positive")
+
+    if wire.get("metadata") is not None:
+        losses.append(
+            loss(
+                "metadata",
+                "metadata",
+                LOSS_UNMAPPED_FIELD,
+                "Anthropic request metadata (user_id) has no IR equivalent in v1.",
+            )
+        )
+
+    model = str(wire.get("model", ""))
+    if table is not None:
+        model = table.map(model)
+
+    tools: list[Tool] | None = None
+    if "tools" in wire and wire["tools"] is not None:
+        tools = []
+        for index, tool in enumerate(wire["tools"]):
+            schema = tool.get("input_schema")
+            require_json_object(schema, f"tools[{index}].input_schema")
+            desc = tool.get("description")
+            tools.append(
+                Tool(
+                    name=tool["name"],
+                    description=desc if desc else None,
+                    input_schema=schema,
+                )
+            )
+
+    tool_choice, tc_losses = decode_tool_choice(wire.get("tool_choice"))
+    losses.extend(tc_losses)
+
+    system, sys_losses = decode_system(wire.get("system"))
+    losses.extend(sys_losses)
+
+    raw_messages = wire.get("messages", [])
+    if not raw_messages:
+        raise ValueError("anthropic: request carries no messages")
+
+    messages: list[IrMessage] = []
+    for index, msg in enumerate(raw_messages):
+        role_str = msg.get("role", "")
+        if role_str == AN_ROLE_USER:
+            role = ROLE_USER
+        elif role_str == AN_ROLE_ASSISTANT:
+            role = ROLE_ASSISTANT
+        else:
+            raise ValueError(f"anthropic: messages[{index}]: unknown role {role_str!r}")
+
+        content_path = f"messages[{index}].content"
+        blocks, b_losses = decode_content(msg.get("content"), content_path)
+        losses.extend(b_losses)
+        messages.append(IrMessage(role=role, content=blocks))
+
+    stop = wire.get("stop_sequences")
+    stop_sequences = [s for s in stop if s] if isinstance(stop, list) and stop else None
+
+    params = Params(
+        temperature=wire.get("temperature"),
+        top_p=wire.get("top_p"),
+        max_tokens=max_tokens,
+        stop_sequences=stop_sequences,
+    )
+
+    return (
+        Request(
+            model=model,
+            messages=messages,
+            system=system,
+            tools=tools if tools else None,
+            tool_choice=tool_choice,
+            params=params,
+        ),
+        losses,
+    )
+
+
+def decode_response(
+    wire: dict[str, Any],
+    raw_text: str = "",
+    table: Table | None = None,
+) -> tuple[Response, list[Loss]]:
+    """Converts an Anthropic Messages wire response to the IR (face → IR)."""
+    losses: list[Loss] = []
+
+    content_raw = wire.get("content", [])
+    content: list[Block] = []
+    for index, block in enumerate(content_raw):
+        decoded, b_losses, mapped = decode_block(block, f"content[{index}]", raw_text)
+        if mapped:
+            content.extend(decoded)
+        losses.extend(b_losses)
+
+    stop_reason, stop_loss = decode_stop_reason(wire.get("stop_reason"))
+    if stop_loss is not None:
+        losses.append(stop_loss)
+
+    model = str(wire.get("model", ""))
+    if table is not None:
+        model = table.map(model)
+
+    usage_raw = wire.get("usage", {})
+    usage = Usage(
+        input_tokens=int(usage_raw.get("input_tokens", 0)),
+        output_tokens=int(usage_raw.get("output_tokens", 0)),
+    )
+
+    stop_seq = wire.get("stop_sequence")
+
+    return (
+        Response(
+            id=str(wire.get("id", "")),
+            model=model,
+            content=content,
+            stop_reason=stop_reason,
+            usage=usage,
+            stop_sequence=stop_seq if stop_seq else None,
+        ),
+        losses,
+    )
+
+
+def decode_stop_reason(stop: Any) -> tuple[str, Loss | None]:
+    if stop == STOP_REASON_END_TURN:
+        return STOP_END_TURN, None
+    if stop == STOP_REASON_MAX_TOKENS:
+        return STOP_MAX_TOKENS, None
+    if stop == STOP_REASON_STOP_SEQUENCE:
+        return STOP_STOP_SEQUENCE, None
+    if stop == STOP_REASON_TOOL_USE:
+        return STOP_TOOL_USE, None
+    if stop == STOP_REASON_REFUSAL:
+        return STOP_REFUSAL, None
+    if not stop:
+        raise ValueError("anthropic: stop_reason is missing")
+    return (
+        STOP_OTHER,
+        loss(
+            "stop_reason",
+            "stop_reason",
+            LOSS_UNMAPPED_VALUE,
+            f"Anthropic stop_reason {stop!r} has no IR equivalent",
+        ),
+    )