nika-core 0.72.0

Lightweight AST and analysis core for Nika workflows
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
101
102
103
104
105
106
107
108
109
110
111
112
113

//! AST Module - Abstract Syntax Tree for YAML workflows
//!
//! # Three-Phase Pipeline
//!
//! ```text
//! YAML -> raw::parse -> analyzer::analyze -> AnalyzedWorkflow
//! ```
//!
//! 1. **raw** -- Parsed from YAML with full span tracking (line:col)
//! 2. **analyzed** -- Validated, references resolved, TaskId interning
//!
//! The lowering step (analyzed -> runtime types) lives in the `nika` crate,
//! since it depends on runtime types not available here.
//!
//! # Modules
//!
//! ## Pipeline
//! - `raw`: Raw AST with `Spanned<T>` fields for precise error locations
//! - `analyzed`: Validated AST with TaskId interning and semantic checks
//! - `analyzer`: Validation and transformation (raw -> analyzed)
//!
//! ## Type Modules
//! - `schema`: SchemaVersion enum
//! - `budget`: YAML bomb protection (Budget, from_str_with_budget)
//! - `output`: OutputPolicy, OutputFormat, SchemaRef
//! - `decompose`: DecomposeSpec, DecomposeStrategy
//! - `context`: ContextConfig (file loading at workflow start)
//! - `logging`: LogConfig, LogLevel, LogFormat
//! - `structured`: StructuredOutputSpec (JSON schema enforcement)
//! - `agent_def`: AgentDef (reusable agent configurations)
//! - `artifact`: ArtifactsConfig, ArtifactSpec (file persistence)
//! - `content`: ContentPart types (multimodal vision support)
//! - `limits`: LimitsConfig (agent resource limits)
//! - `include`: IncludeSpec (DAG fusion)

// Pipeline stages
pub mod analyzed;
pub mod analyzer;
pub mod raw;
pub mod schema;

// Security - YAML bomb protection
pub mod budget;

// Vision/multimodal content parts
pub mod content;

// Type modules
pub mod agent_def;
pub mod artifact;
pub mod completion;
pub mod context;
pub mod decompose;
pub mod extract;
pub mod guardrails;
pub mod include;
pub mod limits;
pub mod logging;
pub mod orchestrate;
pub mod output;
pub mod record;
pub mod routing;
pub mod schedule;
pub mod structured;

// Re-export key types for convenient access
pub use agent_def::AgentDef;
pub use context::ContextConfig;
pub use decompose::{DecomposeSpec, DecomposeStrategy};
pub use extract::{ExtractMode, ResponseMode};
pub use include::IncludeSpec;
pub use limits::{LimitAction, LimitStatus, LimitType, LimitsConfig, OnLimitReachedConfig};
pub use logging::{LogConfig, LogFormat, LogLevel};
pub use orchestrate::OrchestrateConfig;
pub use output::{OutputFormat, OutputPolicy, SchemaRef};
pub use record::RecordSpec;
pub use routing::RoutingConfig;
pub use schema::SchemaVersion;
pub use structured::StructuredOutputSpec;

// ============================================================================
// Unified Pipeline: YAML -> Raw -> Analyzed
// ============================================================================

use crate::ast::analyzed::AnalyzedWorkflow;
use crate::error::CoreError;
use crate::source::FileId;

/// Parse a YAML workflow and return the AnalyzedWorkflow directly.
///
/// Pipeline: `YAML -> raw::parse -> analyzer::analyze -> AnalyzedWorkflow`
///
/// # Errors
///
/// - `CoreError::ValidationError` -- YAML syntax or structural errors (Phase 1)
/// - `CoreError::ValidationError` -- Semantic validation errors (Phase 2)
pub fn parse_analyzed(yaml: &str) -> Result<AnalyzedWorkflow, CoreError> {
    // Phase 1: YAML -> Raw AST (with span tracking)
    let raw = raw::parse(yaml, FileId(0)).map_err(|e| CoreError::ValidationError {
        reason: format!("[{}] {}", e.kind.code(), e.message),
    })?;

    // Phase 2: Raw -> Analyzed (validation, reference resolution)
    analyzer::analyze(raw).into_result().map_err(|errors| {
        let messages: Vec<String> = errors
            .iter()
            .map(|e| format!("[{}] {}", e.kind.code(), e))
            .collect();
        CoreError::ValidationError {
            reason: messages.join("; "),
        }
    })
}