Integration Guide

You are integrating Kindred Tracer into my Node.js codebase with a safe default setup.

Auto-discovery requirements (do this first, do not ask me unless blocked):
1. Detect framework/runtime by scanning dependencies and startup code.
2. Detect package manager from lock/config files (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`).
3. Detect true entrypoints by checking scripts (`package.json`), process bootstrap files, and deployment manifests.
4. Detect runtime style (long-running server, serverless, worker, CLI) from code and infra files.
5. Detect existing shutdown hooks and lifecycle handlers.
6. Propose target files to edit and then apply changes directly.

Tasks:
1. Install `kindred-tracer-node`.
2. Identify the real process bootstrap file and initialize tracing exactly once at startup.
3. In your output, explicitly explain:
   - WHERE you added initialization (exact file + section)
   - WHY that section is correct (earliest startup, singleton init, max request coverage)
4. If layout is nonstandard (monorepo/serverless/multi-worker), choose the best per-entrypoint placement and explain fallback logic.
5. Ensure required env vars are documented and wired:
   - KINDRED_API_KEY (required)
   - KINDRED_API_URL (optional, default https://api.usekindred.dev)
   - KINDRED_SESSION_ID / KINDRED_AGENT_ID / KINDRED_RUN_ID (optional)
6. Add graceful shutdown flushing with `await flushLogs()` in existing signal/shutdown handlers.
7. Do not wrap each LLM call manually; tracer is auto-instrumentation.
8. Show me:
   - Auto-detected project profile (framework, package manager, entrypoint(s), runtime style)
   - Files changed
   - Exact code diff
   - How to run and verify logs are sent

Constraints:
- Keep changes minimal and production-safe.
- Integrate into existing startup/bootstrap logic, do not create parallel startup paths.
- Preserve existing logging behavior.

Placement examples (follow pattern, adapt to actual code):
- Express/Fastify: initialize in `server.ts` right after env/config load and before route handlers or first outbound calls.
- NestJS: initialize in `main.ts` before `NestFactory.create(...)` or immediately after, but before app starts processing requests.
- Serverless handler: initialize in module scope (outside handler) to patch once per warm runtime.
- Worker/queue process: initialize in worker bootstrap file before job loop starts.
- Heuristics for discovery:
  - Read `package.json` scripts like `start`, `dev`, `serve`, `worker`.
  - Inspect framework signatures (`express()`, `NestFactory.create`, `fastify()`, queue worker constructors).
  - Inspect deployment files (`Dockerfile`, Procfile, serverless config, platform manifests).

Library Context (Node, authoritative):
- Import/API:
  - import { kindredTracer, flushLogs } from "kindred-tracer-node"
  - kindredTracer(sessionId?: string, agentId?: string, runId?: string): void
  - flushLogs(): Promise<void>
- Setup rules:
  - Call once at startup.
  - sessionId/agentId/runId use function args first, then env; sessionId auto-generates UUID if missing.
  - Auto-instruments by patching Node http/https request paths.
- Export/env:
  - KINDRED_API_KEY required for export.
  - KINDRED_API_URL default is https://api.usekindred.dev.
  - Logs sent to ${KINDRED_API_URL}/api/logs/ingest with Bearer auth.
  - Sensitive headers removed before logging: Authorization, x-api-key, api-key, x-auth-token, cookie.
- Role mapping:
  - Known LLM hosts => role "agent"; other hosts => role "tool".
  - Known hosts: api.openai.com, api.anthropic.com, generativelanguage.googleapis.com, api.cohere.com, api.mistral.ai

You are retrofitting Kindred Tracer into an existing Node.js codebase with current observability already in place.

Codebase context:
Auto-discovery requirements (do this before patching):
1. Infer stack/framework from dependency graph and startup code.
2. Detect all runnable process types (api server, workers, cron, serverless handlers).
3. Identify startup files per process by tracing script commands to source files.
4. Detect existing telemetry stack and shutdown/lifecycle hooks.
5. Produce a short "detected architecture map" before editing, then patch.

What to do:
1. Trace startup flow and identify the single earliest safe initialization point per process type.
2. Add `kindredTracer(...)` with minimal code changes.
3. For each modified file, explicitly explain:
   - WHERE tracer was inserted
   - WHY this is the correct section for one-time patching and full request coverage
4. Reuse existing lifecycle hooks to `await flushLogs()` on shutdown.
5. Preserve existing logs/spans and avoid duplicate initialization.
6. Provide:
   - detected architecture map
   - migration summary
   - file-by-file diff
   - rollback steps
   - validation checklist

Placement examples (adapt to real structure):
- Monorepo: apply in each runnable package entrypoint, not shared utility modules.
- Next custom server: initialize in custom `server.ts` startup, not per route file.
- BullMQ/worker: initialize in worker bootstrap before processor registration.
- AWS Lambda: initialize once in module scope; avoid inside handler body.

Library Context (Node, authoritative):
- import { kindredTracer, flushLogs } from "kindred-tracer-node"
- kindredTracer(sessionId?: string, agentId?: string, runId?: string)
- flushLogs(): Promise<void>
- Auto patches http/https request calls once initialized.
- Requires KINDRED_API_KEY to export logs; endpoint is ${KINDRED_API_URL}/api/logs/ingest (default base URL https://api.usekindred.dev).
- Env IDs supported: KINDRED_SESSION_ID, KINDRED_AGENT_ID, KINDRED_RUN_ID.
- Sensitive headers are sanitized before send.

You are integrating Kindred Tracer into my Python codebase with a safe default setup.

Project inputs:
Auto-discovery requirements (do this first, do not ask me unless blocked):
1. Detect Python framework/runtime from imports and dependency files.
2. Detect dependency manager from project files (`pyproject.toml`, `requirements.txt`, `Pipfile`, `poetry.lock`, `uv.lock`).
3. Detect true entrypoints by checking launch commands, framework conventions, and worker boot files.
4. Detect runtime style (sync, async, serverless, worker) from app/server startup code.
5. Detect existing shutdown hooks/signals and process lifecycle handlers.
6. Propose target files and apply minimal patch set.

What to do:
1. Install `kindred-tracer`.
2. Identify the real bootstrap file and initialize `kindred_tracer()` exactly once at startup.
3. Explicitly explain:
   - WHERE initialization was inserted
   - WHY that section is correct (startup order, single patching pass, full HTTP coverage)
4. Support nonstandard layouts (monorepo, multiple workers, serverless) by selecting per-process bootstrap points.
5. Wire env vars:
   - KINDRED_API_KEY (required)
   - KINDRED_API_URL (optional, default https://api.usekindred.dev)
   - KINDRED_SESSION_ID / KINDRED_AGENT_ID / KINDRED_RUN_ID (optional)
   - KINDRED_LLM_HOSTS (optional extra LLM domains)
6. Add graceful shutdown `flush()` in existing lifecycle handlers.
7. Show files changed, exact diff, and verification commands.
8. Include an "auto-detected project profile" summary before listing edits.

Placement examples (follow pattern, adapt to actual code):
- FastAPI/Uvicorn: initialize in `main.py` before app starts serving.
- Flask/Gunicorn: initialize in app factory module at import/startup boundary.
- Django: initialize in startup path (for example app config ready hook or process bootstrap) once per process.
- Celery worker: initialize in worker bootstrap before task execution loop.
- Async scripts: initialize before creating API clients and before first await that issues HTTP calls.
- Heuristics for discovery:
  - inspect dependency files and imports for `fastapi`, `flask`, `django`, `celery`, `uvicorn`, `gunicorn`
  - inspect run commands (`python ...`, `uvicorn module:app`, `celery -A ... worker`)
  - inspect infra files (`Dockerfile`, Procfile, task runner configs, serverless config)

Library Context (Python, authoritative):
- from kindred_tracer import kindred_tracer, flush
- kindred_tracer(session_id: str | None = None, agent_id: str | None = None, run_id: str | None = None) -> None
- flush() -> None
- Setup rules:
  - Call once at startup to set global context.
  - IDs use function args first, then env; session_id auto-generates if absent.
  - Auto patches httpx.Client.request and httpx.AsyncClient.request; also patches requests.Session.request when installed.
- Export/env:
  - KINDRED_API_KEY required for export.
  - KINDRED_API_URL default is https://api.usekindred.dev.
  - Sends to ${KINDRED_API_URL}/api/logs/ingest with Bearer auth.
- Host classification:
  - Known LLM hosts: api.openai.com, api.anthropic.com, generativelanguage.googleapis.com, api.cohere.com, api.mistral.ai
  - Extra LLM hosts can be appended via KINDRED_LLM_HOSTS (comma separated).

You are retrofitting Kindred Tracer into an existing Python codebase with current observability already in place.

Codebase context:
Auto-discovery requirements (do this before patching):
1. Infer framework/runtime and process topology from dependency and startup files.
2. Detect all process entrypoints (web server, workers, schedulers, jobs, serverless handlers).
3. Detect existing observability integrations and shutdown hooks.
4. Create a concise architecture map with chosen insertion points and rationale, then patch.

What to do:
1. Map process boot sequence and choose one initialization point per process type.
2. Insert `kindred_tracer(...)` with minimal changes.
3. For each insertion, explicitly state:
   - WHERE it was placed (file + section)
   - WHY this location is correct (first startup phase, singleton patching, broad coverage)
4. Add `flush()` to existing shutdown handlers where possible.
5. Avoid replacing existing telemetry and avoid duplicate initialization paths.
6. Return:
   - detected architecture map
   - migration summary
   - file-by-file diff
   - rollback steps
   - smoke test/verification checklist

Placement examples (adapt to real structure):
- Django + gunicorn: initialize in process startup path, not inside view functions.
- FastAPI app: initialize in startup bootstrap module before first outbound API call.
- Celery: initialize in worker startup module before tasks run.
- Multi-service repo: apply separately in each service entrypoint that makes outbound HTTP calls.
- AWS Lambda: initialize in module scope once per warm runtime.

Library Context (Python, authoritative):
- from kindred_tracer import kindred_tracer, flush
- kindred_tracer(session_id=None, agent_id=None, run_id=None)
- flush()
- Tracer auto-instruments outbound HTTP at client layer (httpx + optional requests patch).
- Export requires KINDRED_API_KEY and uses ${KINDRED_API_URL}/api/logs/ingest (default base https://api.usekindred.dev).
- Env IDs: KINDRED_SESSION_ID, KINDRED_AGENT_ID, KINDRED_RUN_ID.
- Optional host override: KINDRED_LLM_HOSTS.