zeph-orchestration 0.19.0

Task orchestration: DAG execution, failure propagation, and persistence for Zeph
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Multi-model task orchestration: DAG execution, failure propagation, and persistence.
//!
//! `zeph-orchestration` decomposes a user goal into a directed acyclic graph (DAG)
//! of sub-tasks, schedules them for concurrent execution by specialised sub-agents,
//! and synthesises the results into a coherent final response.
//!
//! # Architecture overview
//!
//! ```text
//! User goal
//!    │
//!    ▼
//! [Planner] ──LLM──► TaskGraph (DAG)
//!    │
//!    ▼
//! [DagScheduler] ──tick()──► SchedulerAction
//!    │                           │
//!    │          ┌────────────────┘
//!    │          ▼
//!    │      spawn sub-agent / run inline / cancel / done
//!    │
//!    ▼  (TaskEvent)
//! [DagScheduler] records outcome, applies failure strategy, routes next tasks
//!    │
//!    ▼
//! [Aggregator] ──LLM──► synthesised response
//! ```
//!
//! # Core types
//!
//! - [`TaskGraph`] / [`TaskNode`] — the DAG and its nodes
//! - [`DagScheduler`] — drives execution, emits [`SchedulerAction`]s
//! - [`Planner`] / [`LlmPlanner`] — decomposes a goal into a [`TaskGraph`]
//! - [`Aggregator`] / [`LlmAggregator`] — synthesises completed task outputs
//! - [`AgentRouter`] / [`RuleBasedRouter`] — selects the best agent for a task
//! - [`PlanCache`] — caches and reuses completed plan skeletons
//! - [`PlanVerifier`] — post-task completeness verifier with targeted replan
//!
//! # Feature flags
//!
//! This crate has no optional Cargo features. All orchestration primitives are
//! always available when the crate is in the dependency graph.
//!
//! # Example: build a plan and run the scheduler
//!
//! ```rust,ignore
//! use zeph_orchestration::{LlmPlanner, DagScheduler, RuleBasedRouter};
//! use zeph_config::OrchestrationConfig;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let config = OrchestrationConfig::default();
//! let planner = LlmPlanner::new(my_provider, &config);
//! let (graph, _usage) = planner.plan("build and deploy service", &agents).await?;
//!
//! let scheduler = DagScheduler::new(
//!     graph,
//!     &config,
//!     Box::new(RuleBasedRouter),
//!     agents.clone(),
//! )?;
//! // drive the scheduler loop …
//! # Ok(())
//! # }
//! ```

#[allow(unused_imports)]
pub(crate) use zeph_db::sql;

pub mod aggregator;
pub mod cascade;
pub mod command;
pub mod dag;
pub mod error;
pub mod graph;
pub mod plan_cache;
pub mod planner;
pub mod router;
pub mod scheduler;
pub mod topology;
pub mod verifier;

pub use aggregator::{Aggregator, LlmAggregator};
pub use cascade::{CascadeConfig, CascadeDetector, RegionHealth};
pub use command::PlanCommand;
pub use error::OrchestrationError;
pub use graph::{
    ExecutionMode, FailureStrategy, GraphId, GraphPersistence, GraphStatus, TaskGraph, TaskId,
    TaskNode, TaskResult, TaskStatus,
};
pub use plan_cache::{
    PlanCache, PlanCacheError, PlanTemplate, TemplateTask, normalize_goal, plan_with_cache,
};
pub use planner::{LlmPlanner, Planner};
pub use router::{AgentRouter, RuleBasedRouter};
pub use scheduler::{DagScheduler, SchedulerAction, TaskEvent, TaskOutcome};
pub use topology::{DispatchStrategy, Topology, TopologyAnalysis, TopologyClassifier};
pub use verifier::{Gap, GapSeverity, PlanVerifier, VerificationResult};