Skip to content

API.md

Latest commit

 

History

History
639 lines (437 loc) · 10.1 KB

API.md

File metadata and controls

639 lines (437 loc) · 10.1 KB

API Documentation

Table of Contents

  1. LLM Module
  2. Agent Module
  3. App Module
  4. Config Module
  5. UI Module

LLM Module

The LLM module handles communication with Large Language Model APIs.

Types

Message

Represents a message in the conversation.

pub struct Message {
    pub role: String,    // "user", "assistant", or "system"
    pub content: String, // Message content
}

Methods:

  • new(role: &str, content: &str) -> Self
    • Creates a new message with the given role and content

LlmResponse

Represents a response from the LLM API.

pub struct LlmResponse {
    pub content: String,              // Response text
    pub tool_calls: Vec<ToolCall>,    // Requested tool calls
    pub tokens_used: u64,             // Tokens consumed
}

Functions

send_message

pub async fn send_message(
    config: &LlmConfig,
    messages: &[Message],
) -> Result<LlmResponse, Box<dyn std::error::Error>>

Sends a message to the LLM API and returns the response.

Parameters:

  • config: LLM configuration (API key, base URL, model)
  • messages: Conversation history

Returns:

  • Ok(LlmResponse): Successful response with content and tool calls
  • Err(error): API error, network error, or parse error

Example:

let config = LlmConfig { /* ... */ };
let messages = vec![
    Message::new("user", "Hello!"),
];
let response = send_message(&config, &messages).await?;
println!("Response: {}", response.content);

send_message_streaming

pub async fn send_message_streaming(
    config: &LlmConfig,
    messages: &[Message],
    callback: impl Fn(String),
) -> Result<LlmResponse, Box<dyn std::error::Error>>

Sends a message with streaming support, calling the callback for each chunk.

Parameters:

  • config: LLM configuration
  • messages: Conversation history
  • callback: Function called with each content chunk

Returns:

  • Ok(LlmResponse): Complete response after streaming
  • Err(error): API or network error

Example:

let response = send_message_streaming(&config, &messages, |chunk| {
    print!("{}", chunk);
}).await?;

estimate_tokens

pub fn estimate_tokens(text: &str) -> u64

Estimates the number of tokens in a text string.

Parameters:

  • text: Text to estimate

Returns:

  • Estimated token count (approximately text.len() / 4)

Note: This is a rough approximation. Actual token counts may vary by model.

format_tool_results

pub fn format_tool_results(tool_results: &[(String, String)]) -> String

Formats tool execution results for sending back to the LLM.

Parameters:

  • tool_results: Vector of (tool_name, result) tuples

Returns:

  • Formatted string describing tool results

Agent Module

The agent module provides tool execution capabilities.

Types

ToolCall

Represents a tool call requested by the LLM.

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ToolCall {
    pub id: String,
    pub name: String,
    pub arguments: serde_json::Value,
}

Fields:

  • id: Unique identifier for the tool call
  • name: Name of the tool to execute
  • arguments: JSON object with tool arguments

Functions

execute_tool

pub async fn execute_tool(
    tool_name: &str,
    arguments: &serde_json::Value,
) -> Result<String, String>

Executes a tool by name with the given arguments.

Parameters:

  • tool_name: Name of the tool to execute
  • arguments: JSON object with tool-specific arguments

Returns:

  • Ok(String): Tool execution result
  • Err(String): Error message

Example:

let args = json!({
    "path": "example.txt"
});
let result = execute_tool("read_file", &args).await?;

Available Tools

File Operations

read_file

Read the contents of a file.

Arguments:

{
    "path": "file/path.txt"
}

Returns: File contents as string

write_file

Write content to a file (overwrites existing content).

Arguments:

{
    "path": "file/path.txt",
    "content": "Content to write"
}

Returns: Success message

append_to_file

Append content to the end of a file.

Arguments:

{
    "path": "file/path.txt",
    "content": "Content to append"
}

Returns: Success message

search_and_replace

Search for text in a file and replace it.

Arguments:

{
    "path": "file/path.txt",
    "search": "text to find",
    "replace": "replacement text"
}

Returns: Success message with replacement count

delete_file

Delete a file or directory.

Arguments:

{
    "path": "file/path.txt"
}

Returns: Success message

Directory Operations

create_directory

Create a directory (including parent directories).

Arguments:

{
    "path": "dir/subdir"
}

Returns: Success message

list_directory

List contents of a directory (non-recursive).

Arguments:

{
    "path": "directory/path"
}

Returns: List of files and directories

