From f5c14efb37960b67723a125f280c12aa3c8daa9d Mon Sep 17 00:00:00 2001 From: alvis Date: Sun, 5 Jul 2026 09:56:25 +0000 Subject: [PATCH] openai: add cognee-llm stateless Kimi-CLI wrapper (:8011) [Adolf P3] Stateless one-shot wrapper for Cognee batch cognify: fresh temp dir per request, no resume, non-streaming, text-only, bounded concurrency (3). Per SPIKE-FINDINGS gate 5, Cognee should default its LLM to LiteLLM; this is the optional low-volume path. New service + cognee-llm-home volume in compose. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2 --- openai/cognee-llm/Dockerfile | 11 ++ openai/cognee-llm/README.md | 58 +++++++++ openai/cognee-llm/server.js | 178 ++++++++++++++++++++++++++++ openai/cognee-llm/service-block.yml | 15 +++ openai/docker-compose.yml | 14 +++ 5 files changed, 276 insertions(+) create mode 100644 openai/cognee-llm/Dockerfile create mode 100644 openai/cognee-llm/README.md create mode 100644 openai/cognee-llm/server.js create mode 100644 openai/cognee-llm/service-block.yml diff --git a/openai/cognee-llm/Dockerfile b/openai/cognee-llm/Dockerfile new file mode 100644 index 0000000..db7c997 --- /dev/null +++ b/openai/cognee-llm/Dockerfile @@ -0,0 +1,11 @@ +FROM node:22-slim + +RUN npm install -g @moonshot-ai/kimi-code + +WORKDIR /workspace + +COPY server.js /app/server.js + +EXPOSE 8011 + +ENTRYPOINT ["node", "/app/server.js"] diff --git a/openai/cognee-llm/README.md b/openai/cognee-llm/README.md new file mode 100644 index 0000000..f901b0a --- /dev/null +++ b/openai/cognee-llm/README.md @@ -0,0 +1,58 @@ +# cognee-llm (:8011) + +OpenAI-compatible wrapper around the Kimi Code CLI (`@moonshot-ai/kimi-code`, home +`/root/.kimi-code`), built for Cognee's batch/structured LLM calls. **Opposite policy to +`kimi-agent`**: + +- **Stateless one-shot** — fresh temp dir under `/workspace/` per request, `kimi -p + --output-format stream-json`, **no `-r`/`-S` resume**, dir removed after every call + (success or failure). +- **Non-streaming** — always returns a full `chat.completion` body, even if the caller sets + `stream: true`. +- **No media, no MCP** — text-only prompt built from `messages`; no image persistence, no + `.mcp.json`. +- **Structured/low-temperature intent via prompt, not a sampling param** — the CLI has no raw + temperature knob (it's an agent loop, not a completions API), so determinism/JSON-only output + is enforced with an instruction preamble prepended to the caller's system prompt. +- **Bounded concurrency** — `MAX_CONCURRENCY = 3` in `server.js`, queued beyond that. + +Endpoints: `GET /v1/models` (model id `cognee-llm`), `POST /v1/chat/completions`. + +Own disposable in-container `/workspace` (no host bind mount — nothing here is meant to +survive a request, let alone a container restart) + own `cognee-llm-home` volume +(`/root/.kimi-code`), same Kimi subscription as `kimi-agent`/`adolf-llm`, separate volume so +each wrapper's CLI state stays isolated. + +## Important: this should NOT be Cognee's default LLM backend + +Per `docs/SPIKE-FINDINGS.md` gate 5 (P0 spike, empirically measured against a throwaway authed +container): + +- JSON output from the CLI is clean and schema-conformant when instructed — that part works. +- **Latency is the blocker**: ~5s fixed per-invocation floor (process spawn, config/credential + load) even for a trivial call, ~22-24s for a realistic structured extraction call. Cognify + issues one such call per chunk/entity-extraction step, so a batch of even a few dozen chunks + reaches many minutes of wall time serialized. +- Every call is agentic (tool-call round trips are possible even for "just extract JSON" + prompts), and hammering the single-seat Kimi subscription with concurrent batch CLI spawns + risks rate-limiting/throttling that hasn't been (and shouldn't be) tested at scale. + +**Recommendation: default Cognee's `LLM_API_BASE` to a LiteLLM-routed model (`judge`/local +qwen, per `ARCHITECTURE.md` §3.3's own stated fallback), not this wrapper.** This service stays +buildable/available as the optional, low-volume path (`http://cognee-llm:8011/v1`) — e.g. for +experimentation or if a future need specifically wants Kimi-subscription-backed structured +calls — but P4 should wire Cognee's default LLM to LiteLLM, not here. + +## Smoke test + +```bash +cd /home/alvis/agap_git/openai +docker build -t cognee-llm:local ./cognee-llm +docker run --rm -d --name cognee-llm-smoke -p 18011:8011 cognee-llm:local +curl -s http://localhost:18011/v1/models +docker rm -f cognee-llm-smoke +``` + +A full `/v1/chat/completions` round-trip needs a `kimi login`-authed +`/root/.kimi-code` volume (shared Kimi subscription) — not present in a bare smoke container, +so that step is deferred to integration/P4 wiring. diff --git a/openai/cognee-llm/server.js b/openai/cognee-llm/server.js new file mode 100644 index 0000000..6788220 --- /dev/null +++ b/openai/cognee-llm/server.js @@ -0,0 +1,178 @@ +const http = require('http'); +const fs = require('fs'); +const path = require('path'); +const crypto = require('crypto'); +const { spawn } = require('child_process'); + +const PORT = 8011; +const MODEL_ID = 'cognee-llm'; +const TIMEOUT_MS = 5 * 60 * 1000; // one-shot structured calls; generous but bounded +// Bounded parallelism: SPIKE-FINDINGS.md gate 5 flagged the Kimi subscription as a +// single-seat, interactive-oriented plan — batch cognify must not hammer it with +// unbounded concurrent CLI spawns (rate-limit/throttle risk on a shared live account). +const MAX_CONCURRENCY = 3; + +const WORKSPACE = '/workspace'; +fs.mkdirSync(WORKSPACE, { recursive: true }); + +// The CLI has no raw sampling-temperature knob (it's an agent loop, not a +// completions API) — "low temperature" for structured extraction is enforced +// via an instruction preamble instead, prepended to whatever system prompt +// the caller (Cognee) supplies. +const STRUCTURED_SYSTEM_PREAMBLE = [ + 'You are a stateless structured-extraction engine.', + 'This is a one-shot call with no memory of prior calls: do not reference earlier turns.', + 'Respond deterministically and concisely. When asked for JSON, output raw JSON only', + '- no prose, no markdown code fences, no commentary before or after.', +].join(' '); + +// --- message helpers --------------------------------------------------------- +// Text only, no media parts: this wrapper's policy is no-media/no-MCP, unlike +// adolf-llm which persists inbound images and lets the CLI's ReadMediaFile +// tool read them. +function textOf(msg) { + const c = msg.content; + if (Array.isArray(c)) return c.map(p => (typeof p.text === 'string' ? p.text : '')).join('\n'); + return c == null ? '' : String(c); +} + +function buildPrompt(messages) { + const systemParts = messages.filter(m => m.role === 'system').map(textOf); + const rest = messages.filter(m => m.role !== 'system'); + const preamble = [STRUCTURED_SYSTEM_PREAMBLE, ...systemParts].join('\n\n'); + const transcript = rest + .map(m => `${m.role === 'assistant' ? 'Assistant' : 'User'}: ${textOf(m)}`) + .join('\n\n'); + return `${preamble}\n\n${transcript}`.trim(); +} + +// --- bounded concurrency queue ----------------------------------------------- +let active = 0; +const queue = []; +function drain() { + if (queue.length && active < MAX_CONCURRENCY) queue.shift()(); +} +function withSlot(fn) { + return new Promise((resolve, reject) => { + const run = () => { + active++; + fn().then( + v => { active--; drain(); resolve(v); }, + e => { active--; drain(); reject(e); }, + ); + }; + if (active < MAX_CONCURRENCY) run(); + else queue.push(run); + }); +} + +// --- kimi invocation: stateless one-shot, no resume -------------------------- +// Fresh temp dir per call, NO -r/-S session flag, discard the dir after. +// Returns the assembled text from --output-format stream-json: +// {"role":"assistant","content":"..."} +// (reuses the same parse core as kimi-agent/server.js's runKimi, minus the +// resume/session-id bookkeeping that wrapper needs and this one deliberately +// does not). +function runKimi({ prompt, cwd }) { + return new Promise((resolve, reject) => { + const args = ['-p', prompt, '--output-format', 'stream-json']; + const child = spawn('kimi', args, { cwd, timeout: TIMEOUT_MS }); + + let stdout = ''; + let stderr = ''; + child.stdout.on('data', d => { stdout += d; }); + child.stderr.on('data', d => { stderr += d; }); + + child.on('error', reject); + child.on('close', code => { + const parts = []; + for (const line of stdout.split('\n')) { + const t = line.trim(); + if (!t) continue; + let obj; + try { obj = JSON.parse(t); } catch { continue; } + if (obj.role === 'assistant' && obj.content) parts.push(obj.content); + } + const text = parts.join('').trim(); + if (!text && code !== 0) { + reject(new Error(`kimi exited ${code}: ${stderr.slice(0, 2000)}`)); + } else { + resolve(text); + } + }); + }); +} + +async function handleTurn(messages) { + const prompt = buildPrompt(messages || []); + const reqId = crypto.randomUUID(); + const dir = path.join(WORKSPACE, reqId); + fs.mkdirSync(dir, { recursive: true }); + try { + return await withSlot(() => runKimi({ prompt, cwd: dir })); + } finally { + // Stateless one-shot: nothing about this call is meant to survive it, so + // the temp dir is discarded unconditionally, success or failure. + fs.rm(dir, { recursive: true, force: true }, () => {}); + } +} + +// --- OpenAI-compatible HTTP surface (non-streaming only) --------------------- +function completionBody(text) { + return { + id: `chatcmpl-${Date.now()}`, + object: 'chat.completion', + created: Math.floor(Date.now() / 1000), + model: MODEL_ID, + choices: [{ + index: 0, + message: { role: 'assistant', content: text }, + finish_reason: 'stop', + }], + usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }, + }; +} + +const server = http.createServer((req, res) => { + if (req.method === 'GET' && req.url === '/v1/models') { + res.writeHead(200, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ + object: 'list', + data: [{ id: MODEL_ID, object: 'model', owned_by: 'moonshot' }], + })); + return; + } + + if (req.method === 'POST' && req.url === '/v1/chat/completions') { + let body = ''; + req.on('data', d => { body += d; }); + req.on('end', async () => { + let parsed; + try { + parsed = JSON.parse(body); + } catch { + res.writeHead(400, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ error: 'invalid JSON body' })); + return; + } + + try { + const text = await handleTurn(parsed.messages || []); + // Non-streaming policy: always return the full body even if the + // caller sets stream:true. Cognee's batch cognify has no use for SSE, + // and a one-shot call has nothing to incrementally stream anyway. + res.writeHead(200, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify(completionBody(text))); + } catch (err) { + res.writeHead(500, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ error: String(err.message || err) })); + } + }); + return; + } + + res.writeHead(404, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ error: 'not found' })); +}); + +server.listen(PORT, () => console.log(`cognee-llm wrapper listening on :${PORT}`)); diff --git a/openai/cognee-llm/service-block.yml b/openai/cognee-llm/service-block.yml new file mode 100644 index 0000000..205b6de --- /dev/null +++ b/openai/cognee-llm/service-block.yml @@ -0,0 +1,15 @@ +# Intended service block for /home/alvis/agap_git/openai/docker-compose.yml. +# Not wired in yet (see P3 task note) — orchestrator merges this in and adds +# `cognee-llm-home` to the top-level `volumes:` section. + + cognee-llm: + build: ./cognee-llm + container_name: cognee-llm + ports: + - "8011:8011" + volumes: + - cognee-llm-home:/root/.kimi-code + restart: unless-stopped + +# Add to the top-level `volumes:` block: +# cognee-llm-home: diff --git a/openai/docker-compose.yml b/openai/docker-compose.yml index abcd54a..15db35a 100644 --- a/openai/docker-compose.yml +++ b/openai/docker-compose.yml @@ -154,6 +154,20 @@ services: ["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18789"] restart: unless-stopped + # cognee-llm — stateless one-shot Kimi-CLI wrapper for Cognee's batch cognify + # (P3). Opposite policy to kimi-agent: no resume, non-streaming, text-only. + # Note (SPIKE-FINDINGS gate 5): Cognee should DEFAULT its LLM to LiteLLM; this + # is the optional low-volume path. Needs `kimi login` in its own volume. + cognee-llm: + build: ./cognee-llm + container_name: cognee-llm + ports: + - "8011:8011" + volumes: + - cognee-llm-home:/root/.kimi-code + restart: unless-stopped + volumes: kimi-agent-home: adolf-state: + cognee-llm-home: