Fred — AI Assistant

Fred is a minimal AI assistant built with FastAPI, PostgreSQL, and local Ollama. It can explore codebases, store preferences, and remember high-level concepts.

Requirements

• Python 3.11+
• PostgreSQL
• Ollama (local LLM inference)

Install

pip install -e .
# or with uv:
uv sync

Configuration

Copy .env.example to .env and set:

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql://localhost:5432/fred
OLLAMA_URL	Ollama API base URL	http://localhost:11434

Run

1. Ensure Ollama is running: ollama serve
2. Pull a model with tool support (e.g. Llama 3.1): ollama pull llama3.1
3. Start Fred:

uvicorn fred.main:app --reload

4. Open http://localhost:8000

API Overview

• GET / — Chat web UI
• GET /health — Health check
• POST /chat — Send message, get response (sync)
• POST /chat/stream — Stream response as NDJSON (recommended for code exploration)
• GET/POST/DELETE /memories — Long-term memory CRUD
• GET/PUT /preferences — User preferences (e.g. project_path, model)

Code exploration requires project_path to be set. Use PUT /preferences/project_path with {"value": "/path/to/your/project"} or ask Fred to set it in chat.

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
pytest tests/ -v

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/

More

See AGENTS.md for architecture, tools, and conventions (targeted at AI agents).