pyeve 0.1.1

Filesystem-first framework for durable backend AI agents in Python

pyeve is a filesystem-first framework for durable backend AI agents in Python. Core agent capabilities live in conventional locations, so projects are easier to inspect, extend, and operate.

The filesystem is the authoring interface

A typical pyeve agent has this structure:

my-agent/
└── agent/
    ├── agent.py            # model and runtime config
    ├── instructions.md     # always-on system prompt
    └── tools/              # functions the model can call
        └── get_weather.py

Quick start

pip install pyeve
pyeve init my-agent
cd my-agent
pyeve dev

Your agent is running at http://localhost:8000.

A minimal example

Replace agent/instructions.md with:

You are a concise weather assistant. Tell users that the weather data is mocked.

Add a tool at agent/tools/get_weather.py:

async def execute(city: str) -> dict:
    """Return current weather for a city."""
    return {"city": city, "condition": "Sunny", "temp_f": 72}

Configure the model in agent/agent.py:

from pyeve import define_agent
from pyeve.adapters.anthropic import AnthropicAdapter

agent = define_agent(
    model="claude-sonnet-4-6",
    adapter=AnthropicAdapter(),
)

Send a message:

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the weather in Berlin?"}'

Response streams as Server-Sent Events.

Tools are plain async functions

No decorators, no schema classes. pyeve reads the docstring as the description and infers the JSON schema from type hints.

# agent/tools/search.py
async def execute(query: str, limit: int = 5) -> list[dict]:
    """Search the knowledge base and return matching documents."""
    ...

Works with any Python framework

agent() returns a standard ASGI callable — mount it anywhere:

# FastAPI
from fastapi import FastAPI
from pyeve import agent

app = FastAPI()
app.mount("/", agent("./agent"))

# Standalone with uvicorn
import uvicorn
from pyeve import agent

uvicorn.run(agent("./agent"), port=8000)

Provider adapters

Provider	Install	Adapter
Anthropic	pip install "pyeve[anthropic]"	AnthropicAdapter()
OpenAI	pip install "pyeve[openai]"	OpenAIAdapter()
Mistral	pip install "pyeve[mistral]"	MistralAdapter()
SAP AI Core	pip install "pyeve[sap]"	SAPAICoreAdapter()

Durable sessions

Sessions are persisted to disk automatically. Pick up a conversation by passing session_id:

curl -X POST http://localhost:8000/chat \
  -d '{"message": "Follow up question", "session_id": "user-123"}'

Retrieve history:

curl http://localhost:8000/sessions/user-123

Testing

pyeve ships a MockAdapter and test client for unit testing agents without real API calls:

from pyeve.adapters.mock import MockAdapter
from pyeve.testing import AgentTestClient

async def test_weather_agent():
    client = AgentTestClient(
        agent_dir="./agent",
        adapter=MockAdapter(responses=["The weather in Berlin is sunny and 72°F."]),
    )
    response = await client.chat("What is the weather in Berlin?")
    assert "Berlin" in response.text

License

Apache 2.0