# razberri

Private hackathon repository for **razberri**, a privacy-first, local-first **second-brain
assistant**.

You capture the loose threads you are afraid you'll lose track of — reminders, follow-ups,
deadlines, errands, ideas, and "don't let me forget this" family contactents. razberri then uses a local MCP
agent layer plus Work IQ-style context (calendar, mail, and message signals) to decide what matters
now, resurface it proactively, and turn each thread into one tiny next step.

Two design lenses sit underneath that one product:

- **Neurodivergent-aware / ADHD executive-function support** — non-judgmental, small-next-action
  oriented, "stuck is information, not failure."
- **Microsoft Work IQ alignment** — Outlook, Calendar, and Messages are the first context surfaces,
  but the executive-function engine is local and service-agnostic.

Core loop:

```text
Capture → Context → Prioritize → Surface → Resolve
```

> 📖 **Full reference:** see [DOCUMENTATION.md](DOCUMENTATION.md) for the consolidated guide
> (architecture, MCP tools, web API, CLI, configuration, and roadmap).

## What's in the box

razberri runs locally and offline by default. Everything below is on-device; nothing leaves your
machine unless you explicitly enable the live Microsoft Graph path.

| Surface | Where | Role |
| --- | --- | --- |
| **MCP server** | `mcp_server/main.py` | FastMCP server exposing 15 ADHD/second-brain tools |
| **Web app + JSON API** | `mcp_server/web.py` | FastAPI app; single-page UI + JSON API |
| **CLI demo** | `demo.py` | Judge-friendly commands (brief, breakdown, best-time, calendar import, portal) |
| **Local memory** | `mcp_server/thread_store.py`, `mcp_server/nexus_client.py` | SQLite-backed threads + "Nexus" event history |
| **Dev portal** | `mcp_server/devportal.py` | Local admin console to configure the optional integrations |

### Optional, opt-in capabilities (graceful fallback when absent)

- **LLM-assisted breakdown & mission text** (`mcp_server/llm_client.py`) — local **Ollama** is the
  default provider; **Azure OpenAI** is also supported. If the model is unreachable, razberri falls
  back to a deterministic heuristic and never crashes.
- **ML best-time recommender** (`mcp_server/timing_model.py`, `mcp_server/timing_engine.py`) — a
  scikit-learn model learns your follow-through hours from local history. Until trained, a
  statistical profile is used.
- **Offline calendar import** (`mcp_server/calendar_import.py`) — import a real `.ics` so the demo
  runs on your actual schedule without any live account.
- **Live Microsoft Graph calendar** (`mcp_server/graph_transport.py`) — implemented and opt-in via
  MSAL device-code. **Mock mode is the default**, and the live path is untested in this build; it
  degrades to mock fixtures on any auth/transport failure.

See [WINDOWS_SETUP.md](WINDOWS_SETUP.md) for turning each optional capability on.

## Repository layout

```text
mcp_server/        MCP server, FastAPI web app + API, tools, adapters, local memory
mock_data/         Graph-shaped mock fixtures (Outlook, Calendar, Messages, Planner, To Do, OneNote)
demo.py            CLI demo entry point
tests/             pytest suite (hermetic; ignores your local .env)
docs/              Supporting docs, archive, and planning notes (SPEC, PLAN, PRODUCT_STRATEGY, UI_REFRESH)
ARCHITECTURE.md    Adapter pattern + data flow
WINDOWS_SETUP.md   Turning on Ollama / ML best-time / live Graph
DEMO.md            2–3 minute demo script
```

## Thread persistence

Captured threads are written to a local SQLite database so the running demo retains threads,
importance fields, done/snoozed status, and the selected current thread across restarts. The public
entry point is `mcp_server/storage.py`, which re-exports the underlying repository and adds two
startup helpers:

- `init_storage(path=None)` builds the repository (or a disabled one when persistence is off).
- `storage_status(repository=None)` returns a JSON-serializable snapshot for `/api/agent/status`.

The FastAPI app wires both through a `lifespan` context manager so storage init runs once at boot.

- Default path: `./data/threads.db` (relative to the working directory).
- Override with `RAZBERRI_THREAD_DB_PATH`.
- Set it to `memory` (or `off` / `false` / empty) to disable persistence (in-memory only).
- `data/*.db` and `data/*.sqlite` are gitignored — the database is a local runtime artifact.

Tests always run with an ephemeral temp-file database configured by `tests/conftest.py`, so they
never touch real user data.

## Run the prototype

On the Windows demo machine the validated path is system Python 3.13 with no venv —
`python -m pip install -r requirements.txt` once, then run directly. On other machines, activate a
venv first if you use one.

### Start everything with one command

```bash
python run.py                 # starts the web app and opens the browser
python run.py --portal        # start the dev portal as the control center on :8765
python run.py --install       # pip install -r requirements.txt first, then start
```

`run.py` launches the FastAPI web app (UI + API) as a managed child process and stops it cleanly on
Ctrl+C. Run `python run.py --help` for all flags (`--host`, `--port`, `--reload`, `--no-browser`).

With `--portal`, the **dev portal becomes the control center**: it opens on :8765, owns the web UI
lifecycle (Start / Stop / Restart from the browser), and shows a live overview of every subsystem —
web UI, LLM provider, the Ollama models detected on your machine, Azure, Microsoft sign-on, and the
calendar source. The web UI then carries a "dev portal ↗" link back to it.

The MCP stdio server for MCP clients is separate: `python mcp_server/main.py`.

### Or start the web app directly

```bash
pip install -r requirements.txt
uvicorn mcp_server.web:app --host 0.0.0.0 --port 8000
```

Override the database path for the demo:

```bash
RAZBERRI_THREAD_DB_PATH=./demo_data/threads.db uvicorn mcp_server.web:app --host 0.0.0.0 --port 8000
```

Open:

```text
http://127.0.0.1:8000
```

LAN URL for testing from another device on your network (Wi-Fi IP as of 2026-06-12 —
re-check with `ipconfig` if it changes):

```text
http://192.168.1.188:8000
```

## Development tooling

This project was built in Visual Studio Code with GitHub Copilot assistance. See [`docs/COPILOT_AND_VSCODE.md`](docs/COPILOT_AND_VSCODE.md) for the submission note describing how VS Code and Copilot supported implementation, testing, and documentation.

## Validate

```bash
pytest -q
```

Expected: **102 passed**. The suite is hermetic — it pins an opt-in-OFF baseline and ignores your
local `.env`, so results do not depend on whether you have Ollama, Azure, or Graph configured.