lexigram-ai-relay

Protocol-neutral conversion engine for the Lexigram AI relay — OpenAI Chat, Responses, Anthropic, and Gemini

Overview

Protocol-neutral conversion engine for the Lexigram AI relay. Converts between OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini generateContent wire formats through one canonical intermediate representation.

The engine is synchronous and side-effect free: it never performs HTTP, channel selection, billing, or model selection. Host capabilities (Claude default max_tokens, Gemini safety thresholds, media resolution, model suffixes) are supplied as typed callbacks through RelayConversionContext from lexigram-contracts.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-ai-relay

Quick Start

from lexigram import Application
from lexigram.ai.relay import RelayModule


async def main() -> None:
    async with Application.boot(modules=[RelayModule.configure()]) as app:
        # ... conversion engine available via the registry ...
        ...


if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Convert a payload directly with the built-in registry:

from lexigram.ai.relay import RelayConverterRegistry, convert_request_by_id
from lexigram.contracts.ai.relay import OpenAIChatMessage, OpenAIChatRequest, RelayFormat
from lexigram.contracts.ai.relay.context import RelayConversionContext

registry = RelayConverterRegistry.with_defaults()
context = RelayConversionContext(default_max_tokens=lambda model: 8192)

result = convert_request_by_id(
    registry,
    payload=OpenAIChatRequest(
        model="gpt-4o",
        messages=[OpenAIChatMessage(role="user", content="hi")],
    ),
    converter_id="openai_chat_to_claude",
    context=context,
)
# Result[RelayConvertResult[RelayRequestPayload], RelayError]

RelayConversionContext supplies host capabilities (Claude needs default_max_tokens); see the host-context reference below.

Configuration

Zero-config usage: Call RelayModule.configure() with no arguments. The engine needs no configuration; host capabilities are optional.

Option 1 — Python (host context)

from lexigram.contracts.ai.relay.context import RelayConversionContext

context = RelayConversionContext(
    default_max_tokens=lambda model: 8192,
    upstream_model="claude-3-5-sonnet",
    request_id="req_123",
)

Host context reference

All callbacks are nil-safe: mappers never guard against None.

Module Factory Methods

Key Features

• Four wire formats: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini generateContent
• Canonical IR: every conversion goes source → IR → target with route-quality reporting
• Synchronous and side-effect free: no HTTP, channel selection, billing, or model selection
• Typed host callbacks: RelayConversionContext supplies Claude, Gemini, and media capabilities
• Result-typed conversions: Result[RelayConvertResult, RelayError] with full error translation
• Media handling: local data-URI decoding and host-supplied URL resolution
• Stream scaffolding: per-format stream session state (stateful conversion not yet enabled)

Testing

async with Application.boot(modules=[RelayModule.stub()]) as app:
    # your test code
    ...

Key Source Files