Crate heartbit_core 

heartbit-core

The Rust agentic framework — agents, tools, LLM providers, memory, evaluation.

Documentation lands here as the crate’s docs.rs preamble. The README is rendered above this on docs.rs.

Re-exports

pub use agent::audit::AuditMode;

pub use agent::audit::AuditRecord;

pub use agent::audit::AuditTrail;

pub use agent::audit::InMemoryAuditTrail;

pub use agent::batch::BatchConfig;

pub use agent::batch::BatchExecutor;

pub use agent::batch::BatchExecutorBuilder;

pub use agent::batch::BatchResult;

pub use agent::blackboard::Blackboard;

pub use agent::blackboard::InMemoryBlackboard;

pub use agent::cache::ResponseCache;

pub use agent::context::ContextStrategy;

pub use agent::context_recall::ContextRecallStore;

pub use agent::context_recall::RecallHit;

pub use agent::dag::DagAgent;

pub use agent::dag::DagAgentBuilder;

pub use agent::debate::DebateAgent;

pub use agent::debate::DebateAgentBuilder;

pub use agent::evaluator::EvaluatorOptimizerAgent;

pub use agent::evaluator::EvaluatorOptimizerAgentBuilder;

pub use agent::events::AgentEvent;

pub use agent::events::OnEvent;

pub use agent::goal::GoalCondition;

pub use agent::goal::GoalSlot;

pub use agent::goal::GoalVerdict;

pub use agent::guardrail::GuardAction;

pub use agent::guardrail::Guardrail;

pub use agent::guardrails::ContentFenceGuardrail;Deprecated

pub use agent::guardrails::tool_policy::InputConstraint;

pub use agent::guardrails::tool_policy::ToolRule;

pub use agent::guardrails::ActionBudgetGuardrail;

pub use agent::guardrails::ActionBudgetGuardrailBuilder;

pub use agent::guardrails::BehaviorRule;

pub use agent::guardrails::BehavioralMonitorGuardrail;

pub use agent::guardrails::BehavioralMonitorGuardrailBuilder;

pub use agent::guardrails::BudgetRule;

pub use agent::guardrails::ConditionalGuardrail;

pub use agent::guardrails::GuardrailChain;

pub use agent::guardrails::GuardrailMode;

pub use agent::guardrails::InjectionClassifierGuardrail;

pub use agent::guardrails::LlmJudgeGuardrail;

pub use agent::guardrails::LlmJudgeGuardrailBuilder;

pub use agent::guardrails::PiiAction;

pub use agent::guardrails::PiiDetector;

pub use agent::guardrails::PiiGuardrail;

pub use agent::guardrails::ScopeGuard;

pub use agent::guardrails::SecretAction;

pub use agent::guardrails::SecretScannerGuardrail;

pub use agent::guardrails::SecretScannerGuardrailBuilder;

pub use agent::guardrails::SensorSecurityGuardrail;

pub use agent::guardrails::ToolPolicyGuardrail;

pub use agent::guardrails::WarnToDeny;

pub use agent::handoff::HandoffRunner;

pub use agent::handoff::HandoffRunnerBuilder;

pub use agent::handoff::make_handoff_tool;

pub use agent::instructions::discover_instruction_files;

pub use agent::instructions::load_instructions;

pub use agent::instructions::prepend_instructions;

pub use agent::mixture::MixtureOfAgentsAgent;

pub use agent::mixture::MixtureOfAgentsAgentBuilder;

pub use agent::observability::ObservabilityMode;

pub use agent::orchestrator::Orchestrator;

pub use agent::orchestrator::OrchestratorBuilder;

pub use agent::orchestrator::SubAgentConfig;

pub use agent::orchestrator::SubAgentContextConfig;

pub use agent::permission::LearnedPermissions;

pub use agent::permission::PermissionAction;

pub use agent::permission::PermissionRule;

pub use agent::permission::PermissionRuleset;

pub use agent::prompts::MULTI_AGENT_COLLAB_PROMPT;

pub use agent::pruner::SessionPruneConfig;

