aidale-core 0.1.0

Core abstractions and runtime for Aidale - Rust AI SDK
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# aidale-core

Core abstractions and runtime for Aidale - Rust AI SDK.

[![Crates.io](https://img.shields.io/crates/v/aidale-core.svg)](https://crates.io/crates/aidale-core)
[![Documentation](https://docs.rs/aidale-core/badge.svg)](https://docs.rs/aidale-core)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](../LICENSE)

## Overview

`aidale-core` provides the foundational traits and runtime for the Aidale ecosystem:

- **Provider Trait**: Abstract interface for AI service providers
- **Layer Trait**: Composable middleware system (AOP pattern)
- **Plugin Trait**: Runtime extension hooks for business logic
- **Strategy Trait**: Provider-specific adaptation patterns
- **RuntimeExecutor**: High-level orchestration and execution engine

## Core Concepts

### Provider

Pure HTTP client abstraction for AI services:

```rust
#[async_trait]
pub trait Provider: Send + Sync {
    fn id(&self) -> &str;
    fn name(&self) -> &str;

    async fn chat_completion(
        &self,
        model: &str,
        params: ChatCompletionParams,
    ) -> Result<ChatCompletionResponse>;

    async fn stream_chat_completion(
        &self,
        model: &str,
        params: ChatCompletionParams,
    ) -> Result<impl Stream<Item = Result<ChatCompletionChunk>>>;
}
```

### Layer

Composable middleware with zero-cost abstraction:

```rust
#[async_trait]
pub trait Layer<P: Provider>: Send + Sync {
    async fn call(
        &self,
        provider: &P,
        model: &str,
        params: ChatCompletionParams,
    ) -> Result<ChatCompletionResponse>;
}
```

Layers are composed at compile-time using type-level recursion for static dispatch.

### Plugin

Runtime extension points for business logic:

```rust
#[async_trait]
pub trait Plugin: Send + Sync {
    async fn on_request(&self, ctx: &mut RequestContext) -> Result<()>;
    async fn on_response(&self, ctx: &mut ResponseContext) -> Result<()>;
    async fn on_error(&self, ctx: &mut ErrorContext) -> Result<()>;
}
```

### RuntimeExecutor

High-level API combining strategies, layers, and plugins:

```rust
let executor = RuntimeExecutor::builder(provider)
    .layer(LoggingLayer::new())
    .plugin(Arc::new(ToolUsePlugin::new(tools)))
    .finish();

let result = executor.generate_text(model, params).await?;
```

## Usage

This crate is typically used indirectly through the main `aidale` crate:

```toml
[dependencies]
aidale = "0.1"
```

For direct usage:

```toml
[dependencies]
aidale-core = "0.1"
```

## Features

- **Zero-cost abstractions**: Static dispatch via compile-time composition
- **Type safety**: Leverage Rust's type system for correctness
- **Async-first**: Built on `tokio` and `async-trait`
- **Extensible**: Clear extension points via traits

## Architecture

```
┌─────────────────────────────────────┐
│      RuntimeExecutor                │  High-level API
│  - generate_text()                  │  + Plugin orchestration
│  - generate_object()                │  + Strategy selection
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│      Layers (AOP)                   │  Middleware stack
│  Logging → Retry → Cache            │  (Static dispatch)
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│      Provider                       │  HTTP client
│  - chat_completion()                │  (No business logic)
└─────────────────────────────────────┘
```

## Related Crates

- [`aidale`](../aidale) - Main meta-crate
- [`aidale-provider`](../aidale-provider) - Provider implementations
- [`aidale-layer`](../aidale-layer) - Built-in layers
- [`aidale-plugin`](../aidale-plugin) - Built-in plugins

## License

MIT OR Apache-2.0