> ## Documentation Index
> Fetch the complete documentation index at: https://docs.causeloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prerequisites

> Toolchain, install commands, and the local setup doctor you need before touching either Causeloop repository.

Causeloop is two sibling repositories that must be checked out next to each other: the FastAPI/Python backend (`/Users/rushabhpatel/Desktop/causeloop.ai/backend`, this repo) and the Next.js/TypeScript frontend (`/Users/rushabhpatel/Desktop/causeloop.ai/frontend`). The product Compose stack builds the frontend's `Dockerfile` by relative path (`../../frontend` from `infra/docker-compose.product.yml`), so the two checkouts must share a parent directory before any product-mode command will succeed.

This page covers what to install and how to verify the install. For what to actually run day to day, see [Local product stack](/onboarding/local-product-stack).

## Toolchain

| Tool                                                            | Minimum version    | What it's for                                                                                                                                                                                                            |
| --------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Python                                                          | 3.12               | Runs the FastAPI API, Alembic migrations, workers, and the pytest suite. Pinned in `pyproject.toml` (`requires-python = ">=3.12"`) and enforced by the setup doctor.                                                     |
| [`uv`](https://docs.astral.sh/uv/getting-started/installation/) | any recent release | Resolves and installs the locked Python dependency graph (`uv.lock`) for the workspace, including the in-repo `packages/causegraph` package. Replaces `pip`/`venv` for everything in this repo.                          |
| Node.js                                                         | 20                 | Runs both frontend UIs: the production Next.js console (`../frontend`) and the legacy Vite research workbench (`apps/web`). Enforced by `scripts/check_local_setup.py` and by `apps/web/package.json`'s `engines` field. |
| npm                                                             | 10                 | Package manager for both frontend UIs. Same enforcement path as Node.                                                                                                                                                    |
| Docker with Compose v2                                          | any recent release | Runs the product stack (`infra/docker-compose.product.yml`) and the optional research infrastructure stack (`infra/docker-compose.yml`). Required for `product` and `relational` modes; not required for `basic`/`mvp1`. |

<Note>
  The frontend repo's own `package.json` does not pin an `engines` field. Treat it as subject to the same Node 20+ / npm 10+ baseline the doctor enforces on the backend side — the two frontends (the product console and the research workbench) are built and tested together and there is no supported reason to run them on different toolchains.
</Note>

## Install commands

From the backend repository root:

```bash theme={null}
uv sync --dev
npm ci --prefix apps/web
```

* `uv sync --dev` installs the locked runtime and dev dependency groups (`pytest`, `pytest-asyncio`, `ruff`) from `uv.lock`, including the workspace-local `causegraph` package (`[tool.uv.workspace] members = ["packages/causegraph"]`). It's required for the `basic`/`mvp1`/`relational` research modes and for running backend checks on the host (`uv run ruff check .`, `uv run pytest`). Product mode's own tooling doesn't need it: `scripts/check_local_setup.py` and `scripts/smoke_product.py` import only the Python standard library and run with a bare `python3` — no venv or `uv` install required, per `AGENTS.md`.
* `npm ci --prefix apps/web` installs the **legacy research workbench**'s pinned dependencies (`apps/web/package-lock.json`) — the Vite/React 18 SPA behind `basic`/`mvp1`/`relational` modes. It is not required for `product` mode, which never starts `apps/web`.

From the sibling frontend repository root (`../frontend` relative to this repo):

```bash theme={null}
npm ci
```

This installs the production Next.js 15 / React 19 console's locked dependencies (`package-lock.json`). It's required to run the frontend outside its container (`npm run dev`) and to run its own checks (`npm run typecheck`, `npm test`, `npm run build`, `npm run e2e`). It is **not** required to run the containerized product stack end to end — the frontend's own `Dockerfile` installs dependencies inside the image from the same lockfile.

<Tip>
  The backend's `Makefile` wraps the first two commands into one target, `make setup` (`command -v uv >/dev/null || brew install uv`, then `uv sync --dev`, then `cd apps/web && npm install`). It doesn't touch the sibling frontend checkout — you still run `npm ci` there yourself. `AGENTS.md` is explicit that no Make command is required or expected for product-mode work; treat `make setup` as a macOS convenience for engineers working in the legacy research modes, not as the canonical path.
</Tip>

<Warning>
  Product mode needs no host-side Node/npm install at all if you only intend to run the containers: `docker compose -f infra/docker-compose.product.yml up -d --build` builds both the backend and frontend images from their respective `Dockerfile`s using the committed lockfiles. Install Node locally only when you need frontend hot reload or want to run its checks directly on the host.
</Warning>

## The setup doctor

`scripts/check_local_setup.py` is a local, non-mutating verifier: it never calls OpenAI, never contacts a remote service, and never prints a secret value — only whether one is configured. Run it before claiming any mode is ready to use, and re-run it as the first troubleshooting step whenever something doesn't come up.

```bash theme={null}
python3 scripts/check_local_setup.py --mode product
```

or, for the historical research modes:

```bash theme={null}
uv run python scripts/check_local_setup.py --mode <basic|mvp1|relational>
```

Add `--json` to either form for machine-readable, secret-safe output for tooling and code agents that need to parse results.

<AccordionGroup>
  <Accordion title="--mode product">
    Checks: Python 3.12+, Docker Compose v2 (`docker compose version`), a reachable Docker daemon (`docker info`), and that the sibling source layout is intact — the backend's `Dockerfile`, `infra/docker-compose.product.yml`, and `services/api/product_app.py`, plus the sibling frontend's `Dockerfile`, `package.json`, and `package-lock.json`. If those all pass, it additionally renders `docker compose -f infra/docker-compose.product.yml config` and asserts the product worker advertises its full job-type contract (`materialize_insights,send_email,train_tenant_model`) and that the local Mailpit/S3-compatible provider parity markers are present. This is the mode documented in [Local product stack](/onboarding/local-product-stack).
  </Accordion>

  <Accordion title="--mode basic">
    Checks: Python 3.12+, `uv`, Node 20+, npm 10+, the `.venv` created by `uv sync --dev`, `apps/web/node_modules` created by `npm ci --prefix apps/web`, and the integrity of the tracked synthetic banking dataset (`docs/issue-set-2-records.json` — exactly 250 records, unique IDs, all governed fields populated). No Docker, no OpenAI key.
  </Accordion>

  <Accordion title="--mode mvp1">
    Everything `basic` checks, plus that an `OPENAI_API_KEY` is configured (value never printed) — required because this mode sends de-identified issue fields to OpenAI for a strict analysis run.
  </Accordion>

  <Accordion title="--mode relational">
    Everything `mvp1` checks, plus Docker Compose v2, the presence of `infra/causeloop.local.env`, a live socket check against the configured Postgres DSN, an `alembic current` check that the database is at head, and that a Node runtime exposes the `@oai/artifact-tool` package (via `CAUSELOOP_NODE_PATH` or a bundled `workers/artifacts/node_modules` install) used by the reviewed-workbook exporter.
  </Accordion>
</AccordionGroup>

The doctor's exit code is `1` if any check fails; each failing check prints its own fix instruction. Always act on the *first* failing check rather than the whole list — later checks frequently depend on earlier ones (for example, the relational migration check is skipped entirely if the Postgres socket check already failed).

## Choosing a mode

<Note>
  `product` is the only mode that reflects the deployed system. The `basic`/`mvp1`/`relational` modes described here and in [Research modes](/onboarding/research-modes) support the older embedded research workbench and are not part of the production boundary — see [Backend repo tour](/onboarding/backend-repo-tour) for how the repo separates the two.
</Note>

Pick the smallest mode that covers the work in front of you:

```mermaid theme={null}
flowchart TD
    A[What are you working on?] -->|Product API, tenant console, workers| B[product]
    A -->|Legacy Vite workbench UI/API, no external calls| C[basic]
    A -->|Legacy 250-issue strict OpenAI analysis| D[mvp1]
    A -->|Legacy PostgreSQL-backed relational pipeline| E[relational]
```

## Related

* [Backend repo tour](/onboarding/backend-repo-tour)
* [Frontend repo tour](/onboarding/frontend-repo-tour)
* [Local product stack](/onboarding/local-product-stack)
* [Research modes](/onboarding/research-modes)