pub use agent::routing::AgentCapability;

pub use agent::routing::ComplexitySignals;

pub use agent::routing::KeywordRoutingStrategy;

pub use agent::routing::RoutingDecision;

pub use agent::routing::RoutingMode;

pub use agent::routing::RoutingStrategy;

pub use agent::routing::TaskComplexityAnalyzer;

pub use agent::routing::resolve_routing_mode;

pub use agent::routing::should_escalate;

pub use agent::tenant_tracker::TenantTokenState;

pub use agent::tenant_tracker::TenantTokenTracker;

pub use agent::tenant_tracker::TokenReservation;

pub use agent::tool_filter::ToolProfile;

pub use agent::voting::VoteResult;

pub use agent::voting::VotingAgent;

pub use agent::voting::VotingAgentBuilder;

pub use agent::workflow::LoopAgent;

pub use agent::workflow::LoopAgentBuilder;

pub use agent::workflow::ParallelAgent;

pub use agent::workflow::ParallelAgentBuilder;

pub use agent::workflow::SequentialAgent;

pub use agent::workflow::SequentialAgentBuilder;

pub use agent::workflow::WorkflowRouter;

pub use agent::workflow::WorkflowType;

pub use agent::workflow_tool::RunWorkflowTool;

pub use agent::workflow_tool::WorkflowRecipe;

pub use agent::workflow_tool::WorkflowRegistry;

pub use agent::workflow_tool::default_registry;

pub use agent::AgentOutput;

pub use agent::AgentRunner;

pub use agent::AgentRunnerBuilder;

pub use agent::DelegationNudge;

pub use agent::InterruptHandle;

pub use agent::OnInput;

pub use codegen::verify::VerifyCommandTool;

pub use agent::flow;

pub use agent::flow::agent::AgentCall;

pub use agent::flow::agent::AgentOpts;

pub use agent::flow::agent::Isolation;

pub use agent::flow::agent::NoSchema;

pub use agent::flow::agent::RawJson;

pub use agent::flow::agent::StructuredSchema;

pub use agent::flow::ctx::ControlBreach;

pub use agent::flow::ctx::ProviderFactory;

pub use agent::flow::ctx::WorkflowCtx;

pub use agent::flow::ctx::WorkflowCtxBuilder;

pub use agent::flow::event::OnWorkflowEvent;

pub use agent::flow::event::PhaseGuard;

pub use agent::flow::event::WorkflowEvent;

pub use agent::flow::journal::ResumeMode;

pub use agent::flow::journal::RunJournal;

pub use agent::flow::parallel::BoxThunk;

pub use agent::flow::pipeline::PipelineBuilder;

pub use agent::flow::progress::PhaseProgress;

pub use agent::flow::progress::ProgressTracker;

pub use agent::flow::progress::RunProgress;

pub use error::Error;

pub use execution_context::AuditSink;

pub use execution_context::CredentialResolver;

pub use execution_context::ExecutionContext;

pub use execution_context::Secret;

pub use eval::CaseComparison;

pub use eval::CostScorer;

pub use eval::EvalCase;

pub use eval::EvalComparison;

pub use eval::EvalResult;

pub use eval::EvalRunner;

pub use eval::EvalScorer;

pub use eval::EvalSummary;

pub use eval::EventCollector;

pub use eval::KeywordScorer;

pub use eval::LatencyScorer;

pub use eval::SafetyScorer;

pub use eval::ScorerResult;

pub use eval::SimilarityScorer;

pub use eval::ToolCallCountScorer;

pub use eval::TrajectoryScorer;

pub use eval::build_eval_agent;

pub use eval::clear_events;

pub use sandbox::CorePathPolicy;

pub use sandbox::CorePathPolicyBuilder;

pub use knowledge::in_memory::InMemoryKnowledgeBase;

pub use knowledge::Chunk;

pub use knowledge::DocumentSource;

pub use knowledge::KnowledgeBase;

pub use knowledge::KnowledgeQuery;

pub use knowledge::SearchResult;

pub use llm::ApprovalDecision;

