enact-core 0.0.2

//! enact-core - The core runtime for graph-centric agent execution
//!
//! This crate provides the foundational types and runtime for executing
//! agent graphs with full observability and control.
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────────┐
//! │                           enact-core                                │
//! ├─────────────────────────────────────────────────────────────────────┤
//! │  kernel/       - ExecutionKernel, state machine, reducer, replay    │
//! │  flow/         - Sequential, parallel, conditional, loop primitives │
//! │  callable/     - Callable trait, LlmCallable, GraphCallable         │
//! │  policy/       - Execution, tool, tenant policies and guardrails    │
//! │  streaming/    - Events, event log, IDs, SSE streaming              │
//! │  graph/        - StateGraph, CompiledGraph, nodes, edges            │
//! │  telemetry/    - OpenTelemetry integration, spans, traces           │
//! │  providers/    - LLM adapters (Azure, Anthropic, Gemini)            │
//! │  tool/         - Tool trait and implementations                     │
//! │  memory/       - Episodic, semantic, working memory (future)        │
//! └─────────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Core Concepts
//!
//! - **ExecutionId**: One run of a blueprint (Agent/Graph/Workflow)
//! - **StepId**: A distinct action within that execution
//! - **ArtifactId**: Data produced by steps
//! - **RuntimeContext**: The execution context spine
//! - **TenantContext**: Multi-tenant isolation boundary (REQUIRED)
//!
//! ## Getting Started
//!
//! Most users should start with:
//!
//! ```rust
//! use enact_core::prelude::*;
//! ```
//!
//! This imports the stable, user-facing API for defining agents, graphs, and executions.
//! Internal modules remain accessible for advanced use cases.
//!
//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
//! @see docs/TECHNICAL/02-ENACT-CORE-ARCHITECTURE.md

// =============================================================================
// Core Modules
// =============================================================================

pub mod callable; // Callable trait (Agent abstraction)
pub mod context; // TenantContext, RuntimeContext, TraceContext
pub mod flow; // Sequential, parallel, conditional, loop
pub mod kernel; // ExecutionKernel, state machine, reducer, replay
pub mod policy; // Execution, tool, tenant policies

// =============================================================================
// Existing Modules
// =============================================================================

pub mod background; // Background execution and triggers (Phase 5)
pub mod graph;
pub mod inbox; // Mid-execution guidance (INV-INBOX-*)
pub mod memory;
pub mod providers;
pub mod routing; // v6: model routing primitives and decisions
pub mod runner;
pub mod signal;
pub mod storage; // Storage factory for event/state stores
pub mod streaming; // Events, event log, IDs, SSE streaming
pub mod telemetry; // OpenTelemetry integration
pub mod tool;
pub mod util;
pub mod workflow; // v5: Workflow blueprints, contracts, roles

// =============================================================================
// Re-exports - Kernel
// =============================================================================

pub use kernel::{
    reduce, replay, EventLog as KernelEventLog, Execution, ExecutionAction, ExecutionKernel,
    ExecutionState, ReducerError, ReplayError, Step, StepState, WaitReason,
};

// =============================================================================
// Re-exports - Error Taxonomy (feat-02)
// =============================================================================

pub use kernel::{
    // Retry policies
    BackoffStrategy,
    // Error types
    ExecutionError,
    ExecutionErrorCategory,
    // Specific error codes
    LlmErrorCode,
    RetryPolicy,
    ToolErrorCode,
};

// =============================================================================
// Re-exports - Enforcement & Limits (feat-03)
// =============================================================================

pub use kernel::{
    // Middleware
    EnforcementMiddleware,
    EnforcementPolicy,
    // Enforcement results
    EnforcementResult,
    EnforcementViolation,
    EnforcementWarning,
    // Usage tracking
    ExecutionUsage,
    // Timeout guard
    StepTimeoutGuard,
    UsageSnapshot,
    ViolationType,
};

// =============================================================================
// Re-exports - Artifact Lifecycle (feat-04)
// =============================================================================

