ai-circus

August 4, 2026 · View on GitHub

A building block for generative AI tool applications with state-of-the-art performance.

Contributor Covenant PyPI Package Supported Python Versions

🖥️ Prerequisites: Development Environment

Production is Linux, so development should be too — this repo targets Ubuntu 26.04 (minimal), whichever way you provision it:

  • If you don't already have it, install VS Code on your host machine first. For WSL, add the Remote - WSL extension ("WSL: Connect to WSL"); for a remote VM, add the Remote - SSH extension ("Remote-SSH: Connect to Host...").
  • macOS / native Linux: already Unix-based — skip ahead to Quick Start.
  • Windows: use WSL (install guide).
  • Remote VM (AWS/Azure/GCP/on-prem): provision an Ubuntu 26.04 base and connect over SSH.
  • VS Code Dev Container: open this folder in VS Code and let it build .devcontainer/Dockerfile.

Once you're on an Ubuntu 26.04 machine or session (WSL, native Linux, or remote VM — not needed for Dev Containers, which run this automatically), provision it with this repo's setup scripts:

sudo ./.devcontainer/setup_sudo.sh   # one-time root setup: packages, timezone, optional GPU/CUDA
source .devcontainer/setup_user.sh   # per-user setup: git config, uv, Node via nvm, shell prompt (must be sourced)

Then install Docker — Docker Install Guide (Ubuntu).

Both scripts are idempotent (safe to re-run). See reference/01-fundamentals.md for the full rationale and options.

🚀 Quick Start

Once your environment is ready, get the project up and running in seconds after cloning the repository:

make setup    # Initialize venv, .env, generate settings, and verify environment
make check    # Run QA checks (linting) and tests
make run      # Run the main hello world application

To verify everything end-to-end before a commit:

make all      # clean -> setup -> check -> run

Work in Progress

This project is under active development. Features and APIs are subject to change.

Implemented:

  • Centralized Pydantic configuration (settings.yaml)
  • Validated environment setup (make setup)
  • Simplified LLM/Embedding initialization (ai_circus.get_llm)

Planned:

  • OpenSearch integration for vector storage
  • Agent framework integration (LangChain, OpenAI SDK, etc.)
  • MCP (Model Context Protocol) support and examples

Tools and Frameworks

Python uv Ruff Pytest Pre-commit

Configuration

The project uses a single source of truth for settings defined in settings.yaml.

  1. Run make setup to initialize your .env file from .env.example.
  2. Edit .env to fill in your OPENAI_API_KEY and other optional keys.
  3. The application will automatically validate these at runtime using Pydantic.

Common Workflows

CommandDescription
make cleanRemove .venv, caches, and artifacts (with .env backup)
make setupFull environment initialization and verification
make checkRun qa (linting) and test (unit tests)
make runExecute the main application
make qaRun pre-commit hooks (ruff, etc.)
make testRun the pytest suite
make allFull end-to-end verification pipeline
make updateUpgrade lockfile, sync deps, update pre-commit hooks

AI Tools

CommandDescription
make ai-hello-worldBasic demo: log system info and greet using your configured LLM provider (no LLM call)
make ai-check-api-keysValidate that configured API keys actually work
make ai-commitGenerate a commit message from staged changes
make ai-sample-assistantRun the sample single-turn assistant
make ai-sample-agenticRun the sample tool-using agentic assistant
make ai-appRun the main application (alias for make run)

Each target is a thin wrapper around a uv run console script — they're declared under [project.scripts] in pyproject.toml and can be run directly without make, e.g. uv run ai-hello-world.

📚 Learn More

For the reasoning behind this stack and structure — dev environment, tooling, software engineering practices, ML, and GenAI — see the reference notes starting at reference/00-itinerary.md.

Contributing