Epsimo Agent Framework

Beta Release — Build sophisticated AI-powered applications with agents, persistent threads, and Virtual Database state management.

The Epsimo Agent Framework provides a unified CLI, Python SDK, and React UI Kit for building AI applications with:

• 🤖 Multi-agent orchestration
• 💾 Virtual Database (thread-based persistent state)
• 💬 Streaming conversations with tool support
• 🎨 Pre-built React components
• 🔌 Extensible tool library

Base URL: https://api.epsimoagents.com
Frontend: https://app.epsimoagents.com

📦 Installation

For AI Coding Agents (Recommended)

Install as a skill for Claude Code, Cursor, Cline, Windsurf, and 30+ other AI coding agents:

npx skills add thierryteisseire/epsimo-agent

This installs the skill across all your AI agents in one command! The skill helps agents:

• Set up Epsimo projects quickly
• Manage agents and threads
• Query the Virtual Database
• Deploy configurations
• Handle authentication flows

npm Package (Global Installation)

npm install -g epsimo-agent

Python SDK & CLI

# Install from PyPI (coming soon)
pip install epsimo-agent

# Or install from source
git clone https://github.com/thierryteisseire/epsimo-agent.git
cd epsimo-agent
pip install -r requirements.txt

# Make CLI executable
chmod +x epsimo/cli.py
export PATH="$PATH:$(pwd)/epsimo"

🚀 Quick Start

1. Authentication

# Login to Epsimo
epsimo auth login

# Check who you're logged in as
epsimo whoami

# Check thread/credit balance
epsimo credits balance

2. Create Your First Project

# Create a new Next.js project with Epsimo
epsimo create "My AI App"

# Or initialize in existing directory
cd my-existing-project
epsimo init

3. Deploy Configuration

# Sync your epsimo.yaml to the platform
epsimo deploy

🛠️ CLI Reference

Authentication Commands

epsimo auth login              # Interactive login
epsimo whoami                  # Display current user info

Project Management

epsimo projects                # List all projects
epsimo create <name>           # Scaffold a new Next.js app
epsimo init                    # Initialize existing directory
epsimo deploy                  # Deploy epsimo.yaml configuration

Virtual Database

epsimo db query --project-id <P_ID> --thread-id <T_ID>
epsimo db set --project-id <P_ID> --thread-id <T_ID> --key <K> --value <V>
epsimo db get --project-id <P_ID> --thread-id <T_ID> --key <K>

Credits & Billing

epsimo credits balance                  # Check thread balance
epsimo credits buy --quantity <N>       # Generate Stripe checkout URL

Resource Listing

epsimo assistants --project-id <P_ID>  # List assistants
epsimo threads --project-id <P_ID>     # List threads

📚 Python SDK

Installation

from epsimo import EpsimoClient

# Initialize with API key (JWT token)
client = EpsimoClient(api_key="your-token-here")

# Or use environment variable
# export EPSIMO_API_KEY=your-token-here
client = EpsimoClient()

Virtual Database Access

# Get all structured data from a thread
db_state = client.db.get_all(project_id, thread_id)

# Get specific key
user_prefs = client.db.get(project_id, thread_id, "user_preferences")
print(f"Theme: {user_prefs.get('theme')}")

# Set value (for seeding/testing)
client.db.set(project_id, thread_id, "status", "active")

Streaming Conversations

# Stream assistant responses
for chunk in client.threads.run_stream(
    project_id, 
    thread_id, 
    assistant_id, 
    "Hello, how can you help me?"
):
    print(chunk, end="", flush=True)

Managing Resources

# Projects
projects = client.projects.list()
project = client.projects.create(name="My Project", description="...")
project_details = client.projects.get(project_id)

# Assistants
assistants = client.assistants.list(project_id)
assistant = client.assistants.create(project_id, config={...})

# Threads
threads = client.threads.list(project_id)
thread = client.threads.create(project_id, assistant_id=assistant_id)

# Files
files = client.files.list(project_id)
file = client.files.upload(project_id, file_path="document.pdf")

# Credits
balance = client.credits.get_balance()
checkout_url = client.credits.create_checkout_session(quantity=1000, amount=100.0)

🎨 React UI Kit

ThreadChat Component

import { ThreadChat } from "@/components/epsimo";

export default function App() {
  return (
    <ThreadChat 
      assistantId="your-assistant-id"
      projectId="your-project-id"
      placeholder="Ask me anything..."
    />
  );
}

useChat Hook (Headless)