pub use kernel::artifact::{
    // Metadata
    ArtifactMetadata,
    // Store trait and errors
    ArtifactStore,
    ArtifactStoreError,
    ArtifactType,
    CompressionType,
    // Implementations
    FilesystemArtifactStore,
};

// =============================================================================
// Re-exports - Flow
// =============================================================================

pub use flow::{
    Branch, Condition, ConditionalFlow, FanIn, FanOut, LoopCondition, LoopFlow, ParallelFlow,
    ParallelResult, SequentialFlow,
};

// =============================================================================
// Re-exports - Callable
// =============================================================================

pub use callable::{
    Callable,
    // Phase 6: Composite Callables
    CallableDescriptor,
    CallableInvocation,
    CallableInvocationResult,
    CallableInvoker,
    CallableRegistry,
    CostTier,
    DiscoveryQuery,
    DiscoveryResult,
    DynCallable,
    GraphCallable,
    LlmCallable,
    ResourceAllocation,
    ResourceAllocationStrategy,
    ResourceBudget,
};

// =============================================================================
// Re-exports - Policy
// =============================================================================

pub use policy::{
    ContentFilter,
    ExecutionLimits,
    ExecutionPolicy,
    FeatureFlags,
    FilterAction,
    FilterResult,
    // Input processors (feat-09: Guardrails)
    InputProcessor,
    InputProcessorPipeline,
    InputProcessorResult,
    PiiInputMode,
    PiiInputProcessor,
    PolicyAction,
    PolicyContext,
    PolicyDecision,
    PolicyEvaluator,
    TenantLimits,
    TenantPolicy,
    ToolPermissions,
    ToolPolicy,
    ToolTrustLevel,
};

// =============================================================================
// Re-exports - Streaming (events, event log, SSE)
// =============================================================================

pub use streaming::{
    ControlAction,
    ControlActor,
    ControlEvent,
    ControlOutcome,
    // Protection layer (feat-09: Guardrails)
    DataDestination,
    DecisionRecord,
    DecisionType,
    Event,
    // Wire format for SSE
    EventEmitter,
    // Event log (persistence)
    EventLog,
    EventLogEntry,
    EventStore,
    EventStream,
    // Domain events
    ExecutionContext,
    ExecutionEvent,
    ExecutionEventType,
    InMemoryEventStore,
    OutputProcessor,
    PiiProtectionProcessor,
    ProcessedEvent,
    ProcessorPipeline,
    // Protected emitter with processor pipeline
    ProtectedEventEmitter,
    ProtectionContext,
    StreamEvent,
    StreamMode,
};

// =============================================================================
// Re-exports - IDs and State Types (from streaming)
// =============================================================================

pub use streaming::{
    // ID prefix constants
    prefixes,
    // Primary IDs
    ArtifactId,
    ExecutionId,
    GraphId,
    // Message/Thread IDs
    MessageId,
    NodeId,
    // Parent linkage
    ParentLink,
    ParentType,
    RunId,
    StepId,
    // Step/Node types
    StepType,
    TenantId,
    ThreadId,
    UserId,
};

// =============================================================================
// Re-exports - MessageStore (feat-05 Persistence)
// =============================================================================

pub use kernel::{
    // Message types
    CostInfo,
    ExecutionStats,
    FinishReason,
    // Store trait and implementation
    InMemoryMessageStore,
    Message,
    MessageMetadata,
    MessagePart,
    MessageRole,
    MessageStore,
    Thread,
    TokenUsage,
};

// =============================================================================
// Re-exports - Context (TenantContext, RuntimeContext, etc.)
// =============================================================================

pub use context::{
    // Invocation context
    InvocationContext,
    InvocationServices,
    ResourceLimits,
    // Runtime context (the spine)
    RuntimeContext,
    RuntimeContextBuilder,
    SessionContext,
    // Tenant context (REQUIRED for every execution)
    TenantContext,
    // Trace context (OpenTelemetry)
    TraceContext,
};

// =============================================================================
// Re-exports - Graph & Execution
// =============================================================================

pub use graph::{
    Checkpoint, CheckpointStore, CompiledGraph, FunctionNode, InMemoryCheckpointStore, Node,
    NodeState, StateGraph,
};

