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

Agent writes to DB using the update_database tool
Data persists in thread state
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
EPSIMO_EMAIL=your@email.com
EPSIMO_PASSWORD=your-password  # Only for automated scripts

Token Management

from epsimo.auth import get_token, perform_login

# Login programmatically
token = perform_login("your@email.com", "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.

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
assets		assets
bin		bin
docs		docs
epsimo		epsimo
references		references
scripts		scripts
skills/epsimo-agent		skills/epsimo-agent
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
epsimo.yaml		epsimo.yaml
install.ps1		install.ps1
install.sh		install.sh
package.json		package.json
proj_debug.json		proj_debug.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
test_sdk.py		test_sdk.py
thread_state.json		thread_state.json
verify_skill.py		verify_skill.py

Folders and files

Latest commit

History

Repository files navigation