aimx/inference/
mod.rs

1//! # AIMX Inference Module
2//!
3//! The `inference` module provides the core functionality for integrating AI inference capabilities
4//! into AIMX expressions and workflows. This module handles everything from prompt generation and
5//! provider communication to response parsing and validation.
6//!
7//! ## Overview
8//!
9//! The inference system enables AIMX expressions to trigger AI model calls through special syntax:
10//! - `$tool.function_name(args)` - Inference calls to workflow nodes
11//! - `_variable_name` - Assignment rules populated by AI inference
12//! - `UPPERCASE_IDENTIFIER` - Modifier rules that construct prompts
13//!
14//! The module is organized into several submodules that handle different aspects of the inference
15//! pipeline:
16//!
17//! - [`item`] - Parse and represent inference data items (tasks, values, etc.)
18//! - [`key`] - Parse inference keys and unique component identifiers
19//! - [`prompt`] - Generate structured prompts for AI models
20//! - [`provider`] - Configure and manage AI model providers
21//! - [`request`] - Send inference requests to providers
22//! - [`response`] - Parse and interpret AI model responses
23//! - [`validate`] - Validate responses against workflow rules
24//!
25//! ## Core Workflow
26//!
27//! When an AIMX expression contains an inference call (e.g., `$tool.summarize_email(text)`),
28//! the system follows this pipeline:
29//!
30//! 1. **Reference Resolution** - The `$tool` prefix is resolved to a workflow node
31//! 2. **Prompt Generation** - Modifier rules from the workflow construct the prompt
32//! 3. **Provider Selection** - The appropriate AI model provider is selected
33//! 4. **Request Construction** - HTTP/REST requests are built for the provider API
34//! 5. **Response Handling** - Raw model responses are parsed and structured
35//! 6. **Validation** - Responses are validated against workflow rules
36//! 7. **Assignment** - Validated values populate assignment rules
37//!
38//! ## Usage Examples
39//!
40//! ```rust
41//! use aimx::inference::{Provider, Api, Model, Capability, send_request};
42//! 
43//! // Create a provider configuration for Ollama
44//! let provider = Provider {
45//!     api: Api::Ollama,
46//!     url: "http://localhost:11434".to_string(),
47//!     key: "".to_string(),  // No API key needed for local Ollama
48//!     model: Model::Standard,
49//!     capability: Capability::Standard,
50//!     fast: "mistral:latest".to_string(),
51//!     standard: "llama2:latest".to_string(),
52//!     planning: "codellama:latest".to_string(),
53//!     temperature: 0.7,
54//!     max_tokens: 2048,
55//!     connection_timeout_ms: 30000,
56//!     request_timeout_ms: 120000,
57//! };
58//! 
59//! // Send a request - this would typically be used internally by the inference system
60//! // let response = send_request(&provider, "You are a helpful assistant", "Hello!");
61//! ```
62//!
63//! ## Provider Support
64//!
65//! The inference module supports multiple AI providers:
66//!
67//! - **OpenAI** - GPT models via OpenAI API and compatible services like OpenRouter
68//! - **Ollama** - Local models via Ollama API
69//!
70//! Each provider can be configured with custom endpoints, API keys, and timeout settings.
71//!
72//! ## Error Handling
73//!
74//! The inference system provides comprehensive error handling:
75//!
76//! - **Provider Errors** - Connection failures, rate limits, authentication issues
77//! - **Parsing Errors** - Malformed responses, unexpected formats
78//! - **Validation Errors** - Response validation failures against workflow rules
79//! - **Timeout Errors** - Request timeouts and processing delays
80//!
81//! All errors are returned as [`anyhow::Result`] types for easy integration with error handling
82//! systems.
83//!
84//! ## Integration with AIMX Expressions
85//!
86//! Inference calls are seamlessly integrated into AIMX expressions:
87//!
88//! ```text
89//! // Call an inference tool from an expression
90//! summary: Text = $tool.summarize_email(email_body)
91//!
92//! // Use inference results in calculations
93//! sentiment_score: Number = $analyzer.get_sentiment(review) * 100
94//!
95//! // Chain inference calls with other operations
96//! classification: Text[] = $classifier.categorize(items).filter(cat => cat != "spam")
97//! ```
98//!
99//! This integration allows AIMX workflows to leverage AI capabilities while maintaining the
100//! familiar expression syntax and evaluation semantics.
101
102// Core inference submodules
103pub mod item;
104pub mod key;
105pub mod prompt;
106pub mod provider;
107pub mod request;
108pub mod response;
109pub mod validate;
110
111// Public API exports
112pub use item::{Item, parse_inline_item, parse_item};
113pub use key::{Suffix, parse_key, parse_ucid};
114pub use prompt::generate_prompt;
115pub use provider::{Api, Model, Capability, Provider};
116pub use request::send_request;
117pub use response::{Response, parse_response};
118pub use validate::validate_responses;
aimx/inference/mod.rs

aimx/inference/
mod.rs
