SempAI

A Python AI agent system for collaborative coding. The goal is to have a pair programming companion. The agent will be the "driver" and the human will be the "navigator". The agent is able to:

• Read code, understand it, and generate code.
• Work with the user to create new features, fix bugs, and refactor code.
• Track progress, decisions, bugs and work accross long running, multi-step projects.

Task Management

A todo list is used by the agent and human(s) to track work items (tasks, bugs, feature request, etc.) and progress. The todo list is stored in a file (default: todo_list.json) and is shared between the agent and human. See the system prompt in the agent_coder folder for how we expect the agent to use the todo list. The format of the todo is a simple json list containing:

• id: unique identifier for the task
• task: a short description/name for the task
• detail: a long description with details similar to a user story or defect story.
• notes: List of notes about the task. This is where the agent and human can add their thinking, decisions, and progress.
• done: boolean indicating if the task is complete.

Context Management

To maintain a practical sized context, and keep the agent focussed on the current task, a summariser agent will be used periodically. See .env file. The summariser keeps the first couple, and last 20 messages in the context. The concept is that we always want the system and user prompts plus the latest generated context - code, thinking, and tool results but the middle can be summarised. This combined with the todo list will keep the context manageable.

The summariser will be invoked when the context exceeds the SUMMARISER_TRIGGER length in the .env file (default 75k). See the system prompt in the agent_util folder for how the agent is expected to summarise.

Technology

The agent is built using Pydantic AI's Direct API. Tested with ollama but using the OpenAI interface so it supports any OpenAI-compatible API. Other libraries used include DDGS | Dux Distributed Global Search for web search in the research tool.

🛠 Built-in Tools

Tool	Description
research	Web search and scrape
read	Read files with optional line limits
write	Create files with audit logging
edit	String replacements in files
multiedit	Multiple edits atomically
ls	List directory contents
glob	Pattern-based file search
grep	Regex search in file contents
bash	Execute shell commands
todo	Task management

🚀 Quick Start

Prerequisites

• Python 3.13+
• Ollama with a model that supports tool calls (E.g. qwen3-coder) or OpenAI key
• uv (optional)

Installation

git clone https://github.com/Semprini/sempai.git
cd sempai
cp .env.example .env

# Simplest way is using uv to create a venv, install deps and run:
uv run main.py

# Or pip:
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python main.py

Check out the .env file for selecting your providers and model

Thanks to the below learning project:

• https://moustaphacheikh.com/blog/understanding-codantic-ai-agent-flow