Workspace layout

Paigasus Helikon is a Cargo workspace of 19 crates under the paigasus-helikon-* namespace. As a consumer you rarely depend on more than two of them directly: the paigasus-helikon-core trait crate, or — more commonly — the paigasus-helikon facade, which re-exports core plus the optional sibling crates behind Cargo features.

This page is about how to depend on the SDK. For the per-crate version and ownership table, see Crates reference.

The facade

paigasus-helikon re-exports paigasus-helikon-core unconditionally as paigasus_helikon::core, and each optional sibling crate behind a kebab-case feature. With no features you still get the full core surface: the traits (Agent, Model, Tool, Session) plus the carrier and impl types (LlmAgent, RunContext, the event stream). Features add the concrete adapters and runtimes on top.

Feature names are kebab-case in Cargo.toml; the re-export module aliases are snake-case.

FeatureRe-exported asSurface
(always on)paigasus_helikon::corepaigasus-helikon-core — traits, agent loop, event stream, carrier types
macrospaigasus_helikon::macros, plus paigasus_helikon::tool and paigasus_helikon::tools#[tool] attribute + tools! macro
openai (alias providers-openai)paigasus_helikon::openai (also providers_openai)OpenAiModel adapter
anthropicpaigasus_helikon::anthropicAnthropicModel adapter
mcppaigasus_helikon::mcprmcp-based MCP client/server
toolspaigasus_helikon::toolssandboxed Read/Write/Edit/Bash tools
tools-web(extends tools)adds the WebFetch / WebSearch network tools
runtime-tokiopaigasus_helikon::runtime_tokioephemeral Tokio runner
runtime-axumpaigasus_helikon::runtime_axumself-hosted HTTP/SSE/WebSocket agent server — see Axum Server Runtime
runtime-temporalpaigasus_helikon::runtime_temporaldurable Temporal-backed runner — see Runtimes
runtime-agentcorepaigasus_helikon::runtime_agentcoreAWS Bedrock AgentCore container shim — see Runtimes
sessions-sqlitepaigasus_helikon::sessions_sqliteSQLite Session backend
evalspaigasus_helikon::evalsevaluation harness — datasets, evaluators, MockModel, SQLite/Parquet trace sinks

In addition, paigasus_helikon::schema::strict re-exports the JSON-Schema strict-mode normalizer from core, regardless of features.

tools name clash

paigasus_helikon::tools resolves to two different items when both macros and tools are enabled: the tools! function-like macro (from macros) and the sandboxed-tools module (from the tools crate). They live in separate namespaces, so Rust disambiguates by use site — a macro invocation tools![...] versus a path tools::SomeTool. Be explicit about which you mean.

Published vs stub crates

Eighteen crates carry real implementations and are published on crates.io / docs.rs:

  • paigasus-helikon-core — the dependency root (traits, agent loop, carrier types)
  • paigasus-helikon — the facade
  • paigasus-helikon-macros — #[tool] + tools!
  • paigasus-helikon-providers-openai
  • paigasus-helikon-providers-anthropic
  • paigasus-helikon-providers-bedrock
  • paigasus-helikon-providers-gemini
  • paigasus-helikon-sessions-sqlite
  • paigasus-helikon-sessions-postgres
  • paigasus-helikon-sessions-redis
  • paigasus-helikon-runtime-tokio
  • paigasus-helikon-runtime-axum — self-hosted HTTP/SSE/WebSocket agent server (see Axum Server Runtime)
  • paigasus-helikon-runtime-temporal — durable Temporal-backed runner (see Runtimes)
  • paigasus-helikon-runtime-agentcore — AWS Bedrock AgentCore container shim (see Runtimes)
  • paigasus-helikon-mcp
  • paigasus-helikon-tools
  • paigasus-helikon-evals — evaluation harness: datasets, evaluators, MockModel, SQLite/Parquet trace sinks
  • paigasus-helikon-cli — published binary crate (helikon / paigasus-helikon binaries); its lib target is internal and carries no stability guarantee, publishing only so cargo install paigasus-helikon-cli resolves

Zero name-claim stubs remain in the workspace. The one crate that rounds out the workspace's 19 without publishing is paigasus-helikon-sessions-testkit, an internal Session conformance test harness (publish = false by design).

Picking your surface

Depend on core alone when you only need the trait definitions — for example a crate that implements its own Model or Tool<Ctx> and doesn't pull in any provider:

[dependencies]
paigasus-helikon-core = "0.5"

Depend on the facade for everything else, selecting only the features you use. A typical single-agent app with OpenAI, the tool macros, and SQLite-backed sessions:

[dependencies]
paigasus-helikon = { version = "0.4", features = ["openai", "macros", "sessions-sqlite"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
anyhow = "1"
serde = { version = "1", features = ["derive"] }
schemars = "1"

That pulls paigasus-helikon-providers-openai, paigasus-helikon-macros, and paigasus-helikon-sessions-sqlite transitively; everything else stays out of your dependency graph. Imports then come from the facade's re-export modules:

#![allow(unused)]
fn main() {
use paigasus_helikon::core::{Agent, AgentInput, LlmAgent, MemorySession, RunContext};
use paigasus_helikon::openai::OpenAiModel;
use paigasus_helikon::{tool, tools};
}

Swap providers by swapping one feature and one import: anthropic / paigasus_helikon::anthropic::AnthropicModel instead of openai / OpenAiModel. Add tools (or tools-web) for the sandboxed file/shell tools, mcp for MCP servers, and runtime-tokio for the runner boundary.

Next steps