diff --git a/.env.example b/.env.example index 3797cd4..f894d1b 100644 --- a/.env.example +++ b/.env.example @@ -48,6 +48,9 @@ EMBEDDING_DIM=1024 # EMBEDDING_ENDPOINT=http://host.docker.internal:8002 # EMBEDDING_BATCH_SIZE=1 # EMBEDDING_MAX_SEQ_LENGTH=1024 # caps Jina token window to avoid OOM (0 = disable) +# EMBEDDING_MAX_RETRIES=12 # sized for a cold CPU sidecar, not for an API +# EMBEDDING_TIMEOUT_SECONDS=300 # ditto — their product is the worst-case stall, +# # and the worker consumes one job at a time # On MacBook: run `make embedding-host` in a separate terminal (recommended). # Or Docker sidecar: docker compose --profile embedding up -d embedding # If you change EMBEDDING_DIM after first migrate: make down-all && make migrate diff --git a/.env.production.example b/.env.production.example index f443cc2..c106a70 100644 --- a/.env.production.example +++ b/.env.production.example @@ -1,8 +1,15 @@ # ============================================================ # Dcode production environment variables. -# Copy to `.env.production` on the deployment host and review -# every placeholder before `docker compose -f docker-compose.yml -# -f docker-compose.prod.yml up -d --build`. +# +# Copy to `.env.production` on the deployment host and review every +# placeholder before: +# +# docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build +# +# `docker-compose.prod.yml` is a COMPLETE stack, not an overlay. Do not +# combine it with `-f docker-compose.yml`: the developer file publishes +# Postgres, Redis and the RabbitMQ management UI to the host, and overlaying +# would republish them on a public machine. # ============================================================ # --- Public entrypoint --- @@ -13,26 +20,82 @@ PUBLIC_ORIGIN=http://dcode.odieyang.com POSTGRES_USER=dcode POSTGRES_PASSWORD=__SET_PROD_POSTGRES_PASSWORD__ POSTGRES_DB=dcode -DATABASE_URL=postgresql+asyncpg://dcode:__SET_PROD_POSTGRES_PASSWORD__@postgres:5432/dcode # --- Internal services --- -REDIS_URL=redis://redis:6379/0 RABBITMQ_USER=__SET_PROD_RABBITMQ_USER__ RABBITMQ_PASSWORD=__SET_PROD_RABBITMQ_PASSWORD__ + +# The compose file builds DATABASE_URL / REDIS_URL / RABBITMQ_URL / AGENT_URL +# from the values above and the internal service names, so these four are NOT +# read by the running stack. They are here for commands run against this env +# file outside compose (an alembic invocation on the host, for example). If you +# change a credential above, change it here too or leave these out entirely. +DATABASE_URL=postgresql+asyncpg://dcode:__SET_PROD_POSTGRES_PASSWORD__@postgres:5432/dcode +REDIS_URL=redis://redis:6379/0 RABBITMQ_URL=amqp://__SET_PROD_RABBITMQ_USER__:__SET_PROD_RABBITMQ_PASSWORD__@rabbitmq:5672/ AGENT_URL=http://agent:8001 # --- Internal service auth --- +# Protects every /internal/* retrieval and graph route. The code default is a +# placeholder published in this repository, so this must be set to a real +# secret — the compose file refuses to start without it. INTERNAL_API_KEY=__SET_PROD_INTERNAL_API_KEY__ -# --- Model / runtime knobs --- -# Production defaults keep model serving disabled. If production should use -# real embedding/reranker services, add those services to the deployment and -# set endpoint, model, and EMBEDDING_DIM consistently before indexing. LOG_LEVEL=info + +# ============================================================ +# Retrieval models +# +# These are read by api, worker AND agent, and they must AGREE. The API embeds +# the search query, the worker embeds the corpus, and the agent reranks its own +# evidence union. Configuring one service and not another produces no error — +# it produces real vectors in the database being searched with a stub all-zero +# query vector, i.e. dense retrieval silently returning noise. +# ============================================================ + +# EMBEDDING_DIM is fixed into the pgvector column by the migration and cannot +# be changed afterwards without a new volume. It has no default in production +# for that reason: a wrong value here is not a slow query, it is a re-index. +# stub = 1024 zero vectors; jinaai/jina-embeddings-v2-base-code = 768. EMBEDDING_MODEL=stub EMBEDDING_DIM=1024 EMBEDDING_ENDPOINT= + +# Sized for a cold self-hosted sidecar. 12 retries against a 300s timeout can +# hold one batch of four chunks for about an hour, and the worker consumes one +# job at a time, so everything queued behind it waits. Lower both substantially +# when the endpoint is a hosted API rather than a model loading on CPU. +# EMBEDDING_BATCH_SIZE=4 +# EMBEDDING_MAX_RETRIES=12 +# EMBEDDING_TIMEOUT_SECONDS=300 + +# Leave RERANKER_ENDPOINT empty unless RERANKER_MODEL is a real model. A +# non-stub model with an empty endpoint fails fast and loudly, which is the +# intended behaviour; a stub model ignores the endpoint entirely. RERANKER_MODEL=stub -RERANKER_ENDPOINT=http://localhost:9999 +RERANKER_ENDPOINT= +# RERANKER_CANDIDATE_LIMIT=16 +# RERANKER_MAX_RETRIES=3 + +# Hybrid RRF fusion weights. Dense above sparse reduces keyword noise. +# RRF_DENSE_WEIGHT=2.0 +# RRF_SPARSE_WEIGHT=1.0 + +# ============================================================ +# Answer synthesis +# ============================================================ + +# 'stub' keeps rule-based template answers. Set an OpenAI-compatible model and +# key for prose answers; citations are verified against the index either way. +SYNTHESIS_MODEL=stub +OPENAI_API_KEY= +OPENAI_BASE_URL= +# SYNTHESIS_MAX_TOKENS=700 +# SYNTHESIS_TEMPERATURE=0.1 + +# Keep above 0 in production so the groundedness guardrail stays enforced. +# GROUNDEDNESS_THRESHOLD=0.95 + +# Defined and passed through, but read by no code today. Left in place rather +# than removed, because removing dead configuration is a product decision. JUDGE_MODEL=stub diff --git a/CLAUDE.md b/CLAUDE.md index 6ab0c39..f37f45a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,11 +7,12 @@ rules, and how to not break things. **Read this, then `git log --oneline`.** The work is committed in small scoped slices and the messages carry the reasoning. -Project documentation is five files, all authoritative over this one: +Project documentation is six files, all authoritative over this one: | Document | Read it for | |---|---| | [`docs/en/Final_Report.md`](docs/en/Final_Report.md) | The H1 verdict, **the single outstanding-work list**, known limits, what was verified | +| [`Deploy.md`](Deploy.md) | **Everything about taking this online.** Decisions, verified platform constraints, the invariants, the PR breakdown, the findings register — see §2 below | | [`docs/en/Honesty_Constraints.md`](docs/en/Honesty_Constraints.md) | The eleven rules governing what the UI may assert, with reasoning. Most are pinned by tests — read before touching the thread, the chips, or the inspector | | [`docs/en/Technical_Design.md`](docs/en/Technical_Design.md) | Repository layout, architecture, data model, API contracts | | [`docs/en/Operations.md`](docs/en/Operations.md) | Running the stack, the real-model path, the eval harness, operational gotchas | @@ -56,7 +57,54 @@ its numbers are generated rather than translated. flows, and write drafts to files rather than printing them inline. Pure frontend work runs clean. -## 2. Where things are +## 2. Deployment work is governed by `Deploy.md` — follow it strictly + +If the task touches deployment, hosting, model providers, auth, or production +configuration, **read [`Deploy.md`](Deploy.md) first and execute against it.** It +carries the decisions, the verified Railway constraints, the five-PR breakdown +with binding acceptance criteria, and a findings register where every row has a +`file:line`. Do not re-derive that plan, and do not improvise around it. + +**The backlog is not copied here.** `Deploy.md` §6 and §7 are the single list; +duplicating them into this file is the exact drift pattern this project keeps +having to fix. What is repeated below is only the set of invariants — the things +that stay true no matter which PR is in flight. + +1. **The deployed models must be the evaluated models.** + `jinaai/jina-embeddings-v2-base-code` at 768 dimensions, `BAAI/bge-reranker-v2-m3`, + `gpt-4o-mini`. Every figure the UI and the docs display is generated from + `results/eval-h1-repeat3-2026-07-31/` and is a claim about *that* configuration. + Substituting a model without saying so on the landing page and `/methodology` + is the same class of error as hand-typing a figure into prose. `Deploy.md` §2. +2. **The local multi-container path must not regress.** All four modes keep + working: stub, Docker sidecars, host sidecars, and the new API-provider mode. + `apps/embedding/`, `apps/reranker/`, the Compose profiles, the host scripts, + `HttpEmbeddingClient` and `HttpRerankerClient` are untouched. In particular the + agent+worker merge is a **Railway-only entrypoint** — Railway cannot share a + volume between services and local Docker can, so `docker-compose.yml` keeps two + separate containers. Do not degrade the local path to match the constrained + one. `Deploy.md` §5.1. +3. **The provider switch is additive.** `EMBEDDING_PROVIDER` / `RERANKER_PROVIDER` + default to `sidecar`; existing `.env` files and tests keep their behaviour with + no edit. `Deploy.md` §5.2. +4. **CI stays keyless.** New client tests mock the transport; they never call a + live API. `Deploy.md` §5.3. +5. **Embedding configuration must match on the API and the worker.** Setting it on + one only produces no error — it produces real vectors in the database searched + with a stub all-zero query vector, i.e. dense retrieval silently returning + noise. `Deploy.md` §5.4. +6. **No fork, no long-lived divergent branch.** `Deploy` merges to `main` as small + PRs, each independently green under `make check`. Secrets never enter the + repository. `Deploy.md` §5.5. +7. **`docker-compose.prod.yml` is fixed, not deleted.** `Final_Report.md` lists it + as delivered. `Deploy.md` §5.6. + +The pre-deployment state is frozen at tag `v1.0-submission` (`a4612b8`). Two +Railway constraints are load-bearing and were verified on 2026-08-02: a volume +attaches to exactly one service, and an HTTP request is cut after 5 minutes with +no data (~15 minutes with heartbeats). + +## 3. Where things are ``` apps/frontend/ React 18 + TS strict + Vite + Tailwind + Router v6 + TanStack Query (~4.2k TS/TSX lines) @@ -101,7 +149,7 @@ which matches `dcode_shared.events.sse_encode` emitting pure LF. Two data-fetching paradigms coexist deliberately: TanStack Query for status polling, hand-rolled streaming for the query. That is not an inconsistency. -## 3. Visual identity — deliberate, do not "improve" +## 4. Visual identity — deliberate, do not "improve" Tokens are a CSS-vars layer in `apps/frontend/src/index.css`, with `tailwind.config.ts` pointing at the vars so `color-mix` translucency still works. @@ -134,7 +182,7 @@ let it fill the `1fr` column: serif prose at 100+ characters per line is unreadable, and on a wide monitor a full-bleed column reads as an empty void. The rails (262px left, 384px right) are correct as-is. -## 4. Current state +## 5. Current state Everything below is committed and green: `make check`, `make frontend-build`, 71 frontend tests, full pytest suite. @@ -199,7 +247,7 @@ duplicate `psf/requests` rows already in the local DB are not cleaned up retroactively by the `POST /repos` idempotency fix, and `make down-all` wipes the volumes, which means re-indexing at whatever `EMBEDDING_DIM` you migrate at. -## 5. Environment +## 6. Environment ```bash # All three are required — .env points the model endpoints at host.docker.internal, @@ -242,7 +290,7 @@ vectors — real, varied embeddings, not stubs. Inspector line numbers and call-graph neighbours were manually verified against this index and matched exactly. -## 6. Working agreements that produced good results +## 7. Working agreements that produced good results - **Where this file and the code disagree, the code is the truth.** These notes are written from the approved intent of a session, and intent occasionally diff --git a/Deploy.md b/Deploy.md new file mode 100644 index 0000000..f7bb037 --- /dev/null +++ b/Deploy.md @@ -0,0 +1,533 @@ +# Dcode Deployment Plan + +## Document Scope + +This document is the authority for taking Dcode online. It records the decisions +that were taken, the platform constraints that were verified, the invariants this +workstream may not break, and the work broken into reviewable slices. + +It is deliberately **not** a second copy of the project backlog. +[`docs/en/Final_Report.md` § Outstanding Work](docs/en/Final_Report.md#outstanding-work) +remains the single list of what is unfinished in the *product*; this file covers +only what is unfinished in *getting it deployed*. When a deployment item is also +a product defect — most of them are — it is fixed here and struck from the +Outstanding Work list in the same PR, not tracked in two places. + +| Read instead | For | +|---|---| +| [`docs/en/Final_Report.md`](docs/en/Final_Report.md) | The H1 verdict and the product backlog | +| [`docs/en/Technical_Design.md`](docs/en/Technical_Design.md) | Architecture, data model, API contracts | +| [`docs/en/Operations.md`](docs/en/Operations.md) | Running the stack locally, the real-model path, the eval harness | +| [`docs/en/Honesty_Constraints.md`](docs/en/Honesty_Constraints.md) | What the UI may assert | +| [`CLAUDE.md`](CLAUDE.md) | Session-level operational notes; §2 there points back here | + +**Where this document and the code disagree, the code is the truth.** This file +is written from an approved plan, and plans outrun implementations. Verify before +relying on a claim here, and correct it when it is wrong. + +**Status: PR 1 of 5 landed; PR 2–5 not started.** The pre-deployment state is +frozen at tag `v1.0-submission` (`a4612b8`). Nothing is deployed anywhere yet, +and no live model API has been called from this codebase. + +--- + +## 1. Decisions Taken + +Recorded so a later reader can see what was chosen and what it ruled out. + +| # | Decision | Date | Consequence | +|---|---|---|---| +| D-1 | **Run real models, served by third-party APIs**, not self-hosted sidecars | 2026-08-02 | No GPU/RAM budget for model serving; adds API keys, network dependency, and per-query cost. Makes § 2 possible. | +| D-2 | **Not publicly accessible.** A username/password gate sits between the landing page and the workbench | 2026-08-02 | Removes the anonymous-abuse surface (F-01, F-03 below) as a launch blocker. Landing and `/methodology` stay public; the product does not. | +| D-3 | **Deploy to Railway** | 2026-08-02 | TLS, certificates and a public hostname are solved by the platform. Two platform constraints in § 3 change the topology. | +| D-4 | **No fork. `Deploy` is a normal feature branch, merged back to `main` in slices** | 2026-08-02 | See § 5.5. | +| D-5 | **Explicit per-provider client classes**, not a generic OpenAI-compatible adapter layer | 2026-08-02 | Less code, and the wire contract of each provider is visible at its call site instead of hidden behind a shape that fits none of them exactly. Cost: adding a fourth provider later means writing a class, not setting a variable. Accepted. | +| D-6 | **One shared account**, not per-reviewer accounts | 2026-08-02 | No user table, no migration, no account lifecycle. The daily query cap in PR 3 is therefore per *session*, not per person, and a shared password cannot be revoked for one holder — rotate it instead. Adequate for a gated demo; not an authorization model. | + +Decisions still open are in § 11. + +--- + +## 2. Model Configuration Parity + +**This constraint outranks every other item in this document.** + +The project's central property is that the figures on `/methodology`, in +`README.md` and in `Final_Report.md` describe the system that is actually +running. All of them are generated from +`results/eval-h1-repeat3-2026-07-31/` by `scripts/sync_eval_artifacts.py`, and +`make check` fails if any displayed surface drifts from that directory. + +That recorded run used exactly three models: + +| Role | Model | Dimension | +|---|---|---| +| Embedding | `jinaai/jina-embeddings-v2-base-code` | 768 | +| Reranker | `BAAI/bge-reranker-v2-m3` | — | +| Synthesis | `gpt-4o-mini` | — | + +All three are available as hosted APIs, so **D-1 can be satisfied without +changing a single model**: + +| Role | Provider | Endpoint | Model id | +|---|---|---|---| +| Embedding | Jina AI | `https://api.jina.ai/v1/embeddings` | `jina-embeddings-v2-base-code` | +| Reranker | SiliconFlow | `https://api.siliconflow.cn/v1/rerank` | `BAAI/bge-reranker-v2-m3` | +| Synthesis | OpenAI | `https://api.openai.com/v1` (already supported via `OPENAI_BASE_URL`) | `gpt-4o-mini` | + +**The rule.** The deployed configuration must use these three models. If a future +change substitutes any of them — a different embedding model, Jina's own +reranker instead of BGE, a different synthesis model — then the generated figures +no longer describe the deployed system, and one of two things must happen in the +same change: + +1. the substitution is reverted; or +2. the landing page and `/methodology` carry an explicit statement that the + deployed configuration differs from the evaluated one, naming the difference. + +Silently deploying different models under the same numbers is the single most +damaging thing this workstream could do. It is not a performance question; it is +the same class of error as hand-typing a figure into prose. + +**A caveat that is not resolved.** Serving the same weights through a provider's +API is not bit-identical to serving them locally: batching, quantization, and +model-version pinning are the provider's decisions, not ours. Parity of *model +identity* is achievable and required; parity of *output* is not guaranteed. This +does not affect the recorded verdict, which stays the authority and is not +regenerated. It does mean that **if the H1 suite is ever re-run through the API +providers, that is a new run directory with its own `provenance.json`, not a +refresh of the recorded snapshot.** + +### 2.1 Not yet verified + +Two facts this plan depends on and that must be confirmed with a live call +**before** the database volume is migrated, because `chunks.embedding` fixes its +dimension at migration time: + +- **Jina's API returns 768-dimensional vectors for `jina-embeddings-v2-base-code`.** + The model card and the recorded run both say 768, but the API response was not + observed in this session. One request settles it. +- **SiliconFlow's rerank request/response field names.** The client in § 6.2 must + be written against the observed payload, not against an assumed one. + +--- + +## 3. Verified Platform Constraints (Railway) + +Checked against Railway's documentation and community answers on **2026-08-02**. +Platform behaviour changes; re-verify before relying on any row. + +| # | Constraint | Consequence for Dcode | +|---|---|---| +| R-1 | **A volume can be attached to only one service.** Railway recommends sharing data through Postgres/Redis rather than a volume. | `repo_workdirs` is written by `worker` and read by `agent` (`docker-compose.yml:103-104`, `:185-186`). The agent's `read_file` / `grep` / `list_directory` tools read that tree directly and raise `FileNotFoundError` without it (`apps/agent/src/dcode_agent/tools/common.py:38-43`). **Worker and agent must therefore share one Railway service.** | +| R-2 | **HTTP requests are closed after 5 minutes with no data transferred, and capped at ~15 minutes with keep-alive heartbeats.** | The agent emits no heartbeat frames and has **no overall request timeout** at all — `/internal/query` spawns a task and returns a stream immediately (`apps/agent/src/dcode_agent/main.py:94-109`), with per-hop timeouts only, giving a theoretical upper bound past 8 minutes. Needs both a heartbeat and a hard budget. | +| R-3 | **The default Postgres template does not ship pgvector**; the extension must exist at the server level. | Use a pgvector template for the Postgres service. `infra/postgres/init.sql` only runs `CREATE EXTENSION IF NOT EXISTS vector`, which fails if the binary is absent. | +| R-4 | **Private-network DNS names (`*.railway.internal`) change IP on every redeploy**, and legacy environments resolve IPv6-only. | nginx caches DNS resolution indefinitely with a literal `proxy_pass`. The frontend config must use `resolver [fd12::10] ipv6=on valid=1s;` plus a variable-form `proxy_pass`. | + +R-1 is the only one that changes the architecture. R-2 through R-4 are configuration. + +--- + +## 4. Target Topology + +``` + [ public HTTPS — Railway-managed TLS ] + │ + ┌────────────▼────────────┐ + │ frontend │ public + │ nginx + static bundle │ + └────────────┬────────────┘ + │ /api/* → api.railway.internal:8000 + ┌────────────▼────────────┐ + │ api │ private + │ FastAPI gateway + auth │ + └────────────┬────────────┘ + │ AGENT_URL → agent-worker.railway.internal:8001 + ┌────────────▼────────────┐ + │ agent-worker │ private, owns the only volume + │ agent (:8001) + worker │ + └────────────┬────────────┘ + │ + ┌──────────────────────────────┼──────────────────────────────┐ + ▼ ▼ ▼ + Postgres (pgvector) Redis RabbitMQ +``` + +Six services. The public surface is unchanged from the documented design: the +frontend is the only thing reachable, and it proxies `/api/*` to an API that is +still the only backend entry point. Merging `agent` and `worker` into one +container is a **platform workaround for R-1**, not an architectural revision — +the agent still exposes only `/internal/*` behind the internal API key, and the +worker still consumes from RabbitMQ. + +--- + +## 5. Standing Constraints for This Workstream + +These are invariants. A PR that breaks one should not merge, even if it works. + +### 5.1 The local multi-container path must not regress + +Every mode that works today must still work after this workstream: + +| Mode | How it starts | Needs network / keys | +|---|---|---| +| stub | `make up` | no | +| Docker sidecars | `make up-embed` / `make up-rerank` | weights download on first run | +| host sidecars | `make embedding-host` + `make reranker-host` + `make up` | weights download on first run | +| **API providers (new)** | `make up` with `EMBEDDING_PROVIDER` / `RERANKER_PROVIDER` set | yes | + +Concretely: `apps/embedding/`, `apps/reranker/`, the `embedding` / `reranker` +Compose profiles, `scripts/start-*-host.sh`, `HttpEmbeddingClient` and +`HttpRerankerClient` are all **untouched** by this workstream. + +The one place this could be broken carelessly is R-1. The worker+agent merge is a +Railway-only entrypoint. `dcode_agent.main:app` and `dcode_worker.main` both keep +their own entrypoints (`infra/docker/agent.Dockerfile:22-24`, +`infra/docker/worker.Dockerfile:21`), and `docker-compose.yml` keeps two separate +containers sharing the volume. **Local Docker supports shared volumes; Railway +does not. That is a platform difference, not a code difference, and the local +path must not be degraded to match the constrained one.** + +### 5.2 The provider switch is additive, not a replacement + +`create_embedding_client()` (`packages/shared/src/dcode_shared/embedding.py:125-149`) +and `create_reranker_client()` (`packages/shared/src/dcode_shared/reranker.py:109-127`) +currently branch on one condition, `model == "stub"`. The API providers are a new +branch beside the existing sidecar branch, selected by an explicit +`EMBEDDING_PROVIDER` / `RERANKER_PROVIDER` whose default is `sidecar`. Existing +`.env` files, existing tests, and existing Compose invocations keep their current +behaviour with no edit. + +### 5.3 CI stays keyless + +`.github/workflows/ci.yml` currently requires no secrets. It must still require +none. Tests for the new clients mock the HTTP layer; they never call a live API. + +### 5.4 Embedding configuration must be identical on `api` and `agent-worker` + +The worker writes vectors at index time; the API embeds the query at search time. +They are separate processes reading the same settings. Setting the provider on +one and not the other produces **no error** — it produces Jina vectors in the +database being searched with a stub all-zero query vector +(`packages/shared/src/dcode_shared/embedding.py:37-38`), i.e. dense retrieval +silently returning noise. This is already latent in `docker-compose.prod.yml`, +where the `api` service has no embedding configuration at all (F-02). + +The mitigation is not discipline. It is the readiness check in PR 5: compare the +configured `EMBEDDING_DIM` against the live `vector_dims` of `chunks.embedding` +at startup and report not-ready on a mismatch, rather than discovering it on the +first insert. + +### 5.5 Branch and release policy + +- No fork. `Deploy` is a feature branch; the work merges to `main` as the five + PRs in § 6, each independently green under `make check`. +- Nothing lands on `main` that leaves it in a worse state than `v1.0-submission`. +- Secrets never enter the repository. `.gitignore:11-14` already covers `.env`, + `.env.production`, `.env.local`; Railway environment variables are configured + in the Railway dashboard, not in a committed file. +- `.env.production.example` stays committed and stays free of real values. + +### 5.6 `docker-compose.prod.yml` is fixed, not deleted + +`Final_Report.md` lists "a production-shaped Docker Compose package" as +delivered. Deleting it to make room for Railway would turn that into a false +claim. After this workstream there are two supported paths — self-hosted Compose +and hosted Railway — and the Compose path is where the Railway configuration gets +validated locally before it is pushed. + +### 5.7 Displayed numbers are still generated, never typed + +Unchanged from `CLAUDE.md`, restated because this workstream touches +configuration rather than results and the rule is easy to forget in that context: +no figure from `results/` may be hand-written into `Deploy.md`, the README, the +UI, or a Railway description. + +--- + +## 6. Work Breakdown + +Five PRs, in dependency order. Each is independently reviewable, independently +revertable, and must pass `make check` and `make frontend-build` on its own. + +**Acceptance criteria are binding.** A PR is not done when the code is written; +it is done when its criteria are demonstrated, and honestly reported when they +are not. + +### PR 1 — `fix/prod-compose-model-env` — **done** + +Pure defect repair. Smallest, lands first, useful even if deployment never +happens. + +| Item | Detail | Outcome | +|---|---|---| +| F-02 | Give every service the retrieval settings it reads. See the correction below — this was wider than "the `api` service". | done | +| F-11 | Reconcile the two documented Compose invocations: `README.md:324` used `-f docker-compose.prod.yml` alone; `.env.production.example:4-5` documented overlaying it on `docker-compose.yml`, which republishes Postgres, Redis and the RabbitMQ management UI to the host. | done — standalone form, and both files now say so | +| F-12 | Remove the dead `RERANKER_ENDPOINT=http://localhost:9999` default. | done — empty default, which fails loudly for a real model and is ignored by a stub | +| F-13 | `max_retries=12` against a hardcoded 300 s timeout (`embedding.py:19-20`) can occupy one batch of four chunks for roughly an hour while `prefetch_count=1` stalls the queue behind it. | **partially done** — the timeout is now env-tunable (`EMBEDDING_TIMEOUT_SECONDS`) instead of hardcoded; the *values* are unchanged, because the defaults are correct for a cold CPU sidecar and the hosted-API path they are wrong for does not exist until PR 2. PR 2 sets them. | + +**Correction: F-02 was under-described in the original plan.** It was written as +"the `api` service has no embedding configuration". Reading what each service +actually reads showed all three were short: + +| Service | Was missing | +|---|---| +| `api` | every retrieval setting — all twelve | +| `worker` | `EMBEDDING_ENDPOINT`, `EMBEDDING_BATCH_SIZE`, `EMBEDDING_MAX_RETRIES` — so it had a model and a dimension but no way to reach a service | +| `agent` | `RERANKER_MODEL`, `RERANKER_MAX_RETRIES`, `EMBEDDING_DIM`, and the synthesis knobs. It had `RERANKER_ENDPOINT` alone, which selects nothing: `create_reranker_client` returns `None` for a stub model whatever the endpoint says (`packages/shared/src/dcode_shared/reranker.py:119-120`) | + +`EMBEDDING_DIM` also turned out to matter more widely than the migration. +`dcode_shared.db.models:128` binds the `chunks.embedding` column type to it at +**import time**, so every service that touches the ORM needs it correct, not just +the one that runs Alembic. It is now required in production (`${EMBEDDING_DIM:?…}`) +rather than defaulted, because a wrong value there is a re-index, not a slow query. + +**Acceptance — met.** + +1. `docker compose --env-file .env.production.example -f docker-compose.prod.yml config` + resolves 12 retrieval variables on `api`, 6 on `worker`, 9 on `agent`, all + mutually consistent. Observed. +2. Omitting `EMBEDDING_DIM` aborts the config with the reason attached rather + than silently defaulting. Observed. +3. `make check` green: ruff, eslint, the eval-artifact drift check, mypy strict + over 83 source files, 289 passed / 5 skipped in pytest, 73 frontend tests. +4. Three new tests in `packages/shared/tests/test_config_hardening.py` pin all + of the above, and **each was confirmed to fail when its defect is put back** — + a config test that has never been seen failing is not evidence of anything. + +### PR 2 — `feat/managed-model-providers` + +The capability behind D-1. + +- Add `JinaApiEmbeddingClient` to `packages/shared/src/dcode_shared/embedding.py`. + The sidecar contract is an unauthenticated `POST {endpoint}/embed` with + `{"texts": [...]}` returning `{"embeddings": [[...]]}` (`embedding.py:87-90`); + Jina's is an authenticated `POST /v1/embeddings` with `{"model", "input"}` + returning `{"data": [{"index", "embedding"}]}`. **Results must be reordered by + `index`, not trusted in arrival order.** +- Add the SiliconFlow reranker client to + `packages/shared/src/dcode_shared/reranker.py`. Same shape of problem: the + sidecar returns `{"scores": [...]}` in passage order (`reranker.py:54-61`); + a rerank API returns scored results carrying their own index, which must be + mapped back to input order before returning. +- Select with `EMBEDDING_PROVIDER` / `RERANKER_PROVIDER`, default `sidecar` + (§ 5.2). Add `EMBEDDING_API_KEY` / `RERANKER_API_KEY`. +- Per D-5 these are **two concrete classes with the provider's own payload shape + written out**, not a generic adapter parameterised by field names. Neither + provider is OpenAI-compatible in the part that matters — the response carries + per-item indices that must be mapped back — so a shared abstraction would have + to model the difference anyway. +- Timeouts and retries appropriate to a hosted API, not to a cold local model. + +**Acceptance.** + +1. Unit tests with a mocked transport cover: correct reordering, dimension + validation, auth header present, non-retryable 4xx surfacing, retryable 5xx + retrying. No live calls (§ 5.3). +2. **A live local run, reported with real observed values:** index `psf/requests` + with `EMBEDDING_PROVIDER=jina_api`, then confirm from the database that the + vectors are 768-dimensional and non-zero — this is the § 2.1 check and it must + happen before any Railway volume is migrated. Confirm the reranker is + materially reordering results rather than passing through. +3. `make check` green, and all four modes in § 5.1 still start. + +### PR 3 — `feat/auth-gate` + +D-2. Also closes F-01 and F-03. + +- `POST /api/v1/auth/login`, `POST /api/v1/auth/logout`, `GET /api/v1/auth/me`. + Per D-6, **one shared account read from the environment** — no user table, no + migration. The password is stored as a hash, never as plaintext in the repo or + in a committed file. Signed, `HttpOnly`, `Secure`, `SameSite=Lax` cookie. +- A dependency on the `repos`, `query` and `inspector` routers + (`apps/api/src/dcode_api/main.py:45-47`). `/healthz` stays open. +- Frontend `/login` route; `/workbench` checks the session and redirects on 401. + `/` and `/methodology` remain public — they are the part meant to be read. +- F-05: disable `/docs`, `/redoc` and `/openapi.json` in production. They are + public today and advertise the `/internal/*` surface. +- A per-session daily query cap. The login wall removes anonymous abuse; it does + not remove a logged-in user looping a query against a metered API. + +**Acceptance.** An unauthenticated request to each protected route returns 401. +`/`, `/methodology` and `/healthz` are reachable without a session. The +`/workbench` redirect is verified **by a human in a browser** — headless +screenshots do not work in this environment, and that limitation is not a reason +to claim the check passed. + +### PR 4 — `feat/railway-deploy` + +The only Railway-specific PR. Mostly additive files. + +- R-1: a combined `agent` + `worker` entrypoint used **only** by the Railway + service. `docker-compose.yml` is not touched (§ 5.1). +- R-2: SSE heartbeat frames (a `:` comment line on an interval below Railway's + 5-minute idle cut). The frontend parser already skips `:` lines + (`apps/frontend/src/api/client.ts:142-144`), so no frontend change is required. + Plus an overall agent request budget that expires inside Railway's window and + emits a clean `error` event rather than being cut by the platform. +- R-4 and static-serving fixes in `apps/frontend/nginx.conf`: variable-form + `proxy_pass` with `resolver`, an explicit `proxy_read_timeout` for the SSE + path, `listen` on the platform-assigned port, **gzip on** (verified off by + default in `nginx:1.27-alpine`; the built main chunk is 752.53 kB, 226.74 kB + gzipped), and long-lived cache headers on hashed assets. +- A root `.dockerignore` and one for `apps/frontend` (the frontend build context + currently ships 227 MB of `node_modules` to the daemon; the root context is + 391 MB). +- F-09: `GET /api/v1/repos` so the workbench can list indexed repositories. + Today the switcher reads `localStorage` only + (`apps/frontend/src/lib/recentRepos.ts:8`) and there is no default repository, + so a first-time visitor on a new device sees an empty workbench. + +**Acceptance.** A live deployment reachable over HTTPS; login works; one indexed +repository is selectable; a query streams to completion with verified citations; +clicking a citation opens real indexed source. Every one of those is confirmed by +a human in a browser and reported with what was actually seen. + +### PR 5 — `fix/audit-followups` + +Findings that are not launch blockers but should not ship unaddressed. +See the register in § 7 for F-04, F-06, F-07, F-08, F-10, F-14, F-15. + +**Acceptance.** Each item either fixed with a test, or explicitly deferred in +this document with a reason. Silence is not an outcome. + +--- + +## 7. Findings Register + +Every row carries a `file:line` so it can be checked rather than believed. + +**Verification column.** `direct` — confirmed in this session by reading the file, +running the command, or resolving the Compose config. `audit` — reported by a +code-audit pass with a citation, not independently re-checked. Treat `audit` rows +as leads to verify when the PR touches them, not as established fact. + +| # | Finding | Where | Severity | PR | Verified | +|---|---|---|---|---|---| +| F-01 | No authentication of any kind on `/api/v1/*`; no user or tenant concept, so any caller can read any indexed repo by `repo_id` | `apps/api/src/dcode_api/main.py:45-47` | blocker | 3 | audit | +| F-02 | ~~The `api` service in the production Compose file has no embedding or reranker configuration~~ **— fixed in PR 1, and it was wider than this row said: `worker` and `agent` were short too. See § 6 PR 1.** | `docker-compose.prod.yml` | blocker | 1 | **direct** | +| F-03 | No rate limiting, no request-size limit, no quota. `QueryRequest.query` has `min_length` but no `max_length` | `packages/shared/src/dcode_shared/schemas.py:132` | blocker | 3 | audit | +| F-04 | `INTERNAL_API_KEY` defaults to a literal published in this repository, with no startup guard outside Compose's `:?` operator — and Railway sets variables per service, so that operator does not protect the deployment | `packages/shared/src/dcode_shared/settings.py:33` | high | 5 | audit | +| F-05 | `/docs`, `/redoc` and `/openapi.json` are publicly served and advertise the `/internal/*` surface | `apps/api/src/dcode_api/main.py:31-35` | high | 3 | audit | +| F-06 | SSRF: repository URL validation rejects literal private IPs but has no host allowlist and no resolution check, so a hostname resolving to an internal address passes | `apps/api/src/dcode_api/routes/repos.py:203-224` | high | 5 | audit | +| F-07 | The agent tool cache key omits `index_revision`, so re-indexing a repository does not invalidate cached tool results for up to 24 h | `apps/agent/src/dcode_agent/graph.py:119` | high | 5 | audit | +| F-08 | Cloned workdirs are never cleaned up, for any repository, ever. On a fixed Railway volume this is unbounded growth | `apps/worker/src/dcode_worker/stages/clone.py:17-22` | high | 5 | audit | +| F-09 | No repository list endpoint; the switcher reads `localStorage` only and there is no default repository | `apps/frontend/src/lib/recentRepos.ts:8` | high | 4 | **direct** | +| F-10 | `/healthz` returns `ok` unconditionally — it reports healthy with every dependency down. No readiness probe exists | `apps/api/src/dcode_api/main.py:51-54` | medium | 5 | audit | +| F-11 | ~~The two documented production Compose invocations disagree; one of them republishes Postgres, Redis and the RabbitMQ UI~~ **— fixed in PR 1.** | `README.md`, `.env.production.example` | medium | 1 | **direct** | +| F-12 | ~~`RERANKER_ENDPOINT` defaults to a dead loopback address in the production template~~ **— fixed in PR 1, pinned by a test.** | `docker-compose.prod.yml`, `.env.production.example` | medium | 1 | **direct** | +| F-13 | Embedding retries are 12 attempts against a 300 s timeout; with `prefetch_count=1` one bad batch stalls the entire indexing queue. **Knob added in PR 1 (`EMBEDDING_TIMEOUT_SECONDS`); the values are set in PR 2, where the path that needs them exists.** | `packages/shared/src/dcode_shared/embedding.py:19-20` | medium | 1 → 2 | audit | +| F-14 | `git clone` receives the repository URL with no `--` separator, so a URL beginning with `-` is parsed as an option. Gateway validation is the only defence; the worker has none | `apps/worker/src/dcode_worker/stages/clone.py:22` | medium | 5 | audit | +| F-15 | The `grep` tool runs `rg` with no timeout and buffers all output in memory; the pure-Python fallback compiles a user-supplied regex with no timeout | `apps/agent/src/dcode_agent/tools/grep.py:44-58`, `:79-101` | medium | 5 | audit | +| F-16 | nginx serves the bundle uncompressed — gzip is commented out in the base image and not enabled in the site config. Main chunk 752.53 kB / 226.74 kB gzipped | `apps/frontend/nginx.conf` | low | 4 | **direct** | +| F-17 | No `.dockerignore` anywhere; the frontend build context ships 227 MB of `node_modules` | repository root | low | 4 | **direct** | +| F-18 | Model sidecars download weights from Hugging Face at runtime with no cache volume | `infra/docker/embedding.Dockerfile`, `infra/docker/reranker.Dockerfile` | low | — | **direct** | + +F-18 is recorded but **not scheduled**: D-1 removes the sidecars from the +deployment path, so it only affects local Docker-profile use. It is left as a +known cost of that mode rather than fixed speculatively. + +### Already correct, recorded so nobody "fixes" it + +- SSE anti-buffering headers are set on both hops — `Cache-Control: no-cache` and + `X-Accel-Buffering: no` at `apps/api/src/dcode_api/routes/query.py:43-44` and + `apps/agent/src/dcode_agent/main.py:108`. R-2 is a platform *timeout*, not a + buffering problem, and does not indicate these are wrong. +- Agent path handling is sound: `normalize_repo_relative_path` rejects absolute + and `..`-escaping paths and the resolved path is re-checked against the root + (`apps/agent/src/dcode_agent/tools/common.py:46-76`). +- In the production topology the `api` service publishes no host port and nginx + proxies only `location /api/`, so `/internal/*` is not reachable from outside. + +--- + +## 8. New Environment Variables + +Added by this workstream. Every one defaults to current behaviour. + +| Variable | Default | Read by | Purpose | +|---|---|---|---| +| `EMBEDDING_PROVIDER` | `sidecar` | api, worker | `sidecar` \| `jina_api` | +| `EMBEDDING_API_KEY` | `""` | api, worker | Required when the provider is not `sidecar` | +| `RERANKER_PROVIDER` | `sidecar` | api | `sidecar` \| `siliconflow` | +| `RERANKER_API_KEY` | `""` | api | Required when the provider is not `sidecar` | +| `AUTH_USERNAME` | — | api | Demo account name | +| `AUTH_PASSWORD_HASH` | — | api | Hash, never a plaintext password | +| `AUTH_SESSION_SECRET` | — | api | Cookie signing key | +| `AUTH_DAILY_QUERY_LIMIT` | (to set) | api | Per-session spend guard | +| `AGENT_REQUEST_BUDGET_SECONDS` | (to set) | agent | R-2 hard ceiling | +| `SSE_HEARTBEAT_SECONDS` | (to set) | api, agent | R-2 keep-alive interval | +| `DOCS_ENABLED` | `false` in production | api | F-05 | + +`EMBEDDING_DIM` keeps its existing meaning and its existing trap: it is fixed +into the pgvector column at migration time. Changing it requires a fresh volume. +Switching providers is now a one-line edit, which makes that trap *easier* to +trigger than it was when it required starting a sidecar. + +`JUDGE_MODEL` is passed by both Compose files and defined in settings but is +referenced by no code. It is left alone here; removing dead configuration is a +product decision, not a deployment one. + +--- + +## 9. Cost + +Order-of-magnitude only. No figure here is measured, and none should be quoted +as if it were. + +- **Embedding** is paid once per index, not per query. Jina offers a free tier, + and the corpus is small — the chunk count of the indexed `psf/requests` + snapshot is recorded in [`docs/en/Operations.md`](docs/en/Operations.md), not + restated here. +- **Reranking** runs per query over a candidate list capped by + `RERANKER_CANDIDATE_LIMIT` (default 16). +- **Synthesis** is one `gpt-4o-mini` call per query, bounded by + `SYNTHESIS_MAX_TOKENS` (default 700) with an input side bounded by a 10-item + evidence budget. A follow-up question costs a second, smaller call. +- **Railway** bills six services by usage; an idle gated demo is small. + +The real exposure is not the unit price — it is an unbounded number of calls. +D-2 removes anonymous callers; `AUTH_DAILY_QUERY_LIMIT` bounds authenticated +ones. Both are required. + +--- + +## 10. Verification Checklist + +Two limits of this environment apply to every claim made about this work, and +neither is a reason to soften a report: + +- **Headless screenshots do not work.** Anything visual is confirmed by a human + in a real browser, or it is reported as unconfirmed. Say what to look at. +- **There is no automated end-to-end test spanning browser and live backend.** + +Before calling the deployment done: + +| # | Check | How | +|---|---|---| +| 1 | Vectors in the deployed database are 768-dimensional and non-zero | `SELECT vector_dims(embedding), left(embedding::text, 20) FROM chunks LIMIT 1;` | +| 2 | The reranker is actually reordering, not passing through | Compare `score_components` on a query with and without rerank | +| 3 | `api` and `agent-worker` agree on embedding configuration | § 5.4 readiness check reports ready | +| 4 | A query streams to completion without being cut | Watch a full run; confirm no truncation at 5 minutes (R-2) | +| 5 | Citations are verified and clickable, and open real indexed source at the cited line | Human, in a browser | +| 6 | Call-graph neighbours are clickable and chain | Human, in a browser | +| 7 | Unauthenticated access to `/workbench` and to each protected route is refused | Private window | +| 8 | `/` and `/methodology` load without a session, and their figures match `results/` | `python3 scripts/sync_eval_artifacts.py --check` | +| 9 | The four local modes in § 5.1 all still start | Locally, after the final PR | + +--- + +## 11. Open Questions + +Carried here rather than answered by assumption. + +1. **Team ownership.** `README.md` assigns "infrastructure, deployment" to a + different team member, and `origin` carries four `yuxin_*` branches. This plan + should be reconciled with them before PR 4. *Not resolved.* Pushing `Deploy` + and `v1.0-submission` makes it visible to them, which is the point. +2. **Long-term fix for R-1.** Merging agent and worker is a workaround. The + durable answer is to stop reading repository source from a shared filesystem — + store file contents in Postgres and have the agent's file tools read from + there. That is a migration plus three tool rewrites, deliberately out of scope + here. *Deferred, recorded.* diff --git a/README.md b/README.md index 58a9768..4734539 100644 --- a/README.md +++ b/README.md @@ -326,8 +326,19 @@ docker compose --env-file .env.production -f docker-compose.prod.yml exec api \ uv run alembic -c infra/migrations/alembic.ini upgrade head ``` +`docker-compose.prod.yml` is a complete stack, **not an overlay**. Combining it +with `-f docker-compose.yml` republishes Postgres, Redis and the RabbitMQ +management UI to the host. + +Every service that touches retrieval — api, worker and agent — reads the same +embedding and reranker configuration, and they must agree. `EMBEDDING_DIM` has +no production default on purpose: the migration bakes it into the pgvector +column, so a wrong value is a re-index rather than a slow query. + The production stack is validated locally only — `dcode.odieyang.com` does **not** -resolve publicly, so the external-demo exit criterion is still open. +resolve publicly, so the external-demo exit criterion is still open. The plan for +closing it, including the platform constraints that shape it, is +[`Deploy.md`](Deploy.md). --- @@ -474,7 +485,8 @@ H1 could be evaluated with a simpler indexing script; the queue, worker, state m ## Documentation -Five documents. `docs/en/` is authoritative. +Six documents. `docs/en/` is authoritative; [`Deploy.md`](Deploy.md) sits at the +root because it governs an in-flight workstream rather than the delivered system. | Document | Contents | |---|---| @@ -483,6 +495,7 @@ Five documents. `docs/en/` is authoritative. | **[`docs/en/Technical_Design.md`](docs/en/Technical_Design.md)** | Technical authority: repository layout, architecture, service boundaries, data model, API contracts, NFRs, technology choices | | **[`docs/en/Operations.md`](docs/en/Operations.md)** | Running the stack, the real-model path, the evaluation harness, and the operational gotchas worth knowing before you hit them | | **[`docs/en/Agentic_Workflow.md`](docs/en/Agentic_Workflow.md)** | How Claude Code, Codex, and Cursor were cross checked during development | +| **[`Deploy.md`](Deploy.md)** | Taking this online: decisions taken, verified platform constraints, the invariants, the PR breakdown with acceptance criteria, and a findings register where every row carries a `file:line` | Colocated with what they describe: [`results/README.md`](results/README.md) (which recorded run is the current conclusion), [`design/README.md`](design/README.md) diff --git a/apps/api/src/dcode_api/routes/internal.py b/apps/api/src/dcode_api/routes/internal.py index 1237b1e..a0b52be 100644 --- a/apps/api/src/dcode_api/routes/internal.py +++ b/apps/api/src/dcode_api/routes/internal.py @@ -370,6 +370,7 @@ def _get_query_embedding_client() -> EmbeddingClient: endpoint=api_settings.embedding_endpoint, batch_size=api_settings.embedding_batch_size, max_retries=api_settings.embedding_max_retries, + timeout_seconds=api_settings.embedding_timeout_seconds, ) return _query_embedding_client diff --git a/apps/worker/src/dcode_worker/stages/embed.py b/apps/worker/src/dcode_worker/stages/embed.py index 646c399..d60cb3a 100644 --- a/apps/worker/src/dcode_worker/stages/embed.py +++ b/apps/worker/src/dcode_worker/stages/embed.py @@ -53,6 +53,7 @@ async def run( endpoint=worker_settings.embedding_endpoint, batch_size=worker_settings.embedding_batch_size, max_retries=worker_settings.embedding_max_retries, + timeout_seconds=worker_settings.embedding_timeout_seconds, ) owns_redis = redis_client is None diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index 0e43fb7..2691ea8 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -51,6 +51,22 @@ services: AGENT_URL: http://agent:8001 CORS_ORIGINS: ${PUBLIC_ORIGIN:-http://dcode.odieyang.com} INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env.production} + # The API embeds the query and reranks candidates at search time, so it + # needs the same retrieval configuration as the worker — not a subset. + # It is also where `make prod-migrate` runs, and the migration reads + # EMBEDDING_DIM to size the pgvector column. + EMBEDDING_MODEL: ${EMBEDDING_MODEL:-stub} + EMBEDDING_DIM: ${EMBEDDING_DIM:?set EMBEDDING_DIM in .env.production — it is fixed into the pgvector column at migration time and cannot be changed without a new volume} + EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-} + EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} + EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} + RRF_DENSE_WEIGHT: ${RRF_DENSE_WEIGHT:-2.0} + RRF_SPARSE_WEIGHT: ${RRF_SPARSE_WEIGHT:-1.0} + RERANKER_MODEL: ${RERANKER_MODEL:-stub} + RERANKER_ENDPOINT: ${RERANKER_ENDPOINT:-} + RERANKER_CANDIDATE_LIMIT: ${RERANKER_CANDIDATE_LIMIT:-16} + RERANKER_MAX_RETRIES: ${RERANKER_MAX_RETRIES:-3} LOG_LEVEL: ${LOG_LEVEL:-info} depends_on: postgres: @@ -75,7 +91,11 @@ services: REDIS_URL: redis://redis:6379/0 RABBITMQ_URL: amqp://${RABBITMQ_USER:?set RABBITMQ_USER in .env.production}:${RABBITMQ_PASSWORD:?set RABBITMQ_PASSWORD in .env.production}@rabbitmq:5672/ EMBEDDING_MODEL: ${EMBEDDING_MODEL:-stub} - EMBEDDING_DIM: ${EMBEDDING_DIM:-1024} + EMBEDDING_DIM: ${EMBEDDING_DIM:?set EMBEDDING_DIM in .env.production — it must equal the dimension the volume was migrated at} + EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-} + EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} + EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} WORKDIR_BASE: /tmp/dcode-workdirs INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env.production} LOG_LEVEL: ${LOG_LEVEL:-info} @@ -107,7 +127,17 @@ services: SYNTHESIS_MODEL: ${SYNTHESIS_MODEL:-stub} OPENAI_API_KEY: ${OPENAI_API_KEY:-} OPENAI_BASE_URL: ${OPENAI_BASE_URL:-} - RERANKER_ENDPOINT: ${RERANKER_ENDPOINT:-http://localhost:9999} + SYNTHESIS_MAX_TOKENS: ${SYNTHESIS_MAX_TOKENS:-700} + SYNTHESIS_TEMPERATURE: ${SYNTHESIS_TEMPERATURE:-0.1} + # The agent reranks its own evidence union, so it needs the reranker + # configuration too — RERANKER_ENDPOINT alone selected nothing, because + # a stub RERANKER_MODEL returns no client regardless of the endpoint. + RERANKER_MODEL: ${RERANKER_MODEL:-stub} + RERANKER_ENDPOINT: ${RERANKER_ENDPOINT:-} + RERANKER_MAX_RETRIES: ${RERANKER_MAX_RETRIES:-3} + # Not read directly by the agent, but dcode_shared.db.models binds the + # chunks.embedding column type to it at import time. + EMBEDDING_DIM: ${EMBEDDING_DIM:?set EMBEDDING_DIM in .env.production — it must equal the dimension the volume was migrated at} RETRIEVAL_BASE_URL: http://api:8000 WORKDIR_BASE: /tmp/dcode-workdirs INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env.production} diff --git a/docker-compose.yml b/docker-compose.yml index 4451181..065b726 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -61,6 +61,7 @@ services: EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-http://host.docker.internal:8002} EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} RRF_DENSE_WEIGHT: ${RRF_DENSE_WEIGHT:-2.0} RRF_SPARSE_WEIGHT: ${RRF_SPARSE_WEIGHT:-1.0} RERANKER_MODEL: ${RERANKER_MODEL:-stub} @@ -97,6 +98,7 @@ services: EMBEDDING_ENDPOINT: ${EMBEDDING_ENDPOINT:-http://host.docker.internal:8002} EMBEDDING_BATCH_SIZE: ${EMBEDDING_BATCH_SIZE:-4} EMBEDDING_MAX_RETRIES: ${EMBEDDING_MAX_RETRIES:-12} + EMBEDDING_TIMEOUT_SECONDS: ${EMBEDDING_TIMEOUT_SECONDS:-300} WORKDIR_BASE: /tmp/dcode-workdirs INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env} LOG_LEVEL: ${LOG_LEVEL:-info} diff --git a/packages/shared/src/dcode_shared/embedding.py b/packages/shared/src/dcode_shared/embedding.py index af34ef7..bf74c45 100644 --- a/packages/shared/src/dcode_shared/embedding.py +++ b/packages/shared/src/dcode_shared/embedding.py @@ -129,6 +129,7 @@ def create_embedding_client( endpoint: str = "", batch_size: int = _DEFAULT_BATCH_SIZE, max_retries: int = _DEFAULT_MAX_RETRIES, + timeout_seconds: float = _DEFAULT_TIMEOUT_SECONDS, ) -> EmbeddingClient: """Build the embedding client for the current environment.""" if model == "stub": @@ -146,6 +147,7 @@ def create_embedding_client( dim=dim, batch_size=batch_size, max_retries=max_retries, + timeout_seconds=timeout_seconds, ) diff --git a/packages/shared/src/dcode_shared/settings.py b/packages/shared/src/dcode_shared/settings.py index c332927..c1a02b0 100644 --- a/packages/shared/src/dcode_shared/settings.py +++ b/packages/shared/src/dcode_shared/settings.py @@ -46,7 +46,15 @@ class SharedSettings(BaseSettings): embedding_dim: int = 1024 embedding_endpoint: str = "" embedding_batch_size: int = 4 + # The defaults below are sized for a cold self-hosted sidecar: a CPU Jina + # model can take minutes to load, and the retries exist to ride that out. + # Their product is the worst case, and it is long — 12 attempts against a + # 300s read timeout can hold one batch for about an hour while the worker + # (prefetch_count=1) stalls every other queued repository behind it. A + # hosted embedding API fails in seconds and should be configured with much + # smaller values; both are env-tunable so neither path pays the other's cost. embedding_max_retries: int = 12 + embedding_timeout_seconds: float = 300.0 # Weighted RRF for hybrid fusion. Dense gets higher weight because # equal 1:1 RRF lets sparse keyword noise dilute semantic ranking # (observed: B2 dense nDCG > B3 hybrid under equal weights). diff --git a/packages/shared/tests/test_config_hardening.py b/packages/shared/tests/test_config_hardening.py index 1ed07e3..716d998 100644 --- a/packages/shared/tests/test_config_hardening.py +++ b/packages/shared/tests/test_config_hardening.py @@ -1,9 +1,28 @@ """Configuration hardening checks for env examples and compose files.""" +import re from pathlib import Path _ROOT = Path(__file__).resolve().parents[3] +# A compose service block: ` name:` at two spaces, everything under it deeper. +# Parsed by hand rather than with PyYAML, which is only a transitive dependency +# here and is imported by no other code in this repository. +_SERVICE_HEADER = re.compile(r"^ {2}([a-z0-9_-]+):\s*$") + + +def _service_block(compose_text: str, service: str) -> str: + lines = compose_text.splitlines() + starts = [i for i, line in enumerate(lines) if _SERVICE_HEADER.match(line)] + for position, index in enumerate(starts): + match = _SERVICE_HEADER.match(lines[index]) + assert match is not None + if match.group(1) != service: + continue + end = starts[position + 1] if position + 1 < len(starts) else len(lines) + return "\n".join(lines[index:end]) + raise AssertionError(f"service {service!r} not found in compose file") + def test_env_examples_do_not_ship_known_weak_credentials() -> None: env_example = (_ROOT / ".env.example").read_text(encoding="utf-8") @@ -26,3 +45,94 @@ def test_prod_compose_requires_explicit_secret_env_vars() -> None: assert "${POSTGRES_PASSWORD:?" in compose assert "${RABBITMQ_PASSWORD:?" in compose assert "${INTERNAL_API_KEY:?" in compose + + +def test_prod_compose_requires_an_explicit_embedding_dimension() -> None: + """A defaulted EMBEDDING_DIM in production is not a slow query, it is a re-index. + + The migration sizes the pgvector column from this value + (infra/migrations/versions/001_initial_schema.py) and the ORM binds the + column type to it at import time (dcode_shared.db.models). Once the volume + exists the dimension cannot change, so production must state it rather than + inherit the 1024 code default that happens to suit stub vectors. + """ + compose = (_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8") + + assert "${EMBEDDING_DIM:-" not in compose + assert "${EMBEDDING_DIM:?" in compose + + +def test_prod_services_receive_the_retrieval_settings_they_read() -> None: + """Every service must be able to receive each setting it actually reads. + + Violating this produces no error and no log line. The API embeds the search + query and the worker embeds the corpus; if only one of them is configured, + real vectors get searched with a stub all-zero query vector and dense + retrieval silently returns noise. The production API shipped with none of + these, which also meant `make prod-migrate` built the column at the default + dimension no matter what the env file said. + + The expected sets below are what each service reads today. If a service + starts reading a new setting, add it here as well as to the compose file. + """ + compose = (_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8") + + expected = { + # dcode_api.routes.internal builds both the query embedding client and + # the query reranker client, and fuses with the RRF weights. + "api": { + "EMBEDDING_MODEL", + "EMBEDDING_DIM", + "EMBEDDING_ENDPOINT", + "EMBEDDING_BATCH_SIZE", + "EMBEDDING_MAX_RETRIES", + "EMBEDDING_TIMEOUT_SECONDS", + "RRF_DENSE_WEIGHT", + "RRF_SPARSE_WEIGHT", + "RERANKER_MODEL", + "RERANKER_ENDPOINT", + "RERANKER_CANDIDATE_LIMIT", + "RERANKER_MAX_RETRIES", + }, + # dcode_worker.stages.embed builds the index-time embedding client. + "worker": { + "EMBEDDING_MODEL", + "EMBEDDING_DIM", + "EMBEDDING_ENDPOINT", + "EMBEDDING_BATCH_SIZE", + "EMBEDDING_MAX_RETRIES", + "EMBEDDING_TIMEOUT_SECONDS", + }, + # dcode_agent.graph reranks its own evidence union; EMBEDDING_DIM is + # not read by the agent directly but binds the ORM column type. + "agent": { + "EMBEDDING_DIM", + "RERANKER_MODEL", + "RERANKER_ENDPOINT", + "RERANKER_MAX_RETRIES", + "SYNTHESIS_MODEL", + "SYNTHESIS_MAX_TOKENS", + "SYNTHESIS_TEMPERATURE", + "GROUNDEDNESS_THRESHOLD", + }, + } + + for service, variables in expected.items(): + block = _service_block(compose, service) + missing = sorted(name for name in variables if f"\n {name}:" not in block) + assert not missing, f"{service} is missing {missing} in docker-compose.prod.yml" + + +def test_no_dead_loopback_endpoints_in_production_config() -> None: + """A reranker endpoint pointing at localhost:9999 inside a container. + + It resolved to nothing, and because RERANKER_MODEL defaulted to stub the + client was never built, so the dead address never produced an error either. + An empty endpoint is the honest default: a real model with no endpoint + raises at construction, and a stub model ignores it. + """ + compose = (_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8") + env_prod_example = (_ROOT / ".env.production.example").read_text(encoding="utf-8") + + for content in (compose, env_prod_example): + assert "localhost:9999" not in content