coaiajs 0.3.0 → 0.3.2

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

@@ -1,293 +0,0 @@
-# @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

@@ -1,231 +0,0 @@
-# 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