nlm-memory 0.20.0 → 0.21.0

package/fixtures/classifier-gold/transcripts/04-feature-webhook-retry.txt

@@ -0,0 +1,95 @@
+User: taskstream needs exponential backoff retry for failed webhook deliveries. Right now if a delivery fails it just drops the event. We need up to 5 retry attempts with exponential backoff, delays stored in Redis so retries survive restarts.
+
+Agent: I'll design this before writing code. The approach: use a Redis sorted set where the score is the Unix timestamp of the next attempt. A background worker polls for jobs whose score is <= now, attempts delivery, and either marks the job done or reschedules it with a doubled delay. After 5 attempts the job is moved to a dead-letter key.
+
+Does this fit the existing architecture? Let me check what's already in place.
+
+[Read: src/delivery/deliver.ts]
+[Read: src/worker/retry-worker.ts]
+
+The deliver.ts module handles HTTP POST; retry-worker.ts exists but is a stub. Good starting point.
+
+User: That architecture sounds right. Go ahead.
+
+Agent: [Edit: src/delivery/retry-queue.ts] (new file)
+
+```typescript
+import { createClient } from "redis";
+
+const RETRY_KEY = "taskstream:retry";
+const DEAD_KEY  = "taskstream:dead";
+const MAX_ATTEMPTS = 5;
+const BASE_DELAY_MS = 5_000;
+
+export async function enqueueRetry(
+  redis: ReturnType<typeof createClient>,
+  jobId: string,
+  attempt: number,
+): Promise<void> {
+  if (attempt >= MAX_ATTEMPTS) {
+    await redis.lPush(DEAD_KEY, jobId);
+    return;
+  }
+  const delayMs = BASE_DELAY_MS * Math.pow(2, attempt);
+  const score = Date.now() + delayMs;
+  await redis.zAdd(RETRY_KEY, { score, value: jobId });
+}
+
+export async function pollDueRetries(
+  redis: ReturnType<typeof createClient>,
+): Promise<string[]> {
+  const now = Date.now();
+  return redis.zRangeByScore(RETRY_KEY, "-inf", now);
+}
+
+export async function removeFromQueue(
+  redis: ReturnType<typeof createClient>,
+  jobId: string,
+): Promise<void> {
+  await redis.zRem(RETRY_KEY, jobId);
+}
+```
+
+[Edit: src/worker/retry-worker.ts]
+
+Updated the stub to poll every 5 seconds, attempt delivery for each due job, and call enqueueRetry with incremented attempt count on failure or removeFromQueue on success.
+
+User: What's the delay schedule for 5 attempts?
+
+Agent: With BASE_DELAY_MS = 5000 and doubling per attempt:
+- Attempt 0 -> 1: 5 seconds
+- Attempt 1 -> 2: 10 seconds
+- Attempt 2 -> 3: 20 seconds
+- Attempt 3 -> 4: 40 seconds
+- Attempt 4 -> 5: dead letter (no 6th attempt)
+
+Total window before dead-letter: ~75 seconds. If you want longer, we can increase BASE_DELAY_MS or switch from 2x to a larger multiplier.
+
+User: 75 seconds is fine for v1. What key format is used for job IDs?
+
+Agent: [Read: src/jobs/job-id.ts]
+
+Job IDs are UUIDs generated at event creation time, e.g. `evt_a3f7c290`. The retry queue stores these as ZADD values directly.
+
+User: Add a unit test for the delay schedule.
+
+Agent: [Write: tests/unit/delivery/retry-queue.test.ts]
+
+Test covers: first enqueue sets correct score within 100ms tolerance, fifth attempt goes to dead letter, pollDueRetries returns jobs whose score is in the past, removeFromQueue removes only the target job.
+
+User: Run it.
+
+Agent: [Bash: npm test -- tests/unit/delivery/retry-queue.test.ts]
+
+```
+PASS tests/unit/delivery/retry-queue.test.ts
+  enqueueRetry
+    ✓ schedules retry with exponential delay (12ms)
+    ✓ moves to dead letter after MAX_ATTEMPTS (8ms)
+  pollDueRetries
+    ✓ returns only due jobs (5ms)
+  removeFromQueue
+    ✓ removes target job only (4ms)
+```
+
+All passing.

