armillae-simulate 0.1.0-alpha.1

Backend-neutral simulation, clock, module, and execution protocols for Armillae
Documentation
# Armillae

[简体中文](https://github.com/mmstudio-games/armillae/blob/main/README.zh.md)

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:

```sh
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](https://github.com/mmstudio-games/armillae/blob/main/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](https://github.com/mmstudio-games/armillae/blob/main/LICENSE),
identified by SPDX as `AGPL-3.0-only`.