pub use llm::LlmProvider;

pub use llm::OnApproval;

pub use llm::OnReasoning;

pub use llm::OnText;

pub use llm::anthropic::AnthropicProvider;

pub use llm::cascade::CascadingProvider;

pub use llm::cascade::ConfidenceGate;

pub use llm::cascade::HeuristicGate;

pub use llm::circuit::CircuitBreakerProvider;

pub use llm::circuit::CircuitConfig;

pub use llm::circuit::CircuitKey;

pub use llm::circuit::CircuitPermit;

pub use llm::circuit::CircuitTracker;

pub use llm::circuit::ProviderCircuit;

pub use llm::circuit::is_circuit_failure;

pub use llm::error_class::ErrorClass;

pub use llm::error_class::classify as classify_error;

pub use llm::gemini::GeminiProvider;

pub use llm::openai_compat::AuthStyle;

pub use llm::openai_compat::OpenAiCompatProvider;

pub use llm::openrouter::OpenRouterProvider;

pub use llm::pricing::estimate_cost;

pub use llm::registry::ProviderInfo;

pub use llm::registry::detect_available_provider;

pub use llm::registry::get_provider;

pub use llm::registry::known_providers as known_llm_providers;

pub use llm::registry::resolve_api_key;

pub use llm::retry::OnRetry;

pub use llm::retry::RetryConfig;

pub use llm::retry::RetryingProvider;

pub use llm::types::CompletionRequest;

pub use llm::types::CompletionResponse;

pub use llm::types::ContentBlock;

pub use llm::types::Message;

pub use llm::types::ReasoningEffort;

pub use llm::types::Role;

pub use llm::types::StopReason;

pub use llm::types::TokenUsage;

pub use llm::types::ToolCall;

pub use llm::types::ToolChoice;

pub use llm::types::ToolDefinition;

pub use llm::types::ToolResult;

pub use llm::BoxedProvider;

pub use llm::DynLlmProvider;

pub use lsp::Diagnostic as LspDiagnostic;

pub use lsp::LspManager;

pub use memory::Confidentiality;

pub use memory::consolidation::ConsolidationPipeline;

pub use memory::consolidation::ConsolidationResult;

pub use memory::consolidation::DEFAULT_SUMMARY_MAX_TOKENS;

pub use memory::consolidation::cluster_by_keywords;

pub use memory::embedding::EmbeddingMemory;

pub use memory::embedding::EmbeddingProvider;

pub use memory::embedding::NoopEmbedding;

pub use memory::embedding::OpenAiEmbedding;

pub use memory::hybrid::cosine_similarity;

pub use memory::hybrid::rrf_fuse;

pub use memory::in_memory::InMemoryStore;

pub use memory::namespaced::NamespacedMemory;

pub use memory::pruning::DEFAULT_MIN_STRENGTH;

pub use memory::pruning::default_min_age;

pub use memory::pruning::prune_weak_entries;

pub use memory::reflection::ReflectionTracker;

pub use memory::scoring::ScoringWeights;

pub use memory::Memory;

pub use memory::MemoryEntry;

pub use memory::MemoryQuery;

pub use memory::MemoryType;

pub use persona::AuthorshipMode;

pub use persona::Persona;

pub use persona::PersonaExpansion;

pub use persona::PersonaParams;

pub use persona::PersonaRegistry;

pub use persona::ReviewSpec;

pub use persona::TopicContextProvider;

pub use persona::TriggerSpec;

pub use tool::advisor::AdvisorTool;

pub use tool::builtins::TwitterCredentials;

pub use tool::builtins::handoff::SessionHandoffTool;

pub use tool::builtins::BuiltinToolsConfig;

pub use tool::builtins::FileTracker;

pub use tool::builtins::OnQuestion;

pub use tool::builtins::Question;

pub use tool::builtins::QuestionOption;

pub use tool::builtins::QuestionRequest;

pub use tool::builtins::QuestionResponse;

pub use tool::builtins::TodoPriority;

pub use tool::builtins::TodoStatus;

