Gregory is an AI-powered glue layer that connects various interfaces and automations. His main interface is an HTTP API for chatting, with planned integrations for Home Assistant, Jellyfin, and multiple AI backends.

flowchart TB
    subgraph clients [Clients]
        WebApp[Web / Mobile App]
        VoiceInterface[Voice Interface]
        DebugUI[Debug Chat UI]
    end

    subgraph gregory [Gregory]
        API[HTTP API]
        Notes[Notes]
        Router[AI Router]
    end

    subgraph ai [AI Backends]
        Ollama[Ollama]
        Claude[Claude]
        Gemini[Gemini]
    end

    subgraph future [Planned]
        HA[Home Assistant]
        Jellyfin[Jellyfin]
    end

    clients --> API
    API --> Notes
    API --> Router
    Router --> Ollama
    Router --> Claude
    Router --> Gemini

• HTTP API — Chat with Gregory via REST; future apps can use this for voice, web, and more
• User-scoped chat — Each family member has a dedicated conversation and notes
• Notes — Gregory maintains Markdown notes per user and for the household
• AI backends — Ollama (on-prem), Claude (Anthropic), Gemini (Google) with model routing and fallback
• Docker deployment — Run on home server, Raspberry Pi, or anywhere

1. Copy .env.example to .env and configure:

   cp .env.example .env
   # Edit OLLAMA_BASE_URL, FAMILY_MEMBERS, etc.

2. Run with Docker Compose:

   docker compose -f docker/docker-compose.yml up -d

3. Gregory will be available at http://localhost:8000:

   • API docs: http://localhost:8000/docs
   • Health: http://localhost:8000/health

1. Create a virtual environment and install:

   python -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   pip install -e ".[dev]"

2. Set environment variables (or use .env):

   export OLLAMA_BASE_URL=http://localhost:11434
   export NOTES_PATH=./notes
   export FAMILY_MEMBERS=alice,bob,kids

3. Run:

   uvicorn gregory.main:app --reload --host 0.0.0.0 --port 8000

curl -X POST "http://localhost:8000/users/alice/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello Gregory!"}'

Response:

{
  "response": "Hello Alice! How can I help you today?",
  "conversation_id": "conv_1"
}

Interactive API documentation: http://localhost:8000/docs

A minimal static HTML interface for testing the chat API is in debug/chat.html. Serve it via HTTP to avoid CORS:

cd debug && python -m http.server 8080

Open http://localhost:8080/chat.html, set the API base URL and user ID, then send messages. See docs/DEVELOPMENT.md for details.

Notes are stored in the notes/ directory (or NOTES_PATH). In Docker, the notes volume is mounted.

flowchart LR
    subgraph notes_dir [notes/]
        household[household.md]
        alice[alice.md]
        bob[bob.md]
    end

    subgraph usage [Usage]
        context[Chat Context]
    end

    household --> context
    alice --> context
    bob --> context

• household.md — General household notes (shared context)
• gregory.md — Gregory's self-notes (his experiences, thoughts, preferences)
• entities/*.md — Notes about other things (pets, projects, etc.)
• {user_id}.md — Per-user notes (e.g. alice.md, bob.md)

Gregory reads these before each chat and can append observations as he learns. See notes/README.md for details. Use a bind mount to access notes from the host:

volumes:
  - ./notes:/app/notes

Local (non-Docker): Copy config.json.example to config.json and edit. Use .env for API keys.

Docker: Use .env or environment variables in docker-compose.yml.

See docs/CONFIGURATION.md for details.

For ARM64 builds:

docker buildx build --platform linux/arm64 -t gregory:latest -f docker/Dockerfile .

Or build on the Pi directly (may be slow). See docs/DEPLOYMENT.md for details.