package/fixtures/classifier-gold/transcripts/05-feature-csv-export.txt

@@ -0,0 +1,86 @@
+User: lumens needs a CSV export endpoint. Users want to download their usage report as a CSV. The report query already exists in src/reports/usage.go and returns a slice of UsageRow structs. I want to add GET /reports/export?format=csv.
+
+Agent: [Read: src/reports/usage.go]
+
+```go
+type UsageRow struct {
+    Date     string
+    Metric   string
+    Value    float64
+    Unit     string
+}
+
+func QueryUsage(ctx context.Context, db *sql.DB, accountID string, from, to time.Time) ([]UsageRow, error) {
+    // ... query implementation
+}
+```
+
+[Read: src/api/routes.go]
+
+I see the existing route structure. I'll add the export handler. The question is whether to buffer the rows in memory and send them all at once, or stream directly. For large reports this matters.
+
+How large can these reports get? Hundreds of rows, or could it be tens of thousands?
+
+User: Reports can be up to 100k rows for heavy users. Stream directly, don't buffer.
+
+Agent: In that case I'll write directly to the http.ResponseWriter using encoding/csv rather than building a string in memory. I'll also set the Content-Disposition header so browsers download the file rather than display it.
+
+[Edit: src/api/export_handler.go] (new file)
+
+```go
+package api
+
+import (
+    "encoding/csv"
+    "fmt"
+    "net/http"
+    "time"
+
+    "lumens/reports"
+)
+
+func (s *Server) handleCSVExport(w http.ResponseWriter, r *http.Request) {
+    accountID := r.Context().Value(ctxKeyAccountID).(string)
+    from, to, err := parseDateRange(r)
+    if err != nil {
+        http.Error(w, "invalid date range", http.StatusBadRequest)
+        return
+    }
+    rows, err := reports.QueryUsage(r.Context(), s.db, accountID, from, to)
+    if err != nil {
+        http.Error(w, "query failed", http.StatusInternalServerError)
+        return
+    }
+    filename := fmt.Sprintf("usage-%s.csv", time.Now().Format("2006-01-02"))
+    w.Header().Set("Content-Type", "text/csv")
+    w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, filename))
+    cw := csv.NewWriter(w)
+    _ = cw.Write([]string{"Date", "Metric", "Value", "Unit"})
+    for _, row := range rows {
+        _ = cw.Write([]string{row.Date, row.Metric, fmt.Sprintf("%.4f", row.Value), row.Unit})
+    }
+    cw.Flush()
+}
+```
+
+[Edit: src/api/routes.go]
+
+Added `GET /reports/export` route pointing to handleCSVExport.
+
+User: Should I add this to the OpenAPI spec?
+
+Agent: Yes. [Read: api/openapi.yaml]
+
+[Edit: api/openapi.yaml]
+
+Added the /reports/export path with GET, query params `from`, `to`, and the `format` param (currently only `csv` accepted), response schema as text/csv with the Content-Disposition header documented.
+
+User: Run the existing API tests to make sure nothing broke.
+
+Agent: [Bash: go test ./src/api/...]
+
+```
+ok      lumens/src/api   1.243s
+```
+
+All passing. The export handler streams rows directly to the response writer without buffering in memory.

package/fixtures/classifier-gold/transcripts/06-feature-rate-limiting.txt