// =============================================================================
// Re-exports - Runner
// =============================================================================

pub use runner::{run_parallel, DefaultRunner, InterruptableRunner, Runner};

// =============================================================================
// Re-exports - Inbox (Mid-Execution Guidance)
// =============================================================================

pub use inbox::{
    // Message types
    A2aMessage,
    ControlAction as InboxControlAction,
    ControlMessage,
    EvidenceImpact,
    EvidenceSource,
    EvidenceUpdate,
    GuidanceMessage,
    GuidancePriority,
    GuidanceSource,
    InMemoryInboxStore,
    InboxMessage,
    InboxMessageType,
    // Store
    InboxStore,
};

// =============================================================================
// Re-exports - Background (Phase 5: Background Callables)
// =============================================================================

pub use background::{
    apply_transform,
    // Executor types
    BackgroundExecution,
    BackgroundExecutionConfig,
    BackgroundExecutionMode,
    BackgroundExecutionQueue,
    BackgroundExecutionStatus,
    // Trigger types
    RetryConfig,
    // Target binding types
    TargetBindingConfig,
    TargetBindingResult,
    TargetBindingTransform,
    TargetBindingType,
    ThresholdOperator,
    Trigger,
    TriggerAction,
    TriggerCondition,
    TriggerFiredEvent,
    TriggerId,
    TriggerStatus,
    TriggerType,
};

// =============================================================================
// Re-exports - Storage Factory
// =============================================================================

pub use storage::{
    create_event_log, create_event_store, create_state_store, EventStoreConfig, InMemoryStateStore,
    StateStoreConfig, StorageContext,
};
pub use streaming::{JsonlEventStore, JsonlStateStore};

// =============================================================================
// Re-exports - Providers & Tools
// =============================================================================

// Re-export provider trait and types (implementations are in enact-providers)
pub use providers::{
    ChatMessage, ChatRequest, ChatResponse, EmbeddingRequest, EmbeddingResponse, ModelCapabilities,
    ModelProvider,
};
pub use routing::{
    resolve_model_precedence, ModelRouter, ModelSelectionSource, RoutingDecision, RoutingPolicy,
    RoutingProfile, DEFAULT_MODEL_ROUTER_ID,
};
pub use tool::{FunctionTool, Tool, ToolExecutionContext, ToolExecutionError, ToolExecutor};

// =============================================================================
// Prelude - Stable, user-facing API
// =============================================================================

/// Prelude module - Convenient imports for most users
///
/// This module exports the stable, user-facing API for defining agents, graphs,
/// and executions. It is intentionally small and opinionated.
///
/// **Important**: The prelude is semver-sensitive and part of the brand promise.
/// Changes here should be rare and intentional.
///
/// # Usage
///
/// ```rust
/// use enact_core::prelude::*;
/// ```
///
/// This imports:
/// - Core runtime types (`ExecutionKernel`)
/// - Graph authoring & execution (`StateGraph`, `CompiledGraph`)
/// - Execution abstractions (`Callable`, `LlmCallable`, `Tool`, `FunctionTool`)
/// - Execution identity (`ExecutionId`, `StepId`)
/// - Observability (`EventStream`, `EventLog`)
/// - Workflow blueprints (`WorkflowDefinition`, `WorkflowLoader`)
pub mod prelude {
    // Core runtime
    pub use crate::kernel::ExecutionKernel;

    // Graph authoring & execution
    pub use crate::graph::{CompiledGraph, StateGraph};

    // Execution abstractions
    pub use crate::callable::{Callable, LlmCallable};
    pub use crate::tool::{FunctionTool, Tool};

    // Execution identity
    pub use crate::kernel::{ExecutionId, StepId};

    // Error taxonomy (feat-02)
    pub use crate::kernel::{ExecutionError, ExecutionErrorCategory};

    // Observability
    pub use crate::streaming::{EventLog, EventStream};

    // Workflow blueprints (v5)
    pub use crate::workflow::{
        WorkflowCompiler, WorkflowDefinition, WorkflowLoader, WorkflowValidator,
    };
}