coaiajs 0.1.2 → 0.2.0

package/articles/technical/octokit-github-api.md

@@ -0,0 +1,293 @@
+# @octokit/rest: Technical Assessment for CoAiA.js
+
+> Package selection brief — GitHub REST API client replacing coaiapy's raw requests in cogh.py
+
+## Summary & Recommendation
+
+**Use `@octokit/rest` v22.x** (currently 22.0.1). Octokit is the official GitHub-maintained JavaScript client for the GitHub REST API. It replaces coaiapy's `cogh.py` which manually constructs HTTP requests with auth headers. Octokit provides typed methods for every GitHub endpoint, automatic pagination, built-in authentication, and rate limit handling.
+
+**Pin:** `"@octokit/rest": "^22.0.0"`
+
+## What We're Replacing
+
+Coaiapy's `cogh.py` uses raw HTTP requests:
+
+```python
+# coaiapy/cogh.py — manual GitHub API
+import requests
+import os
+
+def _get_github_headers():
+    config = read_config()
+    token = config.get("github", {}).get("api_token") or os.getenv("GH_TOKEN")
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github.v3+json"
+    }
+
+def list_issues(owner, repo):
+    headers = _get_github_headers()
+    response = requests.get(
+        f"https://api.github.com/repos/{owner}/{repo}/issues",
+        headers=headers
+    )
+    return response.json()
+
+def get_issue(owner, repo, issue_number):
+    headers = _get_github_headers()
+    response = requests.get(
+        f"https://api.github.com/repos/{owner}/{repo}/issues/{issue_number}",
+        headers=headers
+    )
+    return response.json()
+```
+
+Issues: no pagination handling, no rate limit awareness, no type safety, manual URL construction, no retry logic.
+
+## Options Compared
+
+| Feature | @octokit/rest v22 | Raw fetch/requests | graphql (@octokit/graphql) |
+|---------|-------------------|-------------------|--------------------------|
+| API coverage | All REST endpoints typed | Manual per endpoint | GraphQL (different paradigm) |
+| Authentication | Token, App, OAuth, Action | Manual headers | Same as octokit |
+| Pagination | `octokit.paginate()` automatic | Manual `Link` header parsing | Cursor-based (manual) |
+| Rate limiting | Built-in retry plugin | Manual `X-RateLimit-*` handling | Same as octokit |
+| TypeScript | Full types for every endpoint | Manual interfaces | Partial |
+| Request/response hooks | Plugin system | Manual interceptors | Plugin system |
+| Bundle size | ~150KB | 0 | ~50KB |
+| Maintenance | GitHub-maintained official | N/A | GitHub-maintained official |
+
+## API Overview
+
+### Client Setup
+
+```typescript
+import { Octokit } from '@octokit/rest';
+import { loadConfig } from '../config.js';
+
+const config = loadConfig();
+
+const octokit = new Octokit({
+  auth: config.githubToken ?? process.env.GH_TOKEN,
+  userAgent: 'coaiajs/1.0.0',
+});
+```
+
+### Issues API (replacing cogh.py)
+
+```typescript
+// List issues (replaces cogh.list_issues)
+async function listIssues(owner: string, repo: string, options?: {
+  state?: 'open' | 'closed' | 'all';
+  labels?: string[];
+  per_page?: number;
+}) {
+  const { data } = await octokit.rest.issues.listForRepo({
+    owner,
+    repo,
+    state: options?.state ?? 'open',
+    labels: options?.labels?.join(','),
+    per_page: options?.per_page ?? 30,
+  });
+  return data;
+}
+
+// Get single issue (replaces cogh.get_issue)
+async function getIssue(owner: string, repo: string, issueNumber: number) {
+  const { data } = await octokit.rest.issues.get({
+    owner,
+    repo,
+    issue_number: issueNumber,
+  });
+  return data;
+}
+
+// Create issue
+async function createIssue(owner: string, repo: string, title: string, body: string, labels?: string[]) {
+  const { data } = await octokit.rest.issues.create({
+    owner,
+    repo,
+    title,
+    body,
+    labels,
+  });
+  return data;
+}
+
+// Add comment to issue
+async function commentOnIssue(owner: string, repo: string, issueNumber: number, body: string) {
+  const { data } = await octokit.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    body,
+  });
+  return data;
+}
+```
+
+### Automatic Pagination
+
+```typescript
+// Fetch ALL issues across all pages
+async function listAllIssues(owner: string, repo: string) {
+  const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
+    owner,
+    repo,
+    state: 'all',
+    per_page: 100,
+  });
+  return issues; // All pages concatenated
+}
+```
+
+### Session Management (Miadi webhook pattern)
+
+```typescript
+// Create issue for agent session tracking
+async function createSessionIssue(
+  owner: string,
+  repo: string,
+  sessionId: string,
+  metadata: Record<string, string>
+) {
+  const body = [
+    `## Agent Session: ${sessionId}`,
+    '',
+    '| Key | Value |',
+    '|-----|-------|',
+    ...Object.entries(metadata).map(([k, v]) => `| ${k} | ${v} |`),
+  ].join('\n');
+
+  return createIssue(owner, repo, `Session: ${sessionId}`, body, ['agent-session']);
+}
+
+// Update session with results
+async function updateSessionIssue(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  results: string
+) {
+  await commentOnIssue(owner, repo, issueNumber, results);
+  
+  // Close when session completes
+  await octokit.rest.issues.update({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    state: 'closed',
+  });
+}
+```
+
+### Repository Operations
+
+```typescript
+// Get file contents
+async function getFileContent(owner: string, repo: string, path: string, ref?: string) {
+  const { data } = await octokit.rest.repos.getContent({
+    owner,
+    repo,
+    path,
+    ref,
+  });
+  if ('content' in data) {
+    return Buffer.from(data.content, 'base64').toString('utf-8');
+  }
+  throw new Error(`${path} is not a file`);
+}
+
+// List commits
+async function listRecentCommits(owner: string, repo: string, count = 10) {
+  const { data } = await octokit.rest.repos.listCommits({
+    owner,
+    repo,
+    per_page: count,
+  });
+  return data.map(c => ({
+    sha: c.sha.slice(0, 7),
+    message: c.commit.message.split('\n')[0],
+    author: c.commit.author?.name,
+    date: c.commit.author?.date,
+  }));
+}
+```
+
+### Authentication Patterns
+
+```typescript
+// Pattern 1: Personal Access Token (default)
+const octokit = new Octokit({ auth: process.env.GH_TOKEN });
+
+// Pattern 2: GitHub Actions token
+const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+
+// Pattern 3: GitHub App (for Miadi webhook integration)
+import { createAppAuth } from '@octokit/auth-app';
+
+const octokit = new Octokit({
+  authStrategy: createAppAuth,
+  auth: {
+    appId: config.githubAppId,
+    privateKey: config.githubPrivateKey,
+    installationId: config.githubInstallationId,
+  },
+});
+```
+
+### Formatting (replacing cogh.format_issues_table)
+
+```typescript
+function formatIssuesTable(issues: Awaited<ReturnType<typeof listIssues>>): string {
+  const header = '| # | Title | State | Labels | Updated |';
+  const separator = '|---|-------|-------|--------|---------|';
+  const rows = issues.map(i => 
+    `| ${i.number} | ${i.title} | ${i.state} | ${i.labels.map(l => 
+      typeof l === 'string' ? l : l.name).join(', ')} | ${i.updated_at?.slice(0, 10)} |`
+  );
+  return [header, separator, ...rows].join('\n');
+}
+```
+
+## Integration Plan
+
+1. **Core client:** `src/github/client.ts` — Octokit singleton from config
+2. **Issues module:** `src/github/issues.ts` — CRUD + pagination (replaces cogh.py)
+3. **Session tracking:** `src/github/sessions.ts` — issue-based session management
+4. **Repository module:** `src/github/repos.ts` — file content, commits
+5. **CLI command:** `src/commands/gh.ts` — Commander subcommand for GitHub ops
+6. **MCP tool:** `mcp/tools/github.ts` — GitHub operations as agent tools
+7. **Auth:** Support PAT, Actions token, and GitHub App auth
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 22.0.1 (Feb 2026) |
+| Weekly downloads | ~10M+ |
+| TypeScript | Full native types for every endpoint |
+| Node.js compat | ≥20 (v22 dropped Node 18) |
+| Authentication | PAT, OAuth, App, Actions |
+| Pagination | Built-in `octokit.paginate()` |
+| Rate limiting | Plugin-based retry |
+| Maintained by | GitHub (official) |
+| License | MIT |
+
+### Ecosystem Packages
+
+| Package | Purpose | When to Use |
+|---------|---------|-------------|
+| `@octokit/rest` | REST API client | Primary — all REST operations |
+| `@octokit/graphql` | GraphQL API | Complex queries (PR reviews, nested data) |
+| `@octokit/auth-app` | GitHub App auth | Miadi webhook integration |
+| `@octokit/webhooks` | Webhook handling | Receiving GitHub webhooks |
+| `@octokit/plugin-paginate-rest` | Pagination | Included in @octokit/rest |
+
+## References
+
+- npm: https://www.npmjs.com/package/@octokit/rest
+- GitHub: https://github.com/octokit/rest.js
+- Docs: https://octokit.github.io/rest.js/v22/
+- Auth patterns: https://github.com/octokit/auth-app.js
+- Releases: https://github.com/octokit/rest.js/releases

package/articles/technical/openai-sdk-modern.md

@@ -0,0 +1,231 @@
+# OpenAI Node.js SDK: Technical Assessment for CoAiA.js
+
+> Package selection brief — Unified LLM client for chat completions, streaming, and Whisper transcription replacing coaiapy's raw HTTP calls
+
+## Summary & Recommendation
+
+**Use `openai` v6.x SDK** (currently 6.27.0). The official SDK provides type-safe chat completions with streaming, Whisper audio transcription, and image generation — all features coaiajs needs. The SDK handles authentication, retry logic, rate limiting, and model-specific serialization. Combined with `@langfuse/openai` for automatic tracing, this eliminates all raw HTTP request code.
+
+**Pin:** `"openai": "^6.0.0"`
+
+## What We're Replacing
+
+Coaiapy uses raw HTTP requests for OpenAI API calls, scattered across multiple modules:
+
+```python
+# coaiapy pattern — manual HTTP to OpenAI
+import requests
+import json
+
+def call_openai(messages, model="gpt-4"):
+    headers = {
+        "Authorization": f"Bearer {os.getenv('OPENAI_API_KEY')}",
+        "Content-Type": "application/json"
+    }
+    response = requests.post(
+        "https://api.openai.com/v1/chat/completions",
+        headers=headers,
+        json={"model": model, "messages": messages}
+    )
+    return response.json()["choices"][0]["message"]["content"]
+```
+
+This pattern: no streaming, no automatic retry, no type safety, no token counting, no multimodal support, and requires manual header management per request.
+
+## Options Compared
+
+| Feature | openai SDK v6 | Raw fetch/requests | LangChain OpenAI |
+|---------|--------------|-------------------|------------------|
+| Type safety | Full TypeScript types | Manual interfaces | Via LangChain types |
+| Streaming | `stream: true` + async iterator | Manual SSE parsing | LangChain callbacks |
+| Whisper transcription | `client.audio.transcriptions.create()` | Manual multipart form | Not supported |
+| Image generation | `client.images.generate()` | Manual API call | Via LangChain |
+| Rate limit handling | Built-in retry with backoff | Manual retry loops | Via LangChain |
+| Token counting | Response includes usage | Manual counting | Via callbacks |
+| Langfuse integration | `@langfuse/openai` wrapper | Manual trace creation | `CallbackHandler` |
+| Realtime API | WebSocket support built-in | Manual WebSocket | N/A |
+| Bundle overhead | ~50KB | 0 | ~200KB+ |
+| Maintenance | Official, rapid updates | None | LangChain release cycle |
+
+## API Overview
+
+### Client Setup
+
+```typescript
+import OpenAI from 'openai';
+import { loadConfig } from '../config.js';
+
+const config = loadConfig();
+const openai = new OpenAI({
+  apiKey: config.openaiApiKey,
+  // Optional: custom base URL for Azure OpenAI or local models
+  baseURL: config.openaiBaseUrl,
+});
+```
+
+### Chat Completions (Standard)
+
+```typescript
+async function chatCompletion(
+  messages: OpenAI.ChatCompletionMessageParam[],
+  model = 'gpt-5.4'
+): Promise<string> {
+  const response = await openai.chat.completions.create({
+    model,
+    messages,
+    temperature: 0.7,
+  });
+  return response.choices[0]?.message?.content ?? '';
+}
+
+// Usage in coaiajs
+const analysis = await chatCompletion([
+  { role: 'system', content: 'You are a structural tension chart analyst.' },
+  { role: 'user', content: `Analyze this chart: ${JSON.stringify(chart)}` },
+]);
+```
+
+### Streaming Chat Completions
+
+```typescript
+async function* streamChat(
+  messages: OpenAI.ChatCompletionMessageParam[],
+  model = 'gpt-5.4'
+): AsyncGenerator<string> {
+  const stream = await openai.chat.completions.create({
+    model,
+    messages,
+    stream: true,
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content;
+    if (content) yield content;
+  }
+}
+
+// Usage in CLI for real-time output
+async function streamToTerminal(messages: OpenAI.ChatCompletionMessageParam[]) {
+  for await (const chunk of streamChat(messages)) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write('\n');
+}
+```
+
+### Whisper Transcription (replacing voice-to-text pipeline)
+
+```typescript
+import fs from 'fs';
+
+async function transcribeAudio(filePath: string, language = 'en'): Promise<string> {
+  const response = await openai.audio.transcriptions.create({
+    file: fs.createReadStream(filePath),
+    model: 'whisper-1',
+    language,
+    response_format: 'text',
+  });
+  return response;
+}
+
+// Verbose transcription with timestamps
+async function transcribeVerbose(filePath: string) {
+  const response = await openai.audio.transcriptions.create({
+    file: fs.createReadStream(filePath),
+    model: 'whisper-1',
+    response_format: 'verbose_json',
+    timestamp_granularities: ['segment'],
+  });
+  return response; // includes segments with start/end timestamps
+}
+```
+
+### Image Generation (for chart visualization)
+
+```typescript
+async function generateChartImage(description: string): Promise<string> {
+  const response = await openai.images.generate({
+    model: 'dall-e-3',
+    prompt: `Structural tension chart visualization: ${description}`,
+    n: 1,
+    size: '1024x1024',
+    response_format: 'url',
+  });
+  return response.data[0]?.url ?? '';
+}
+```
+
+### With Langfuse Tracing (automatic observability)
+
+```typescript
+import { observeOpenAI } from '@langfuse/openai';
+import OpenAI from 'openai';
+import { getLangfuse } from '../langfuse/client.js';
+
+// Wrap OpenAI client for automatic trace capture
+const tracedOpenai = observeOpenAI(new OpenAI(), {
+  langfuse: getLangfuse(),
+  generationName: 'coaia-generation',
+});
+
+// Every API call is automatically traced in Langfuse
+// with model, tokens, latency, cost tracking
+const response = await tracedOpenai.chat.completions.create({
+  model: 'gpt-5.4',
+  messages: [{ role: 'user', content: 'Evaluate this structural tension...' }],
+});
+```
+
+### Structured Output with Zod
+
+```typescript
+import { z } from 'zod';
+import { zodResponseFormat } from 'openai/helpers/zod';
+
+const ChartAnalysis = z.object({
+  tension_score: z.number().min(0).max(10),
+  recommendations: z.array(z.string()),
+  next_action: z.string(),
+});
+
+const response = await openai.beta.chat.completions.parse({
+  model: 'gpt-5.4',
+  messages: [{ role: 'user', content: `Analyze: ${JSON.stringify(chart)}` }],
+  response_format: zodResponseFormat(ChartAnalysis, 'chart_analysis'),
+});
+
+const analysis = response.choices[0]?.message?.parsed;
+// analysis is fully typed as { tension_score: number; recommendations: string[]; next_action: string }
+```
+
+## Integration Plan
+
+1. **Core client:** `src/openai/client.ts` — singleton, config-driven, with Langfuse wrapper
+2. **Chat module:** `src/openai/chat.ts` — standard + streaming completions
+3. **Audio module:** `src/openai/audio.ts` — Whisper transcription (replaces voice pipeline)
+4. **Structured output:** `src/openai/structured.ts` — Zod-validated responses
+5. **MCP tool integration:** Tools that call OpenAI for analysis, decomposition, evaluation
+6. **Pipeline steps:** `src/pipeline/generation-step.ts` — traced generation within pipelines
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 6.27.0 (March 2026) |
+| Weekly downloads | ~15M+ |
+| TypeScript | Full native types |
+| Node.js compat | ≥20 LTS |
+| Runtime support | Node.js, Deno, Bun, edge |
+| Streaming | SSE async iterator |
+| Structured output | Zod helper built-in |
+| Models supported | GPT-5.x, GPT-4.x, Whisper, DALL-E, Realtime |
+| Langfuse integration | `@langfuse/openai` drop-in wrapper |
+| License | Apache-2.0 |
+
+## References
+
+- npm: https://www.npmjs.com/package/openai
+- GitHub: https://github.com/openai/openai-node
+- API docs: https://developers.openai.com/api/docs/libraries/
+- DeepWiki: https://deepwiki.com/openai/openai-node
+- Releases: https://github.com/openai/openai-node/releases