@@ -0,0 +1,61 @@
+User: crestapi needs API rate limiting. We're getting abuse from a handful of API keys hammering the search endpoint. I want per-API-key rate limiting: 100 requests per minute, returning 429 with a Retry-After header when exceeded.
+
+Agent: The standard approach for FastAPI is slowapi, which wraps limits.py and integrates as middleware. It supports Redis as the backing store so limits are shared across multiple crestapi workers. Let me check what's already in requirements.txt and whether Redis is already a dependency.
+
+[Bash: grep -E "redis|slowapi|limits" requirements.txt]
+
+```
+redis==5.0.4
+```
+
+Redis is there. slowapi is not yet installed. I'll add it.
+
+User: Go ahead and add slowapi.
+
+Agent: [Edit: requirements.txt]
+
+Added `slowapi==0.1.9`.
+
+[Read: src/main.py]
+
+[Edit: src/main.py]
+
+```python
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+from slowapi.middleware import SlowAPIMiddleware
+
+def get_api_key(request: Request) -> str:
+    return request.headers.get("X-API-Key", get_remote_address(request))
+
+limiter = Limiter(key_func=get_api_key, storage_uri=settings.REDIS_URL)
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+app.add_middleware(SlowAPIMiddleware)
+```
+
+[Read: src/routes/search.py]
+
+[Edit: src/routes/search.py]
+
+Added the `@limiter.limit("100/minute")` decorator to the search endpoint handler.
+
+User: Will the 429 response include a Retry-After header?
+
+Agent: slowapi's built-in _rate_limit_exceeded_handler sets the Retry-After header automatically based on the window reset time. You don't need to add it manually.
+
+User: Good. What happens to unauthenticated requests with no API key header?
+
+Agent: The `get_api_key` function falls back to `get_remote_address`, which returns the client IP. So unauthenticated clients are rate-limited by IP at the same 100 req/min threshold. If you want a stricter limit for unauthenticated access you'd need a separate decorator with a lower limit on those routes.
+
+User: Keep it the same limit for now. Run the tests.
+
+Agent: [Bash: pip install -r requirements.txt -q && pytest tests/ -q]
+
+```
+...................................
+35 passed in 2.14s
+```
+
+All passing. slowapi with Redis backing installed and wired to the search endpoint.

package/fixtures/classifier-gold/transcripts/07-refactor-db-abstraction.txt

@@ -0,0 +1,72 @@
+User: In vaultdb I want to refactor the database layer so we can swap between Postgres and SQLite for tests without touching core logic. Right now the core modules import from src/adapters/postgres.ts directly.
+
+Agent: [Bash: grep -rn "from.*postgres" src/core/]
+
+```
+src/core/session-store.ts:3: import { pgPool } from "../adapters/postgres.js";
+src/core/fact-store.ts:2: import { pgPool } from "../adapters/postgres.js";
+src/core/search.ts:5: import { pgPool } from "../adapters/postgres.js";
+```
+
+Three core modules import Postgres directly. The fix is to define a DbAdapter interface in the ports layer and have the core modules depend on that interface rather than the concrete Postgres adapter. The Postgres and SQLite implementations both implement the interface.
+
+User: Yes. Let's extract the interface to src/ports/db-adapter.ts.
+
+Agent: I'll first enumerate what operations the core modules actually call on pgPool, then define only those in the interface.
+
+[Read: src/core/session-store.ts]
+[Read: src/core/fact-store.ts]
+[Read: src/core/search.ts]
+
+Operations used: `query(sql, params)` returning rows, `transaction(fn)` for multi-statement writes. That's it.
+
+[Write: src/ports/db-adapter.ts]
+
+```typescript
+export interface QueryResult<T = Record<string, unknown>> {
+  readonly rows: ReadonlyArray<T>;
+}
+
+export interface DbAdapter {
+  query<T = Record<string, unknown>>(
+    sql: string,
+    params?: ReadonlyArray<unknown>,
+  ): Promise<QueryResult<T>>;
+  transaction<T>(fn: (db: DbAdapter) => Promise<T>): Promise<T>;
+}
+```
+
+[Edit: src/adapters/postgres.ts]
+
+Implemented DbAdapter on the existing PgAdapter class. Added `transaction()` using `BEGIN` / `COMMIT` / `ROLLBACK` calls.
+
+[Write: src/adapters/sqlite.ts]
+
+New SQLite adapter implementing DbAdapter for use in tests using better-sqlite3.
+
+[Edit: src/core/session-store.ts]
+[Edit: src/core/fact-store.ts]
+[Edit: src/core/search.ts]
+
+Replaced `import { pgPool }` with `import type { DbAdapter } from "../ports/db-adapter.js"` in each. Each module now receives the adapter through its constructor or init function rather than importing it directly.
+
+User: Where do we wire the concrete adapter?
+
+Agent: In src/app.ts, which is the composition root. That's the only place that imports PgAdapter. In tests, SqliteAdapter is passed instead.
+
+User: Can you verify no core module imports from adapters directly after this refactor?
+
+Agent: [Bash: grep -rn "from.*adapters" src/core/]
+
+No output. Core is clean.
+
+User: Good. Run the full test suite.
+
+Agent: [Bash: npm test]
+
+```
+Test Suites: 8 passed, 8 total
+Tests:       61 passed, 61 total
+```
+
+All green. The DbAdapter interface is in the ports layer; SQL stays in adapters, not in core.

