| Title: | Rho AI Protocol |
|---|---|
| Description: | Defines S7 protocols for models, messages, content, tools, credentials, capabilities, and normalized provider event streams. Includes adapters for OpenAI, OpenAI Codex, Anthropic, GitHub Copilot, Z.ai, Kimi Code, Kimi Platform, Ollama, and deterministic provider fixtures. |
| Authors: | Sounkou Mahamane Toure [aut, cre] |
| Maintainer: | Sounkou Mahamane Toure <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.1.9001 |
| Built: | 2026-07-21 23:02:33 UTC |
| Source: | https://github.com/RGenomicsETL/Rho |
Credentials are owned by a CredentialStore; login interaction is owned by
a LoginIO. Reads, refreshes, writes, prompts, and notifications are explicit
async operations. RhoModels owns provider selection and serialized refresh
gates instead of relying on process-global auth state.
rho_memory_credential_store() keeps credentials for one R process.
rho_file_credential_store() persists them as a versioned JSON document at
an explicitly supplied path. rho_encrypted_file_credential_store() encrypts
that document with an explicitly supplied passphrase or 32-byte key using
Argon2id and XChaCha20-Poly1305. rho_keychain_credential_store() keeps each
provider credential in the operating system's native keychain and rejects
keyring's environment and file backends. File updates are serialized, replace
the prior document, and use owner-only permissions where the platform supports
them. rho_user_credential_path() returns R's platform-specific user
configuration path without creating it.
Providers emit the typed AssistantEvent hierarchy. Provider-specific wire
events are decoded and reduced through separate S7 generics, keeping wire
formats out of the agent loop.
Messages contain typed content objects rather than discriminator strings. Tool execution is asynchronous, and overlap is represented by an S7 value that the agent can dispatch on.
A RhoOperation states what a conversation may do. A handler binds that
semantic request to a concrete implementation for the selected model.
Bindings record both the handler and the reason it was selected; request
translators turn bindings into provider wire values while encoding a request.
Provider-hosted activity is normalized as Content, never as a local
ToolCall. The agent can therefore retain and report a web search without
placing it in its executable tool registry.
Shared model facts live in typed capability, limits, and pricing objects. Provider-specific behavior is queried with typed operation values and S7 dispatch, avoiding a lowest-common-denominator boolean map.
Provider turns are independent of byte transport. rho_stream() always
returns normalized assistant events whether an implementation uses SSE,
WebSocket, an embedded model, or a remote evaluator. ProviderTransport
values describe executable strategies. AutomaticTransport is a selection
policy rather than a model capability. rho_select_provider_transport()
records the selected strategy and reason; rho_open_provider_transport()
is the provider-open execution point.
ProviderUsage records token and cache counts supplied by a provider.
EstimatedUsage records an explicitly named estimator and method.
UsageUnavailable records that a provider did not supply counts; it has no
fabricated token counts or cost. Usage components are disjoint: input
excludes cache reads and writes, while output includes any reported
reasoning tokens. reasoning is an optional breakdown of output; it is
never added to total a second time. The optional cache_write_1h value is
a subset of cache_write.
rho_price_usage() is the open pricing protocol. Its default Model
method selects the highest matching long-context tier, prices every
component, and returns a new counted usage value with a
NominalUsageCost. It does not claim to report a subscription charge. Model
subclasses may provide methods for provider-specific pricing rules.
rho_summarize_usage() preserves every typed observation and reports
disjoint token totals, nominal cost, and the latest cache-hit proportion.
complete is false when any turn has UsageUnavailable; cost_complete is
false when a counted turn has no nominal price. Zeroes therefore never hide
missing provider data.
Anthropic request construction is a reduction over typed request sections. Model catalog facts select thinking, temperature, cache, and tool-input capabilities; request methods never infer behavior from model names.
AnthropicMessagesEndpoint separates the Messages dialect from endpoint
authentication and transport. Anthropic and GitHub Copilot therefore share
message translation and event reduction while retaining their own endpoint
headers, URLs, and credentials.
Stream JSON is decoded once into typed wire events. S7 methods translate
blocks, deltas, and stop reasons into the provider-neutral AssistantEvent
protocol.
Kimi Platform uses its own Chat Completions dialect. Its typed request
methods preserve Kimi thinking controls, use max_completion_tokens, and
accept explicit image content. The global and China endpoints remain
separate providers because their credentials and model catalogs are scoped
independently.
The catalog stores model facts as package data. rho_model_expression()
turns a typed provider profile, protocol, and record into an inspectable R
call. rho_compile_catalog_model() evaluates that call to produce the S7
model value used by provider dispatch. Extensions may add provider profiles,
protocols, and expression methods without rewriting the catalog reader.
Catalog refresh is an explicit development operation. Package installation and ordinary runtime use never contact a catalog service.
Chat Completions chunks are parsed into typed wire values and reduced by S7
methods to the normalized AssistantEvent protocol.
OpenAI request bodies are reductions over typed sections. Model-specific
methods select the sections and their defaults; section methods alone emit
wire field names and provider values. Extensions can specialize
rho_openai_request_sections() for a model subclass or append a new
OpenAIRequestSection with a rho_request_fields() method.
Canonical thinking requests are values. ThinkingOff therefore dispatches
separately from enabled levels without comparing provider wire strings.
The OpenAI Responses decoder maps JSON/SSE payloads to typed wire event and output-item classes before reducing them to normalized assistant events. Provider extensions may add narrower S7 methods for new item or event types.
Z.ai uses the OpenAI-compatible Chat Completions protocol with explicit thinking preservation and tool-call streaming policies.