paigasus-helikon

Paigasus AI SDK — codename Helikon. A Rust SDK for building AI agents with pluggable providers, runtimes, and tools.

What it is

paigasus-helikon is a Rust SDK for building agentic AI systems. It separates the slow-moving primitives (types, traits, message protocols) from the fast-moving parts (provider SDKs, execution runtimes, tool catalogs), so downstream projects can pick the surface they need without dragging in the rest.

The SDK does not pick a deployment story, a hosting story, or an observability stack for you. Bring your own.

The codename

In Greek myth, Mount Helicon (Greek: Ἑλικῶν, Helikōn) is the home of the Muses. When Pegasus struck the mountainside with his hoof, the Hippocrene spring burst forth — the literal source of poetic inspiration that the Muses drew from.

Paigasus is the umbrella; Helikon is the spring. The SDK is the artifact you draw from when building agents on top.

Install

cargo add paigasus-helikon --features openai,macros

Turn on the features you need — openai, anthropic, bedrock, gemini, mcp, tools, tools-web, tools-os-sandbox, tools-microvm, sessions-sqlite, sessions-postgres, sessions-redis, runtime-tokio, runtime-axum, runtime-temporal, runtime-agentcore, evals, macros. See the crate roster for the full feature → crate map and current published versions.

Workspace at a glance

Nineteen crates under crates/. Eighteen are published to crates.io; one is an internal test harness (publish = false); one of the published crates (the CLI) is binary-only, publishing a lib target with no stability guarantees purely so cargo install resolves.

• paigasus-helikon — facade re-exporting core plus opt-in sibling crates by feature flag.
• paigasus-helikon-core — type system, traits, the agent loop, runtime-agnostic primitives.
• paigasus-helikon-macros — the #[tool] attribute and tools! proc macros.
• paigasus-helikon-providers-openai, -anthropic, -bedrock, -gemini — LLM provider adapters.
• paigasus-helikon-sessions-sqlite — SQLite-backed session persistence.
• paigasus-helikon-sessions-postgres — PostgreSQL-backed session persistence (JSONB event log, advisory-lock concurrency, aws-lc-rs TLS).
• paigasus-helikon-sessions-redis — Redis Streams-backed session persistence (atomic Lua append, BYO-ConnectionManager for TLS).
• paigasus-helikon-runtime-tokio — the default ephemeral Tokio runner.
• paigasus-helikon-runtime-axum — self-hosted HTTP/SSE/WebSocket agent server (AgentServer builder, 6 endpoints: one-shot JSON, SSE streaming, async detached, WebSocket event replay, agent list, OpenAPI schema; replayable runs with TTL+count retention).
• paigasus-helikon-runtime-temporal — durable runner over the official Temporal Rust SDK (TemporalRunner; per-model-turn and per-tool-call activities; a run that crashes mid-tool-call resumes from the last completed activity).
• paigasus-helikon-runtime-agentcore — AWS Bedrock AgentCore container shim (AgentCoreServer; HTTP-protocol contract on 8080 plus MCP-protocol mode on 8000; ships a multi-stage Dockerfile and CDK deployment snippet).
• paigasus-helikon-tools — sandboxed Read/Write/Edit/Bash tools (+ WebFetch/WebSearch behind web; OS-enforced containment behind os-sandbox; microVM containment via forkd/Firecracker behind microvm, experimental — SMA-437: includes EgressProxy, EgressPolicy, and Isolation::Proxied for domain-filtered egress enforcement).
• paigasus-helikon-mcp — Model Context Protocol client and server integration.
• paigasus-helikon-cli — published binary crate: helikon and paigasus-helikon binaries (cargo install paigasus-helikon-cli) with repl, eval run, and mcp serve subcommands driven by an agents.toml sidecar; its lib target publishes only so cargo install works, and carries no stability guarantee.
• paigasus-helikon-evals — evaluation harness: JSONL datasets, an Evaluator trait with four built-ins (ExactMatch, JsonSchemaConformance, LlmJudge, ToolUseTrajectory), a MockModel for deterministic replay, and SQLite/Parquet trace sinks.

See the crate roster for each crate's concern, published state, and current version.

Documentation

The public documentation site is published at https://smk1085.github.io/paigasus-helikon/ — a guided mdBook covering the quickstart, the core concepts, and the crate roster.

To build it locally: cd docs/book && mdbook serve (requires mdbook and mdbook-linkcheck installed via cargo install; see CONTRIBUTING.md for exact versions).

The architectural source-of-truth currently lives in Notion (internal): "Crate Reference". External readers should treat the Notion link as an artifact pointer rather than a destination — content migrates into the published book as the SDK lands.

Tracked work lives in Linear under the project Paigasus Helikon (issues are prefixed SMA-).

Contributing

See CONTRIBUTING.md for branching, testing, and release workflows. By participating you agree to the Contributor Covenant Code of Conduct. For security disclosures see SECURITY.md.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.