package/fixtures/classifier-gold/transcripts/08-refactor-config-loading.txt

@@ -0,0 +1,89 @@
+User: axiom-worker has config scattered across the codebase. I want to centralize it into a single Pydantic Settings class loaded once at startup. Can you audit how config is currently read?
+
+Agent: [Bash: grep -rn "os.getenv\|os.environ" src/ --include="*.py"]
+
+```
+src/worker/processor.py:14: DB_URL = os.getenv("DATABASE_URL", "")
+src/worker/processor.py:31: BATCH_SIZE = int(os.getenv("BATCH_SIZE", "50"))
+src/jobs/runner.py:8:  QUEUE_URL = os.environ["QUEUE_URL"]
+src/jobs/runner.py:9:  RETRY_LIMIT = int(os.environ.get("RETRY_LIMIT", "3"))
+src/notifier/slack.py:3: SLACK_WEBHOOK = os.environ["SLACK_WEBHOOK_URL"]
+src/health/check.py:22: PORT = int(os.getenv("PORT", "8080"))
+```
+
+Six separate call sites across four files. Some use `os.getenv` with defaults, some use `os.environ` which raises on missing keys. Inconsistent.
+
+User: Consolidate these into a Pydantic Settings class.
+
+Agent: [Write: src/config.py]
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    database_url: str
+    queue_url: str
+    slack_webhook_url: str
+    batch_size: int = 50
+    retry_limit: int = 3
+    port: int = 8080
+
+settings = Settings()
+```
+
+`database_url`, `queue_url`, and `slack_webhook_url` have no default, so startup fails fast with a clear Pydantic ValidationError if they are missing rather than silently proceeding with an empty string.
+
+[Edit: src/worker/processor.py]
+[Edit: src/jobs/runner.py]
+[Edit: src/notifier/slack.py]
+[Edit: src/health/check.py]
+
+Replaced all `os.getenv`/`os.environ` calls with imports from `src/config.py`.
+
+User: Is pydantic-settings already a dependency?
+
+Agent: [Bash: grep "pydantic" requirements.txt]
+
+```
+pydantic==2.7.1
+```
+
+pydantic-settings is a separate package. I'll add it.
+
+[Edit: requirements.txt]
+
+Added `pydantic-settings==2.3.4`.
+
+User: Any tests need updating?
+
+Agent: [Bash: grep -rn "os.environ\|os.getenv\|monkeypatch.setenv" tests/ --include="*.py"]
+
+```
+tests/test_processor.py:12: monkeypatch.setenv("DATABASE_URL", "sqlite:///:memory:")
+tests/test_processor.py:13: monkeypatch.setenv("BATCH_SIZE", "5")
+tests/test_runner.py:9:  monkeypatch.setenv("QUEUE_URL", "amqp://localhost")
+```
+
+These tests set env vars which Pydantic Settings will pick up automatically since it reads from the environment. However, the Settings object is a module-level singleton in config.py, so it is initialized once at import time before `monkeypatch.setenv` runs.
+
+The fix is to move Settings instantiation to a function and call it inside each module that needs it, or to use pydantic-settings' `_env_file` override per test. The simpler fix for tests: patch `src.config.settings` directly.
+
+I'll update the tests to patch the singleton.
+
+[Edit: tests/test_processor.py]
+[Edit: tests/test_runner.py]
+
+User: Run the tests.
+
+Agent: [Bash: pip install pydantic-settings==2.3.4 -q && pytest tests/ -v]
+
+```
+tests/test_processor.py::test_batch_size_respected PASSED
+tests/test_runner.py::test_retry_on_failure PASSED
+tests/test_health_check.py::test_port_default PASSED
+5 passed in 1.87s
+```
+
+All green. Config is now centralized in a single Pydantic Settings class loaded at startup.

package/fixtures/classifier-gold/transcripts/09-ops-docker-staging.txt

@@ -0,0 +1,94 @@
+User: droneflow needs a staging environment that mirrors production. Right now we only have a docker-compose.yml for local dev. I want a separate staging compose file with Traefik as the router and real Postgres instead of the local volume.
+
+Agent: [Read: docker-compose.yml]
+
+```yaml
+services:
+  api:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      DATABASE_URL: postgres://dev:dev@db:5432/droneflow
+  db:
+    image: postgres:16
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+```
+
+For staging I'll create docker-compose.staging.yml that:
+- Removes the direct port binding (Traefik will handle routing)
+- Adds Traefik as a router service with Let's Encrypt TLS
+- Points DATABASE_URL at an external Postgres instance (staging.db.example.com)
+- Adds explicit labels so Traefik routes api.staging.example.com to the api service
+
+User: The staging database is already provisioned at staging.db.example.com. Use that.
+
+Agent: [Write: docker-compose.staging.yml]
+
+```yaml
+services:
+  traefik:
+    image: traefik:v3.1
+    command:
+      - --providers.docker=true
+      - --providers.docker.exposedbydefault=false
+      - --entrypoints.web.address=:80
+      - --entrypoints.websecure.address=:443
+      - --certificatesresolvers.letsencrypt.acme.email=ops@example.com
+      - --certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json
+      - --certificatesresolvers.letsencrypt.acme.tlschallenge=true
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - letsencrypt:/letsencrypt
+
+  api:
+    build: .
+    environment:
+      DATABASE_URL: postgres://app:${STAGING_DB_PASSWORD}@staging.db.example.com:5432/droneflow_staging
+      NODE_ENV: staging
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.api.rule=Host(`api.staging.example.com`)
+      - traefik.http.routers.api.entrypoints=websecure
+      - traefik.http.routers.api.tls.certresolver=letsencrypt
+
+volumes:
+  letsencrypt:
+```
+
+User: Should the staging environment auto-pull new images on deploy?
+
+Agent: Not with compose alone. For that you'd need Watchtower or a deploy hook. The typical pattern is to keep deploy explicit: SSH to the staging host and run `docker compose -f docker-compose.staging.yml pull && docker compose -f docker-compose.staging.yml up -d`. That way staging only updates when you intentionally trigger a deploy, not on every push.
+
+User: Let's keep it explicit for now. Add a deploy script.
+
+Agent: [Write: scripts/deploy-staging.sh]
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+HOST="${STAGING_HOST:-staging.example.com}"
+ssh "deploy@${HOST}" '
+  cd /opt/droneflow
+  docker compose -f docker-compose.staging.yml pull
+  docker compose -f docker-compose.staging.yml up -d --remove-orphans
+'
+```
+
+User: Good. Any concerns about the current setup?
+
+Agent: One: the `STAGING_DB_PASSWORD` must be set in the environment on the staging host before starting the stack. If it's missing, Docker Compose substitutes an empty string and Postgres connection will fail at startup rather than at config validation time. Consider adding a `.env.staging.example` file documenting required variables.
+
+User: Good call. Add that.
+
+Agent: [Write: .env.staging.example]
+
+```
+STAGING_DB_PASSWORD=changeme
+```
+
+Setup complete. Traefik routes api.staging.example.com with TLS; deploy is explicit via the deploy script.

