CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a multi-agent roleplay system implementing Stanford's "Generative Agents" memory architecture for believable AI characters with emergent behaviors. The project currently uses OpenAI's API in the agent system but is transitioning to use a custom LLM connector that supports any OpenAI-compatible API endpoint.

Key Architecture Components

Agent System (agents.py)

Memory Stream: Stanford's memory architecture with observations, reflections, and plans
Smart Retrieval: Combines recency (exponential decay), importance (1-10 scale), and relevance (cosine similarity)
Auto-Reflection: Generates insights when importance threshold (150) is reached
Character Components: Character, CharacterAgent, MemoryStream, SceneManager
Currently uses OpenAI API directly but should be migrated to use llm_connector

LLM Connector Package

Custom LLM abstraction that supports any OpenAI-compatible API
Streaming support with both reasoning and content chunks
Type definitions: LLMBackend (base_url, api_token, model) and LLMMessage
Environment variables: BACKEND_BASE_URL, BACKEND_API_TOKEN, BACKEND_MODEL

UI Framework

NiceGUI for web interface (async components)
AsyncElement base class: Never override init, use create() factory method and implement build()
Dialog support: Can create elements as dialogs with as_dialog()
Pages are created in pages/ directory, main page is MainPage

Development Commands

# Install dependencies
uv sync

# Run the application
uv run python main.py
# Application runs on http://localhost:8080

# Add new dependencies
uv add <package-name>

# Python environment management
uv python pin 3.12  # Pin to Python 3.12

Important Development Notes

AsyncElement Usage

When creating UI components that extend AsyncElement:

NEVER override the init method
Always use the create() factory method: await MyComponent.create(params)
Implement the build() method for initialization logic
Pass parameters through build(), not init

LLM Integration

The project has two LLM integration approaches:

Legacy (in agents.py): Direct OpenAI client usage
Current (llm_connector): Flexible backend supporting any OpenAI-compatible API

When implementing new features, use the llm_connector package:

from llm_connector import get_response, LLMBackend, LLMMessage

backend: LLMBackend = {
    'base_url': os.environ['BACKEND_BASE_URL'],
    'api_token': os.environ['BACKEND_API_TOKEN'], 
    'model': os.environ['BACKEND_MODEL']
}

messages: List[LLMMessage] = [
    {'role': 'system', 'content': 'You are...'},
    {'role': 'user', 'content': 'Hello'}
]

# Non-streaming
response = await get_response(backend, messages, stream=False)

# Streaming
async for chunk in await get_response(backend, messages, stream=True):
    if 'content' in chunk:
        # Handle content
    if 'reasoning' in chunk:
        # Handle reasoning (if supported)

Project Structure

main.py: Entry point, NiceGUI app configuration
agents.py: Stanford memory architecture implementation (to be integrated)
llm_connector/: Custom LLM integration package
components/: Reusable UI components with AsyncElement base
pages/: UI pages (currently only MainPage)

Environment Variables

Required in .env:

BACKEND_BASE_URL: LLM API endpoint
BACKEND_API_TOKEN: API authentication token
BACKEND_MODEL: Model identifier
OPENAI_API_KEY: Currently needed for agents.py (to be removed)

Next Steps for Integration

The agents.py system needs to be:

Modified to use llm_connector instead of direct OpenAI client
Integrated into the NiceGUI web interface
Create UI components for character interaction, memory viewing, scene management
Implement real-time streaming of agent responses in the UI

3.9 KiB Raw Blame History