'Simulacra01: Complete Guide to Building Local AI Agents with OpenAI Agents [post] deterministic


Comprehensive Guide to Simulacra01

This guide provides detailed documentation on how to use, customize, and extend Simulacra01, a framework that integrates the OpenAI Agents SDK with Ollama for local AI agent capabilities.

Table of Contents

1. [Introduction](#introduction) 2. [Understanding the Architecture](#understanding-the-architecture) 3. [Installation & Setup](#installation--setup) 4. [Using Document Analysis Agent](#using-document-analysis-agent) 5. [Working with the Command-Line Interface](#working-with-the-command-line-interface) 6. [Creating Custom Agents](#creating-custom-agents) 7. [Advanced Customization](#advanced-customization) 8. [Debugging and Troubleshooting](#debugging-and-troubleshooting) 9. [Performance Optimization](#performance-optimization) 10. [Contributing and Development](#contributing-and-development)

Introduction

Simulacra01 is a powerful framework that brings together the structured agent capabilities of OpenAI's Agents SDK with the privacy and cost benefits of local LLM inference through Ollama. This integration enables you to build sophisticated AI agents that run entirely on your local infrastructure.

Key Benefits

• **Complete Data Privacy**: All processing happens locally, with no data sent to external services
• **Cost Efficiency**: No per-token API costs associated with cloud-based LLM services
• **Customizability**: Full control over model selection, fine-tuning, and behavior
• **Network Independence**: Agents function without requiring internet access
• **Reduced Latency**: Eliminate network roundtrips for faster responses

Core Components

• **OpenAI Agents SDK**: Provides the structured framework for building AI agents
• **Ollama**: Enables local running of various open-source LLMs
• **Adapter Layer**: Connects the two technologies seamlessly
• **Specialized Agents**: Pre-built agents for document analysis and other tasks
• **Command-Line Interface**: Interactive way to engage with agents

Understanding the Architecture

Simulacra01 employs a layered architecture designed for flexibility and extensibility:

Ollama Layer

The base layer provides LLM inference capabilities:

• Handles model loading and management
• Processes raw prompts into completions
• Manages system resources for inference
• Provides API endpoints that mimic OpenAI's structure

Adapter Layer

The bridge between Ollama and the OpenAI Agents SDK:

• OllamaClient: Routes requests to Ollama's API endpoints
• AgentAdapter: Makes OpenAI's Agent class compatible with the Ollama backend
• ResponseFormatter: Ensures responses match expected formats
• ToolCallProcessor: Handles function/tool calls with local models

Agents SDK Layer

Provides the agent framework and abstractions:

• Agent lifecycle management
• Tool definition and integration
• Conversation handling
• Response processing

Application Layer

Implements specialized agents and interfaces:

• Document Analysis Agent
• Command-Line Interface
• Document Memory system
• Other specialized agent types

Installation & Setup

System Requirements

• Python 3.9 or higher
• 8GB+ RAM recommended (model dependent)
• 2GB+ free disk space for model storage

Step 1: Install Ollama

For macOS and Linux:

bash curl -fsSL https://ollama.ai/install.sh | sh

For Windows, download from [Ollama's website](https://ollama.com/download).

Verify installation:

bash ollama --version

Step 2: Download Required Models

```bash # Pull the Mistral model (recommended starting model) ollama pull mistral

Optional: Pull additional models ollama pull llama3 ollama pull mixtral ```

Verify model installation:

bash ollama list

Step 3: Clone and Install Simulacra01

bash git clone https://github.com/kliewerdaniel/simulacra01.git cd simulacra01 pip install -e .

Step 4: Install Dependencies

bash pip install -r requirements.txt

Step 5: Verify Installation

Run the basic test script:

bash python -c "from ollama_client import OllamaClient; client = OllamaClient(); response = client.chat.completions.create(model='mistral', messages=[{'role': 'user', 'content': 'Hello, world!'}]); print(response.choices[0].message.content)"

You should see a response from the model.

Using Document Analysis Agent

The Document Analysis Agent is a powerful tool for extracting information from documents, answering questions about content, and managing a document repository.

Basic Usage

Run the document agent:

bash python main.py

This will start an interactive session with the agent.

Available Commands

• exit: Exit the agent
• help: Show help information
• list: List documents in memory

Example Interactions

Analyze a webpage: `` You: Please analyze the article at https://en.wikipedia.org/wiki/Artificial_intelligence and tell me when AI was first developed.

Extract specific information: `` You: Extract all the dates mentioned in the last document.

Search for content: `` You: Find information about neural networks in the document.

Tool Functionality

The Document Analysis Agent includes several specialized tools:

#### fetch_document

Retrieves document content from a URL:

python fetch_document(url="https://example.com/article")

This tool: - Checks if the document is already in memory - If not, fetches it from the URL - Stores it in document memory for future use - Returns the document content

#### extract_info

Extracts specific types of information from text:

python extract_info(text="document content", info_type="dates")

Common info types: - dates: Extracts dates and timestamps - names: Extracts person names - organizations: Extracts organization names - key points: Extracts main ideas or arguments - statistics: Extracts numerical data and statistics

#### search_document

Searches document content for relevant information:

python search_document(text="document content", query="neural networks")

This uses semantic search to find the most relevant paragraphs for the query.

Document Memory

The Document Memory system provides persistent storage for documents:

```python from document_memory import DocumentMemory

Initialize memory memory = DocumentMemory()

Store a document doc_id = memory.store_document( url="https://example.com/article", content="Document text goes here...", metadata={"author": "John Doe", "date": "2025-03-13"} )

Retrieve a document doc = memory.get_document(doc_id) print(doc["content"])

List all documents docs = memory.list_documents() for doc in docs: print(f"URL: {doc['url']}") ```

Document memory is stored on disk and persists between sessions.

Working with the Command-Line Interface

The Simulacra01 CLI provides a comprehensive interface for interacting with various agent types.

Starting the CLI

```bash # Start with interactive menu python cli.py

Start directly with a specific agent python cli.py chat --agent document python cli.py chat --agent research ```

Global Commands

These commands work across all agent types:

• exit: End the current session
• help: Show available commands
• clear: Clear the conversation history
• save [filename]: Save the current conversation
• load <filename>: Load a saved conversation
• list: List saved conversations
• tools: List available tools

Agent-Specific Commands

#### Document Agent

• list docs: List stored documents
• analyze <url>: Analyze a document at URL

#### Research Agent

• search <topic>: Research a topic
• synthesize: Summarize research findings
• save research <filename>: Save research data

#### Task Agent

• add task <title>: Add a new task
• list tasks: Show all tasks
• update task <id>: Update task status

Configuration

Configure the CLI using:

bash python cli.py config

This allows you to customize:

• OpenAI and Ollama