package/fixtures/classifier-gold/transcripts/10-ops-nginx-ssl.txt

@@ -0,0 +1,121 @@
+User: I need to set up nginx as a reverse proxy for gridhost with TLS from Let's Encrypt. The app is running on port 8080 on the same machine. Domain is gridhost.example.com.
+
+Agent: [Bash: nginx -v]
+
+```
+nginx version: nginx/1.24.0
+```
+
+[Bash: which certbot]
+
+```
+/usr/bin/certbot
+```
+
+Both are present. Let me check what's currently in /etc/nginx/sites-available/.
+
+[Bash: ls /etc/nginx/sites-available/]
+
+```
+default
+```
+
+Only the default site. I'll create a new config for gridhost.example.com, get the certificate, then update the config to use it.
+
+First, the initial HTTP-only config for the ACME challenge:
+
+[Write: /etc/nginx/sites-available/gridhost]
+
+```nginx
+server {
+    listen 80;
+    server_name gridhost.example.com;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+```
+
+[Bash: ln -s /etc/nginx/sites-available/gridhost /etc/nginx/sites-enabled/gridhost]
+[Bash: nginx -t]
+
+```
+nginx: configuration file /etc/nginx/nginx.conf test is successful
+```
+
+[Bash: systemctl reload nginx]
+
+[Bash: certbot certonly --webroot -w /var/www/certbot -d gridhost.example.com --non-interactive --agree-tos -m ops@example.com]
+
+```
+Successfully received certificate.
+Certificate is saved at: /etc/letsencrypt/live/gridhost.example.com/fullchain.pem
+Key is saved at:         /etc/letsencrypt/live/gridhost.example.com/privkey.pem
+```
+
+Now updating the config to add TLS and the proxy:
+
+[Edit: /etc/nginx/sites-available/gridhost]
+
+```nginx
+server {
+    listen 80;
+    server_name gridhost.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    server_name gridhost.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/gridhost.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/gridhost.example.com/privkey.pem;
+
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers on;
+
+    location / {
+        proxy_pass         http://127.0.0.1:8080;
+        proxy_set_header   Host $host;
+        proxy_set_header   X-Real-IP $remote_addr;
+        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+[Bash: nginx -t && systemctl reload nginx]
+
+```
+nginx: configuration file /etc/nginx/nginx.conf test is successful
+```
+
+User: Does Let's Encrypt auto-renew?
+
+Agent: certbot installs a systemd timer or cron job during installation that runs `certbot renew` twice daily. Renewal happens automatically when the certificate is within 30 days of expiry. To confirm it's active:
+
+[Bash: systemctl status certbot.timer]
+
+```
+Active: active (waiting)
+Trigger: Fri 2026-06-05 12:00:00 UTC
+```
+
+Active. You don't need to do anything manual for renewal.
+
+User: Add a cron fallback in case the timer is disabled.
+
+Agent: [Bash: crontab -l]
+
+No existing crontab. Adding:
+
+[Bash: (crontab -l 2>/dev/null; echo "0 3 * * * certbot renew --quiet --post-hook 'systemctl reload nginx'") | crontab -]
+
+Runs at 3am daily; the post-hook reloads nginx after a successful renewal so the new certificate is served without a restart.
+
+User: Perfect. TLS is live.