From c044298fdf95d80600c9b8af0b2c97a60d4fa348 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 6 Mar 2026 21:57:42 +0000 Subject: [PATCH] docs: add separate OpenAI, Anyway, and Traceloop guides --- docs/opencto/ANYWAY_IMPLEMENTATION_GUIDE.md | 117 ++++++++++++++++++ docs/opencto/OPENAI_IMPLEMENTATION_GUIDE.md | 103 +++++++++++++++ docs/opencto/README.md | 3 + .../opencto/TRACELOOP_IMPLEMENTATION_GUIDE.md | 106 ++++++++++++++++ 4 files changed, 329 insertions(+) create mode 100644 docs/opencto/ANYWAY_IMPLEMENTATION_GUIDE.md create mode 100644 docs/opencto/OPENAI_IMPLEMENTATION_GUIDE.md create mode 100644 docs/opencto/TRACELOOP_IMPLEMENTATION_GUIDE.md diff --git a/docs/opencto/ANYWAY_IMPLEMENTATION_GUIDE.md b/docs/opencto/ANYWAY_IMPLEMENTATION_GUIDE.md new file mode 100644 index 0000000..4834e3c --- /dev/null +++ b/docs/opencto/ANYWAY_IMPLEMENTATION_GUIDE.md @@ -0,0 +1,117 @@ +# Anyway Implementation Guide + +Version: v1.0 +Date: March 6, 2026 +Scope: OpenCTO Anyway tracing integration only + +## Purpose + +This guide documents the current Anyway integration in OpenCTO and how to operate it safely. + +## Current State + +Anyway tracing is implemented in the cloudbot worker only. + +- Worker: `opencto/opencto-cloudbot-worker` +- Core file: `opencto/opencto-cloudbot-worker/src/index.ts` +- Pattern: fail-open trace buffer that never blocks user responses + +No Anyway integration is currently wired into: + +- `opencto/opencto-api-worker` +- `opencto/opencto-dashboard` +- `opencto/mobile-app` +- `opencto/cto-orchestrator` + +## Architecture + +```text +Webhook Event (Telegram/Slack/Infobip) + | + v + OpenCTO CloudBot Worker + - span buffer per request + - flush at request completion + | + v + Anyway ingest endpoint +``` + +## Implementation Details + +### Enablement Gate + +Tracing is enabled only when both are true: + +1. `OPENCTO_ANYWAY_ENABLED=true` +2. `OPENCTO_ANYWAY_API_KEY` is configured + +Code location: + +- `anywayEnabled(env)` in `opencto/opencto-cloudbot-worker/src/index.ts` + +### Trace Buffer + +`AnywayTraceBuffer` handles: + +- trace ID generation +- span start/end with status and attributes +- batched flush to ingest endpoint + +Default ingest endpoint: + +- `https://api.anyway.sh/v1/ingest` + +Request payload shape: + +- `{ traces: [{ trace_id, spans }], metrics: [] }` + +### Instrumented Workflow Segments + +Cloudbot spans are created around: + +- Telegram webhook handling +- Slack webhook handling +- Infobip webhook handling +- lexical and semantic memory retrieval +- OpenAI response generation + +## Environment Variables + +| Variable | Purpose | +| --- | --- | +| `OPENCTO_ANYWAY_ENABLED` | Global enable flag (`true`/`false`) | +| `OPENCTO_ANYWAY_API_KEY` | Bearer token for ingest auth | +| `OPENCTO_ANYWAY_ENDPOINT` | Optional custom ingest URL override | + +## Deployment Runbook + +1. Set secrets: + +```bash +wrangler secret put OPENCTO_ANYWAY_API_KEY +``` + +2. Set vars in `wrangler.toml`: + +```toml +OPENCTO_ANYWAY_ENABLED = "true" +OPENCTO_ANYWAY_ENDPOINT = "https://api.anyway.sh/v1/ingest" +``` + +3. Deploy worker: + +```bash +wrangler deploy +``` + +4. Verify: +- `GET /health` confirms worker is up. +- Trigger a webhook event. +- Confirm traces arrive in Anyway. + +## Operational Notes + +- Integration is explicitly fail-open; telemetry failures are swallowed by design. +- Do not place user secrets in span attributes. +- Treat phone numbers and user IDs as sensitive identifiers; hash/redact where possible before adding new attributes. diff --git a/docs/opencto/OPENAI_IMPLEMENTATION_GUIDE.md b/docs/opencto/OPENAI_IMPLEMENTATION_GUIDE.md new file mode 100644 index 0000000..99ece29 --- /dev/null +++ b/docs/opencto/OPENAI_IMPLEMENTATION_GUIDE.md @@ -0,0 +1,103 @@ +# OpenAI Implementation Guide + +Version: v1.0 +Date: March 6, 2026 +Scope: OpenCTO OpenAI integrations only + +## Purpose + +This guide documents how OpenCTO currently uses OpenAI across product surfaces and background services. + +## Where OpenAI Is Used + +1. Realtime voice assistant sessions (dashboard + mobile via API Worker token minting). +2. OpenAI operational proxy endpoints (`models`, `usage`) for tool-driven platform observability. +3. Incident/autonomy workflows in orchestrator. +4. Multi-channel cloudbot responses and embeddings. +5. Voice backend chat completion endpoint. + +## Architecture + +```text +Client (Dashboard/Mobile/SDK) + | + v +OpenCTO API Worker +- POST /api/v1/realtime/token +- GET /api/v1/cto/openai/models +- GET /api/v1/cto/openai/usage + | + v +OpenAI API +``` + +## Core Implementation Points + +### Realtime Token Minting + +- Endpoint: `POST /api/v1/realtime/token` +- File: `opencto/opencto-api-worker/src/index.ts` +- Behavior: + - resolves key by workspace/user via BYOK (`provider=openai`) or `OPENAI_API_KEY` fallback + - calls `https://api.openai.com/v1/realtime/client_secrets` + - returns ephemeral `clientSecret` to browser/mobile + +### Realtime Session Client + +- Files: + - `opencto/opencto-dashboard/src/lib/realtime/openaiAdapter.ts` + - `opencto/mobile-app/src/api/realtime.ts` +- Behavior: + - connects to `wss://api.openai.com/v1/realtime?model=` + - uses subprotocol auth: `openai-insecure-api-key.` + - streams PCM audio, receives transcript/audio deltas + - executes function tools via backend proxy routes + +### OpenAI Proxy Endpoints + +- Routes: + - `GET /api/v1/cto/openai/models` + - `GET /api/v1/cto/openai/usage?start=&end=` +- File: `opencto/opencto-api-worker/src/index.ts` (`proxyOpenAI`) +- Used by dashboard tool execution in `opencto/opencto-dashboard/src/lib/realtime/shared.ts` + +### BYOK Key Management + +- File: `opencto/opencto-api-worker/src/providerKeys.ts` +- Routes: + - `GET /api/v1/llm/keys` + - `PUT /api/v1/llm/keys/openai` + - `DELETE /api/v1/llm/keys/openai` +- Security: + - AES-GCM at-rest encryption + - per user + workspace + provider key scope + - only masked hints are returned + +## Environment Variables + +| Area | Variables | +| --- | --- | +| API Worker | `OPENAI_API_KEY`, `RATE_LIMIT_REALTIME_PER_MINUTE`, `RATE_LIMIT_CTO_OPENAI_PER_MINUTE` | +| Voice backend | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | +| Orchestrator | `OPENAI_API_KEY`, `OPENCTO_OPENAI_MODEL`, `OPENCTO_AGENT_MODEL` | +| Cloudbot worker | `OPENAI_API_KEY`, `OPENCTO_AGENT_MODEL`, `OPENCTO_EMBED_MODEL` | + +## Operational Runbook + +1. Set `OPENAI_API_KEY` in API Worker (`wrangler secret put OPENAI_API_KEY`). +2. For multi-tenant setups, save per-workspace key via `PUT /api/v1/llm/keys/openai`. +3. Validate realtime path: + - call `/api/v1/realtime/token` + - confirm non-empty `clientSecret` +4. Validate ops path: + - call `/api/v1/cto/openai/models` + - call `/api/v1/cto/openai/usage` +5. Monitor 429 and 5xx rates on: + - `realtime_token` + - `cto_openai_proxy` + +## References (Chicago 17B) + +OpenAI. “Realtime API.” *OpenAI API Documentation*. Accessed March 6, 2026. https://developers.openai.com/api/docs/guides/realtime. + +OpenAI. “Text Generation.” *OpenAI API Documentation*. Accessed March 6, 2026. https://developers.openai.com/api/docs/guides/text. diff --git a/docs/opencto/README.md b/docs/opencto/README.md index 3f45d0b..6aeafc5 100644 --- a/docs/opencto/README.md +++ b/docs/opencto/README.md @@ -7,6 +7,9 @@ This folder is the working documentation source for the OpenCTO platform build-o - `OPENCTO_PLATFORM_SPEC.md`: Platform architecture and engineering spec (v0.3 baseline). - `OPENCTO_FRONTEND_BRAND_MONETISATION_SPEC.md`: Frontend, brand, domain, and monetisation spec (v0.4 baseline). - `IMPLEMENTATION_ROADMAP.md`: Practical phased delivery plan mapped to current repository state. +- `OPENAI_IMPLEMENTATION_GUIDE.md`: OpenAI-only implementation map, env setup, and runbook. +- `ANYWAY_IMPLEMENTATION_GUIDE.md`: Anyway-only tracing implementation guide for cloudbot workflows. +- `TRACELOOP_IMPLEMENTATION_GUIDE.md`: Traceloop-only rollout and instrumentation guide. - `OPENAI_CLOUDFLARE_TRACELOOP_IMPLEMENTATION_GUIDE.md`: Task-based implementation guide for OpenAI, Cloudflare, and Traceloop workflows. - `UI_REUSE_LEMAAI.md`: UI reuse strategy for `chilu18/LemaAI` and migration into OpenCTO. - `WORK_SPLIT_MULTI_TERMINAL.md`: Multi-terminal and multi-agent execution split (Codex, Claude, OpenClaw). diff --git a/docs/opencto/TRACELOOP_IMPLEMENTATION_GUIDE.md b/docs/opencto/TRACELOOP_IMPLEMENTATION_GUIDE.md new file mode 100644 index 0000000..95ee083 --- /dev/null +++ b/docs/opencto/TRACELOOP_IMPLEMENTATION_GUIDE.md @@ -0,0 +1,106 @@ +# Traceloop Implementation Guide + +Version: v1.0 +Date: March 6, 2026 +Scope: OpenCTO Traceloop strategy and rollout + +## Purpose + +This guide defines how to implement Traceloop in OpenCTO. As of this date, there is no direct Traceloop integration in the repository. + +## Current State + +- No `traceloop` package/config usage found in OpenCTO product surfaces. +- Existing telemetry patterns are: + - custom trace context headers in legacy SDK paths + - Anyway tracing in cloudbot worker + +This means Traceloop should be introduced as a new telemetry layer, not as an in-place replacement. + +## Rollout Goals + +1. End-to-end request tracing for realtime and agent workflows. +2. LLM span observability (latency, error, model usage metadata). +3. Correlation across API worker, orchestrator, cloudbot, and client-facing sessions. +4. Safe telemetry posture (no secrets/PII leakage). + +## Recommended Rollout Phases + +### Phase 1: API Worker Core + +Instrument: + +- `POST /api/v1/realtime/token` +- `GET /api/v1/cto/openai/models` +- `GET /api/v1/cto/openai/usage` +- `GET /api/v1/cto/cloudflare/*` + +Required attributes: + +- `workspace.id` +- `route.name` +- `llm.vendor` +- `llm.model` (when applicable) +- `http.status_code` +- `error.type` + +### Phase 2: Agent Backends + +Instrument: + +- `opencto/cto-orchestrator` incident cycles and OpenAI triage calls +- `opencto/opencto-cloudbot-worker` RAG retrieval + response generation + webhook lifecycle + +### Phase 3: Client Correlation + +- propagate trace context IDs from API worker into dashboard/mobile session state +- attach trace IDs to support/debug payloads (without exposing secrets) + +### Phase 4: Governance + +- add CI checks for telemetry redaction rules +- enforce denylist for sensitive fields: + - `token`, `secret`, `authorization`, API keys, raw credentials + +## Suggested Environment Variables + +| Variable | Purpose | +| --- | --- | +| `TRACELOOP_API_KEY` | Auth for Traceloop ingestion | +| `TRACELOOP_BASE_URL` | Optional endpoint override | +| `TRACELOOP_ENABLED` | Feature flag for gradual rollout | +| `TRACELOOP_SERVICE_NAME` | Service-level identity per component | +| `TRACELOOP_ENV` | Environment tag (`dev`, `staging`, `production`) | + +## Suggested Service Matrix + +| Service | Start Phase | Priority | +| --- | --- | --- | +| `opencto-api-worker` | Phase 1 | Critical | +| `cto-orchestrator` | Phase 2 | High | +| `opencto-cloudbot-worker` | Phase 2 | High | +| `opencto-voice-backend` | Phase 2/3 | Medium | +| dashboard/mobile clients | Phase 3 | Medium | + +## Minimal Implementation Checklist + +1. Add Traceloop SDK/config to `opencto-api-worker`. +2. Wrap OpenAI and Cloudflare proxy paths with spans. +3. Add span context propagation headers for cross-service correlation. +4. Add redaction middleware for trace attributes. +5. Repeat for orchestrator and cloudbot. +6. Build latency/error dashboards per workflow. + +## Validation Checklist + +- Trace appears for every `/api/v1/realtime/token` request. +- OpenAI model and usage proxy calls produce linked spans. +- Failed upstream requests show structured error attributes. +- No secret-bearing fields appear in traces. +- End-to-end correlation from user action to backend spans is queryable. + +## References (Chicago 17B) + +Traceloop. “Introduction.” *Traceloop Documentation*. Accessed March 6, 2026. https://www.traceloop.com/docs. + +OpenTelemetry. “What Is OpenTelemetry?” *OpenTelemetry Documentation*. Accessed March 6, 2026. https://opentelemetry.io/docs/what-is-opentelemetry/.