Armillae

简体中文

Armillae is a layered Rust ecosystem for agentic narrative systems, TRPG runtimes, and world simulation engines. Its implemented foundation provides provider-independent LLM calls and type-safe Tool execution; its next design focus is the Agentic narrative runtime above them.

Status

Armillae is alpha software. Its foundational crates remain on Semifold's alpha release channel while public protocol boundaries, Provider compatibility, and release evidence continue to stabilize. Beta requires a frozen 0.1 scope, no known chain-blocking defects, representative Live and downstream evidence, and explicit approval; stable will not be promoted directly from alpha. The implemented LLM foundation currently provides:

• provider-independent message, completion, Tool, usage, and streaming protocols;
• a runtime-independent LlmBridge for exactly one model call;
• target Provider projection with same-Provider reasoning replay and observable cross-Provider compatibility facts;
• type-safe Tool authoring, registration, and exactly one ToolCall execution;
• a #[tool] macro that turns synchronous or asynchronous functions into the same Tool contract;
• deterministic mocks and shared Bridge contract tests;
• Rig adapters for OpenAI, generic OpenAI-compatible endpoints, DeepSeek, MiniMax, Moonshot, Anthropic, and Ollama;
• non-streaming and streaming text and ToolCall support for the implemented providers.

The OpenAI-protocol baseline still requires an explicit end-to-end Provider/model scenario matrix before a formal full-support claim. The native Anthropic Messages adapter uses a conservative profile: requests require max_output_tokens, ToolResult.is_error = true is rejected because Rig 0.42 cannot preserve it. Unknown Anthropic events exposed by Rig are retained as ProviderEvent. All adapters pin Rig 0.42.0; streaming success requires a real provider terminal event, and structured output additionally requires final JSON/Schema validation. Ollama uses a conservative native profile and generates Armillae ToolCall IDs because its wire protocol does not provide them.

Crates

Crate	Responsibility
armillae-core	Provider-independent messages, completions, Tools, usage, and streaming events
armillae-llm	Bridge traits, capabilities, configuration, secrets, errors, factories, and mocks
armillae-tools	Type-safe Tools, context, registry, and single-call execution
armillae-tools-macros	Function-like #[tool] authoring macro for armillae-tools
armillae-llm-rig	Rig-backed Provider adapters isolated from the public protocol

The central boundary is simple: a Bridge performs one model call, and a Tool Executor performs one ToolCall. Whether another model call should happen is decided by downstream code.

Development

The workspace uses stable Rust with the 2024 edition. Run the same offline checks used by CI:

cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features --locked
cargo test --workspace --all-targets --all-features --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps --locked

Live Provider tests are ignored by default and must only be run with explicitly supplied test credentials. See CONTRIBUTING.md before making changes. Engineering specifications and RFCs are linked from the contribution guide.

License

Armillae is licensed under the GNU Affero General Public License v3.0 only, identified by SPDX as AGPL-3.0-only.