Research modes

None of the modes on this page are the deployed product. Causeloop in production, and its local parity environment, is the container stack documented in Local product stack (infra/docker-compose.product.yml, Next.js console on 13000, product API on 18000). The modes below run services/api/main.py — the legacy research application with roughly 258 endpoints — and the Vite-based workbench in apps/web. Reach for them only when the work is actually inside that legacy surface: the MVP1 strict-analysis pipeline, the relational clustering pipeline, or the workbench UI that renders them.

Why this surface still exists

services/api/main.py predates the tenant-scoped product API in services/api/product_app.py. It hosts the local research workbench, file-backed client onboarding, and the process-global /mvp1 routes that the current product does not need. The product boundary (services/api/product_app.py) explicitly does not import it — the module’s own docstring calls out that importing the legacy app “creates stores and exposes operations the customer/staff product does not need.” Treat everything on this page as a research and pipeline-development environment, not a place to prototype product features.

Choosing a mode

Pick the smallest mode that covers the work at hand:

Mode	What it runs	Docker	OpenAI key	Use it for
`basic`	FastAPI + React, built-in read-only MVP1 data	No	No	UI/API changes to the workbench that don’t need a fresh analysis run
`mvp1`	Basic mode plus a new strict 250-issue analysis	No	Yes	Exercising the strict fishbone/severity pipeline end to end
`relational`	PostgreSQL-backed analysis through a reviewed Excel workbook	Postgres	Yes	Work on the relational clustering pipeline, the workbook exporter, or Alembic migrations for that schema

All three assume Python 3.12+, uv, and Node.js 20+/npm 10+ are installed. From the repository root, install locked dependencies once:

uv sync --dev
npm ci --prefix apps/web
uv run python scripts/check_local_setup.py --mode basic

check_local_setup.py is local and non-mutating — it never calls OpenAI, never contacts a remote service, and never prints a secret value. Run it for the mode you’re about to use before claiming that mode is ready.

Mode 1: basic UI and API

No Docker, no API key. Start both processes together:

uv run python scripts/run_local.py

or in two terminals:

uv run uvicorn services.api.main:app --host 127.0.0.1 --port 8000 --reload
npm --prefix apps/web run dev -- --host 127.0.0.1

Open:

Web UI: http://127.0.0.1:5173
API docs: http://127.0.0.1:8000/docs
API schema: http://127.0.0.1:8000/openapi.json

The tracked synthetic banking dataset (docs/issue-set-2-records.json, 250 records) is available in this mode. A fresh clone has no generated strict latest report, so report endpoints correctly return 404 until an analysis is run — that is not a setup failure (see Troubleshooting).

scripts/run_local.py builds its child environment by loading .env then .env.local, but the real process environment takes precedence over both — a variable already set in your shell overrides whatever either dotenv file has. It then launches uvicorn on services.api.main:app and npm --prefix apps/web run dev as child processes. It requires npm to be on PATH.

Mode 2: strict MVP1 analysis

Create the local env file

cp .env.example .env.local

At the time of writing, .env.example is not present in a fresh clone of this repository, even though scripts/check_local_setup.py and this historical instruction both reference it. If the copy fails, create .env.local directly and set OPENAI_API_KEY= in it through a secret-aware local workflow — never paste the key into chat, logs, commits, or shell history. The doctor only checks that the variable is non-empty; it never prints the value.

Run the doctor for mvp1

uv run python scripts/check_local_setup.py --mode mvp1

Start the stack

uv run python scripts/run_local.py

Approve and run the strict analysis in the UI

In the web UI, choose the Operator or Developer role, enable the two separate OpenAI transfer approvals, and start the strict run.

Starting the strict run sends governed, de-identified issue fields to OpenAI and may incur API cost. A code agent must never perform that live action without the user’s explicit, informed approval — this is one of the safety boundaries in AGENTS.md. The strict pipeline persists its reusable analysis state locally; PostgreSQL is not required for mvp1 mode. The UI/API shape for this mode is specified in docs/MVP1_API_CONTRACT.md.

Mode 3: relational DB-to-Excel

This path clusters the same tracked docs/issue-set-2-records.json dataset through PostgreSQL and a reviewed Excel workbook. It does not depend on a workbook in ~/Downloads or any machine-specific path.

Prepare local configuration and start Postgres

cp .env.example .env.local
cp infra/causeloop.local.env.example infra/causeloop.local.env
docker compose -f infra/docker-compose.yml up -d postgres
set -a
source .env.local
source infra/causeloop.local.env
set +a
uv run alembic upgrade head

Both .env.local and infra/causeloop.local.env are git-ignored. Never read, print, log, or commit either file — that rule is explicit in AGENTS.md.

Point Node at the bundled @oai/artifact-tool package

The reviewed workbook builder (workers/artifacts/build_mvp1_clustering_workbook.mjs) imports @oai/artifact-tool. If you are a Codex agent, call the workspace-dependency discovery tool and export its bundled Node executable:

export CAUSELOOP_NODE_PATH=/absolute/path/from/workspace-dependency-discovery/node

scripts/check_local_setup.py resolves this as either the configured path or whatever node is on PATH, then looks for @oai/artifact-tool next to workers/artifacts/node_modules or next to that Node binary’s own node_modules. Do not point it at an arbitrary Node install that doesn’t carry the package — the check will fail with “Node runtime does not expose @oai/artifact-tool.”

Verify prerequisites without making an API call

uv run python scripts/check_local_setup.py --mode relational

Run the pipeline (only after explicit user approval of cost)

uv run python workers/run_banking_relational_e2e.py \
  --approve-openai-llm \
  --openai-authorization \
  "I explicitly authorize sending these 250 de-identified banking issue descriptions and derived severity context to the OpenAI API."

The runner enforces this exact authorization string in addition to the approval flag — it is not a formality.

Outputs are written under the ignored outputs/mvp1/ directory and must never be committed. Validated severity, embedding, and cluster-label results are content-addressed in PostgreSQL: an unchanged rerun reuses them and should make zero new OpenAI calls. The full database and workbook contract is in docs/MVP1_RELATIONAL_PIPELINE.md. To bring up every optional local infrastructure service instead of Postgres alone:

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

If a sandbox redirects user caches and uv commands fail to write to their default cache directory, prefix them with UV_CACHE_DIR=/tmp/uv-cache.

Welcome

Developer Onboarding

Why this surface still exists

Choosing a mode

Mode 1: basic UI and API

Mode 2: strict MVP1 analysis

Mode 3: relational DB-to-Excel

​Why this surface still exists

​Choosing a mode

​Mode 1: basic UI and API

​Mode 2: strict MVP1 analysis

​Mode 3: relational DB-to-Excel

​Related

Why this surface still exists

Choosing a mode

Mode 1: basic UI and API

Mode 2: strict MVP1 analysis

Mode 3: relational DB-to-Excel

Related