list_directory_recursive

List contents of a directory recursively.

Arguments:

{
    "path": "directory/path"
}

Returns: Tree structure of files and directories

Code Execution

execute_python

Execute Python code.

Arguments:

{
    "code": "print('Hello, World!')"
}

Returns: Standard output and error from execution

execute_bash

Execute bash commands.

Arguments:

{
    "command": "ls -la"
}

Returns: Command output

execute_node

Execute Node.js code.

Arguments:

{
    "code": "console.log('Hello');"
}

Returns: Standard output from execution

execute_ruby

Execute Ruby code.

Arguments:

{
    "code": "puts 'Hello'"
}

Returns: Standard output from execution

Plan Management

create_plan

Create a development plan in plan.md.

Arguments:

{
    "plan": "## Phase 1\n- [ ] Step 1\n- [ ] Step 2"
}

Returns: Success message

update_plan_step

Update the status of a plan step.

Arguments:

{
    "step_number": 1,
    "new_status": "completed"
}

Returns: Success message

clear_plan

Clear the current plan.

Arguments: None

Returns: Success message

Git Operations

git_status

Get git repository status.

Arguments: None

Returns: Git status output

App Module

The app module manages application state.

Types

App

Main application state.

pub struct App {
    pub user_input: String,
    pub conversation: Vec<String>,
    pub status_message: String,
    pub tool_logs: Vec<String>,
    pub is_executing_tool: bool,
    pub current_tool: String,
    pub session_start_time: std::time::Instant,
    pub tokens_used: u64,
    pub total_requests: u64,
    pub total_tools_executed: u64,
    pub conversation_scroll_position: usize,
    pub tool_logs_scroll_position: usize,
    pub is_streaming: bool,
    pub current_streaming_message: String,
}

Methods

new

pub fn new() -> Self

Creates a new App instance with default values.

add_tool_log

pub fn add_tool_log(&mut self, log: String)

Adds a log entry to the tool logs.

Usage Tracking

pub fn increment_tokens(&mut self, tokens: u64)
pub fn increment_requests(&mut self)
pub fn increment_tools_executed(&mut self)
pub fn get_session_duration(&self) -> std::time::Duration
pub fn get_usage_summary(&self) -> String

Methods for tracking and reporting usage statistics.

Scrolling

pub fn scroll_conversation_up(&mut self)
pub fn scroll_conversation_down(&mut self)
pub fn scroll_conversation_to_top(&mut self)
pub fn scroll_conversation_to_bottom(&mut self)

Methods for managing conversation scroll position.

Streaming

pub fn start_streaming(&mut self)
pub fn update_streaming_message(&mut self, new_content: &str)
pub fn finish_streaming(&mut self, final_message: String)

Methods for managing streaming response state.

Config Module

The config module handles configuration loading.

Types

Config

Main configuration structure.

pub struct Config {
    pub llm: LlmConfig,
}

LlmConfig

LLM-specific configuration.

pub struct LlmConfig {
    pub provider: Option<String>,
    pub api_key: String,
    pub api_base_url: String,
    pub model_name: String,
}

Methods

from_file

pub fn from_file(path: &str) -> Result<Self, io::Error>

Loads configuration from a TOML file.

Parameters:

  • path: Path to config file

Returns:

  • Ok(Config): Loaded configuration
  • Err(io::Error): File not found or parse error

Example:

let config = Config::from_file("config.toml")?;
println!("Model: {}", config.llm.model_name);

UI Module

The UI module handles terminal rendering.

Functions

ui

pub fn ui<B: Backend>(f: &mut Frame<B>, app: &App)

Renders the terminal UI for the given app state.

Parameters:

  • f: Ratatui frame for rendering
  • app: Current application state

Layout:

  • Top 70%: Conversation area
  • Next 20%: Tool logs area
  • Next line: Status bar
  • Bottom: Input area

Scrolling:

  • Automatically clamps scroll positions to valid ranges
  • Shows indicators when there's more content to scroll

Error Handling

All functions that can fail return Result types:

  • Ok(value): Successful execution
  • Err(error): Error occurred

Error types:

  • Box<dyn std::error::Error>: Generic error for API/network issues
  • String: Simple error messages for tool execution
  • io::Error: File system errors

Thread Safety

  • Config and LlmConfig: Clone + Send + Sync
  • Message: Clone + Send + Sync
  • App: Not thread-safe (single-threaded UI)

Async Support

Async functions require a Tokio runtime:

#[tokio::main]
async fn main() {
    let result = send_message(&config, &messages).await;
}