import { useChat } from "@/hooks/epsimo";

export default function CustomChat() {
  const { messages, sendMessage, isLoading } = useChat({
    projectId: "...",
    threadId: "...",
    assistantId: "..."
  });

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <button onClick={() => sendMessage("Hello")} disabled={isLoading}>
        Send
      </button>
    </div>
  );
}

🧪 Tool Library

The framework includes reusable tool schemas in epsimo/tools/library.yaml:

Available Tools

| Tool | Type | Description | |------|------|-------------| | database_sync | function | Persist structured JSON to thread state (Virtual DB) | | web_search_tavily | search_tavily | Advanced web search with source attribution | | web_search_ddg | ddg_search | Fast DuckDuckGo search for simple queries | | retrieval_optimized | retrieval | High-accuracy document search in uploaded files | | task_management | function | Track and update user tasks |

Using Tools in Assistants

# epsimo.yaml
assistants:
  - name: "Research Assistant"
    model: "gpt-4o"
    instructions: "You help with research tasks"
    tools:
      - type: search_tavily
        max_results: 5
      - type: function
        name: update_database
        description: "Save research findings"
        parameters:
          type: object
          properties:
            key: { type: string }
            value: { type: object }

💾 Virtual Database Pattern

Threads serve as persistent, structured storage — eliminating the need for a separate database.

How It Works

1. Agent writes to DB using the update_database tool
2. Data persists in thread state
3. Query from SDK or CLI:

# Python SDK
preferences = client.db.get(project_id, thread_id, "user_preferences")

# CLI
epsimo db query --project-id P123 --thread-id T456

Benefits

• ✅ Zero database configuration
• ✅ Data naturally partitioned by conversation
• ✅ Agent always "knows" what's in its DB
• ✅ Queryable from both agent and application code

See docs/virtual_db_guide.md for detailed guide.

🔐 Authentication & Security

Environment Variables

# .env file (never commit!)
EPSIMO_API_KEY=your-jwt-token-here
[email protected]
EPSIMO_PASSWORD=your-password  # Only for automated scripts

Token Management

from epsimo.auth import get_token, perform_login

# Login programmatically
token = perform_login("[email protected]", "password")

# Get cached token (auto-refreshes if expired)
token = get_token()

Token Storage: Tokens are stored in ~/code/epsimo-frontend/.epsimo_token (configurable via TOKEN_FILE in auth.py)

Security Best Practices:

• Never commit .epsimo_token or .env files
• Use environment variables in production
• Rotate tokens regularly
• Use project-specific tokens for multi-tenant apps

📖 API Reference

See references/api_reference.md for comprehensive endpoint documentation including:

• Authentication flows
• Request/response schemas
• HTTP status codes
• Error handling patterns
• Rate limits

🧪 Verification & Testing

# Verify skill is correctly configured
python3 verify_skill.py

# Run E2E test suite
python3 scripts/test_all_skills.py

# Test streaming functionality
python3 scripts/test_streaming.py

# Test Virtual DB
python3 scripts/test_vdb.py

📁 Project Structure

epsimo-agent/
├── epsimo/
│   ├── cli.py              # Unified CLI
│   ├── client.py           # Main SDK client
│   ├── auth.py             # Authentication logic
│   ├── resources/          # Resource-specific clients
│   │   ├── projects.py
│   │   ├── assistants.py
│   │   ├── threads.py
│   │   ├── files.py
│   │   ├── credits.py
│   │   └── db.py
│   ├── tools/
│   │   └── library.yaml    # Reusable tool schemas
│   └── templates/          # Project scaffolding templates
├── scripts/                # Helper scripts and examples
├── docs/                   # Additional documentation
├── references/             # API reference docs
├── SKILL.md                # Main skill documentation
└── README.md               # This file

🤝 Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

📄 License

MIT License - see LICENSE for details.

🔗 Links

Installation & Discovery

• skills.sh: Search for "epsimo-agent" at https://skills.sh
• npm Package: https://www.npmjs.com/package/epsimo-agent
• Install Command: npx skills add thierryteisseire/epsimo-agent

Documentation

• Skill Guide: SKILL.md
• API Reference: references/api_reference.md
• Virtual DB Guide: docs/virtual_db_guide.md

Platform

• GitHub Repository: https://github.com/thierryteisseire/epsimo-agent
• Epsimo Web App: https://app.epsimoagents.com
• API Endpoint: https://api.epsimoagents.com

Questions? Open an issue on GitHub or check the API Reference.