pub use tool::builtins::TodoStore;

pub use tool::builtins::ToolRisk;

pub use tool::builtins::builtin_tools;

pub use tool::handoff::HandoffContextMode;

pub use tool::handoff::HandoffTarget;

pub use tool::handoff::HandoffTool;

pub use tool::mcp::AuthProvider;

pub use tool::mcp::AuthResolver;

pub use tool::mcp::DirectAuthProvider;

pub use tool::mcp::DynamicAuthResolver;

pub use tool::mcp::McpClient;

pub use tool::mcp::McpPromptArgument;

pub use tool::mcp::McpPromptDef;

pub use tool::mcp::McpPromptMessage;

pub use tool::mcp::McpPromptMessageContent;

pub use tool::mcp::McpResourceContent;

pub use tool::mcp::McpResourceDef;

pub use tool::mcp::McpRoot;

pub use tool::mcp::McpTransportPool;

pub use tool::mcp::SamplingContent;

pub use tool::mcp::SamplingHandler;

pub use tool::mcp::SamplingMessage;

pub use tool::mcp::SamplingModelHint;

pub use tool::mcp::SamplingModelPreferences;

pub use tool::mcp::SamplingRequest;

pub use tool::mcp::StaticAuthProvider;

pub use tool::mcp::StaticAuthResolver;

pub use tool::mcp::TokenExchangeAuthProvider;

pub use tool::mcp_presets::McpPreset;

pub use tool::mcp_presets::check_preset_env;

pub use tool::mcp_presets::connect_preset;

pub use tool::mcp_presets::connect_preset_with_args;

pub use tool::mcp_presets::known_presets;

pub use tool::mcp_presets::resolve_preset;

pub use tool::mcp_server::McpServer;

pub use tool::mcp_server::McpServerConfig;

pub use tool::mcp_server::ServerResource;

pub use tool::set_goal::SetGoalTool;

pub use tool::set_scope::SetScopeTool;

pub use tool::Tool;

pub use tool::ToolOutput;

pub use tool::validate_tool_input;

pub use workspace::Workspace;

Modules

agent

Agent runtime — AgentRunner, Orchestrator, workflow agents, guardrails, and supporting types.

auth

Authentication primitives.

browser

SOTA browser-bot harness: drive a real Chrome via the chrome-devtools MCP server, with the reliability and safety layer that makes a web agent actually work (per tasks/browser-bot-sota-2026-05-31.md).

channel

Channel base traits and in-process implementations.

codegen

Code-generation harness — a domain-specific agent harness for writing and verifying code, mirroring browser but for the code domain.

config

TOML configuration types for agents, orchestrators, LLM providers, and integrations.

error

Error type for all heartbit-core fallible operations.

eval

Agent evaluation framework.

execution_context

Per-request execution context threaded through tool dispatch.

http

HTTP client factories and URL validation primitives.

knowledge

Knowledge base — document ingestion, chunking, and vector or BM25 retrieval.

llm

LLM provider abstractions — LlmProvider trait, Anthropic/Gemini/OpenRouter/OpenAI-compat backends, retry, cascade, and circuit-breaker wrappers.

lsp

Language Server Protocol (LSP) client for inline diagnostics in agent tool responses.

memory

Agent memory system — Memory trait, in-memory and PostgreSQL stores, BM25 and vector recall, Ebbinghaus decay, reflection, and consolidation.

persona

Persona registry: a small abstraction so concrete persona crates (e.g. heartbit-ghost) plug in identically. Empty in Phase 0; concrete personas land in Phase 1.

sandbox

Path-level sandbox policy shared across filesystem-touching builtins.

signal

Unix signal handling utilities for graceful agent shutdown.

skill

Agent Skills: filesystem-based, progressively-disclosed capabilities.

store

Task and audit record persistence (in-memory and PostgreSQL backends).

template

Agent template system for reusable, composable agent configurations.

tool

Tool trait and built-in tool implementations (filesystem, web, MCP, A2A, etc.).

workspace

Workspace root management and path normalization for sandboxed agent file access.