determinishtic 0.2.0

Blend deterministic Rust code with LLM-powered reasoning
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

# determinishtic

Blend deterministic Rust code with LLM-powered reasoning.

> *Hat tip to [Dave Herman](https://github.com/dherman) for the name.*

## Philosophy

**Do things deterministically that are deterministic.** File discovery, iteration, and I/O happen in Rust. Summarization, analysis, and judgment happen via the LLM.

```rust
use determinishtic::Determinishtic;
use sacp_tokio::AcpAgent;

#[tokio::main]
async fn main() -> Result<(), determinishtic::Error> {
    let d = Determinishtic::new(AcpAgent::zed_claude_code()).await?;

    // Rust handles the deterministic parts
    let files = std::fs::read_dir("./docs")?
        .filter_map(|e| e.ok())
        .filter(|e| e.path().extension() == Some("md".as_ref()))
        .collect::<Vec<_>>();

    for entry in files {
        let contents = std::fs::read_to_string(entry.path())?;

        // LLM handles the non-deterministic reasoning
        let summary: String = d.think()
            .text("Summarize in one sentence:")
            .display(&contents)
            .await?;

        println!("{}: {}", entry.path().display(), summary);
    }

    Ok(())
}
```

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
determinishtic = "0.1"
sacp = "11.0.0-alpha.1"

[dev-dependencies]
sacp-tokio = "11.0.0-alpha.1"
tokio = { version = "1.0", features = ["macros", "rt-multi-thread"] }
```

## Core Concepts

### `Determinishtic`

The main entry point. Wraps a connection to an LLM agent and provides the `think()` method.

```rust
// Connect to an agent
let d = Determinishtic::new(AcpAgent::zed_claude_code()).await?;

// Or use an existing connection (e.g., inside a proxy)
let d = Determinishtic::from_connection(cx.connection_to());
```

### `ThinkBuilder`

A builder for composing prompts with embedded tools. Created via `d.think()`.

```rust
let result: MyOutput = d.think()
    .text("Analyze this data:")
    .display(&data)
    .textln("")
    .text("Focus on trends and anomalies.")
    .await?;
```

The output type must implement `JsonSchema` and `Deserialize` - the LLM returns structured data by calling a `return_result` tool.

### Tools

Register tools that the LLM can call during reasoning:

```rust
use sacp::tool_fn_mut;

let mut results = Vec::new();

let output: Summary = d.think()
    .text("Process each item using the provided tool")
    .tool(
        "process_item",
        "Process a single item and return the result",
        async |input: ItemInput, _cx| {
            let output = process(&input);
            results.push(output.clone());
            Ok(output)
        },
        tool_fn_mut!(),
    )
    .await?;
```

Tools can capture references from the stack frame - no `'static` requirement. The `tool_fn_mut!()` macro is required due to Rust async closure limitations.

- `.tool()` - Register a tool and mention it in the prompt
- `.define_tool()` - Register a tool without mentioning it in the prompt

## Examples

Run the summarize_docs example:

```bash
cargo run --example summarize_docs -- --agent claude-code ./docs
```

Available agents: `claude-code`, `gemini`, `codex`

## Documentation

See the [mdbook](./md) for detailed documentation and RFCs.

## License

MIT OR Apache-2.0