@monoes/monograph 1.1.0 → 1.2.1

package/src/wiki/prompt-builder.ts

@@ -0,0 +1,35 @@
+export interface CommunityContext {
+  communityId: string;
+  label: string;
+  topSymbols: { name: string; label: string; filePath: string | null }[];
+  incomingCount: number;
+  outgoingCount: number;
+}
+
+/**
+ * Build an LLM prompt for generating a wiki page about a code community.
+ */
+export function buildWikiPrompt(context: CommunityContext): string {
+  const symbolLines = context.topSymbols
+    .map(s => `  - [${s.label}] ${s.name}${s.filePath ? ` (${s.filePath})` : ''}`)
+    .join('\n');
+
+  return `You are a technical documentation writer. Write a concise markdown wiki page for the following code module (community).
+
+Community ID: ${context.communityId}
+Module Name: ${context.label}
+Incoming Dependencies: ${context.incomingCount} (other modules that depend on this one)
+Outgoing Dependencies: ${context.outgoingCount} (modules this one depends on)
+
+Top Symbols:
+${symbolLines || '  (none)'}
+
+Write a wiki page that includes:
+1. A brief description of what this module does
+2. The key entry points and their purpose
+3. What this module depends on and what depends on it
+4. Any notable architectural patterns observed
+
+Format the output as markdown with a top-level heading using the module name.
+Be concise but informative. Focus on the role this module plays in the overall system.`;
+}

package/src/wiki/providers.ts

@@ -0,0 +1,160 @@
+export type LLMProvider = 'anthropic' | 'openai' | 'ollama';
+
+export interface LLMConfig {
+  provider: LLMProvider;
+  model?: string;       // e.g. "claude-3-haiku-20240307", "gpt-4o-mini", "mistral"
+  apiKey?: string;      // read from env if not provided
+  baseUrl?: string;     // for ollama: "http://localhost:11434"
+  maxTokens?: number;   // default 2048
+  temperature?: number; // default 0.2
+}
+
+export interface LLMResponse {
+  text: string;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+const REASONING_MODELS = new Set(['o1', 'o1-mini', 'o1-preview', 'o3', 'o3-mini', 'o4-mini']);
+
+function isReasoningModel(model: string): boolean {
+  return REASONING_MODELS.has(model) || /^o\d+(-mini|-preview)?$/.test(model);
+}
+
+/**
+ * Call an LLM provider with the given prompt and configuration.
+ * Supports anthropic, openai, and ollama providers.
+ */
+export async function callLLM(prompt: string, config: LLMConfig): Promise<LLMResponse> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 30_000);
+
+  try {
+    switch (config.provider) {
+      case 'anthropic':
+        return await callAnthropic(prompt, config, controller.signal);
+      case 'openai':
+        return await callOpenAI(prompt, config, controller.signal);
+      case 'ollama':
+        return await callOllama(prompt, config, controller.signal);
+      default: {
+        const _exhaustive: never = config.provider;
+        throw new Error(`Unknown LLM provider: ${_exhaustive}`);
+      }
+    }
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function callAnthropic(
+  prompt: string,
+  config: LLMConfig,
+  signal: AbortSignal,
+): Promise<LLMResponse> {
+  const apiKey = config.apiKey ?? process.env['ANTHROPIC_API_KEY'];
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    signal,
+    headers: {
+      'x-api-key': apiKey ?? '',
+      'anthropic-version': '2023-06-01',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: config.model ?? 'claude-3-haiku-20240307',
+      max_tokens: config.maxTokens ?? 2048,
+      messages: [{ role: 'user', content: prompt }],
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`LLM provider anthropic error: ${response.status} ${response.statusText}`);
+  }
+
+  const data = await response.json() as {
+    content: Array<{ text: string }>;
+    usage: { input_tokens: number; output_tokens: number };
+  };
+
+  return {
+    text: data.content[0].text,
+    inputTokens: data.usage.input_tokens,
+    outputTokens: data.usage.output_tokens,
+  };
+}
+
+async function callOpenAI(
+  prompt: string,
+  config: LLMConfig,
+  signal: AbortSignal,
+): Promise<LLMResponse> {
+  const apiKey = config.apiKey ?? process.env['OPENAI_API_KEY'];
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    signal,
+    headers: {
+      'Authorization': `Bearer ${apiKey ?? ''}`,
+      'content-type': 'application/json',
+    },
+    body: (() => {
+      const reasoning = isReasoningModel(config.model ?? '');
+      const bodyObj: Record<string, unknown> = {
+        model: config.model ?? 'gpt-4o-mini',
+        messages: [{ role: 'user', content: prompt }],
+      };
+      if (reasoning) {
+        bodyObj['max_completion_tokens'] = config.maxTokens ?? 2048;
+      } else {
+        bodyObj['max_tokens'] = config.maxTokens ?? 2048;
+        bodyObj['temperature'] = config.temperature ?? 0.2;
+      }
+      return JSON.stringify(bodyObj);
+    })(),
+  });
+
+  if (!response.ok) {
+    throw new Error(`LLM provider openai error: ${response.status} ${response.statusText}`);
+  }
+
+  const data = await response.json() as {
+    choices: Array<{ message: { content: string } }>;
+    usage: { prompt_tokens: number; completion_tokens: number };
+  };
+
+  return {
+    text: data.choices[0].message.content,
+    inputTokens: data.usage.prompt_tokens,
+    outputTokens: data.usage.completion_tokens,
+  };
+}
+
+async function callOllama(
+  prompt: string,
+  config: LLMConfig,
+  signal: AbortSignal,
+): Promise<LLMResponse> {
+  const baseUrl = config.baseUrl ?? 'http://localhost:11434';
+  const response = await fetch(`${baseUrl}/api/generate`, {
+    method: 'POST',
+    signal,
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: config.model ?? 'mistral',
+      prompt,
+      stream: false,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`LLM provider ollama error: ${response.status} ${response.statusText}`);
+  }
+
+  const data = await response.json() as { response: string };
+
+  return {
+    text: data.response,
+  };
+}

package/src/wiki/wiki-generator.ts

@@ -0,0 +1,218 @@
+import type { MonographDb } from '../storage/db.js';
+import { buildWikiPrompt } from './prompt-builder.js';
+import { upsertWikiPage, getWikiPage, listWikiPages } from './wiki-store.js';
+import { callLLM, type LLMConfig } from './providers.js';
+
+export type { LLMConfig } from './providers.js';
+export type { LLMProvider, LLMResponse } from './providers.js';
+
+export interface WikiGeneratorOptions {
+  repoPath: string;
+  reviewOnly?: boolean;
+  db?: MonographDb;
+}
+
+export interface WikiGeneratorResult {
+  reviewMode?: boolean;
+  proposedGroupings?: unknown[];
+  pages: string[];
+  pageCount: number;
+}
+
+/**
+ * Top-level wiki generation entry point.
+ * When reviewOnly is true, returns proposed community groupings without generating pages.
+ */
+export async function generateWiki(options: WikiGeneratorOptions): Promise<WikiGeneratorResult> {
+  const db = options.db;
+
+  // Collect community groupings from DB (if available)
+  let groupings: unknown[] = [];
+  if (db) {
+    try {
+      const rows = db.prepare('SELECT DISTINCT community_id FROM nodes WHERE community_id IS NOT NULL').all();
+      groupings = rows as unknown[];
+    } catch {
+      groupings = [];
+    }
+  }
+
+  if (options.reviewOnly) {
+    return {
+      reviewMode: true,
+      proposedGroupings: groupings,
+      pages: [],
+      pageCount: 0,
+    };
+  }
+
+  // Full generation path
+  if (!db) {
+    return { pages: [], pageCount: 0 };
+  }
+
+  const result = await generateAllWikiPages(db);
+  return {
+    pages: [],
+    pageCount: result.generated,
+  };
+}
+
+export interface LlmClient {
+  generate: (prompt: string) => Promise<string>;
+}
+
+export interface GenerateWikiPageOptions {
+  model?: string;
+  apiKey?: string;
+  /** Inject a test client instead of calling Anthropic API */
+  llmClient?: LlmClient;
+  /** Use a multi-provider LLM config instead of the default Anthropic SDK */
+  llmConfig?: LLMConfig;
+}
+
+export interface GenerateAllWikiPagesOptions {
+  force?: boolean;
+  model?: string;
+  communityId?: string;
+  llmClient?: LlmClient;
+  /** Use a multi-provider LLM config instead of the default Anthropic SDK */
+  llmConfig?: LLMConfig;
+}
+
+export interface GenerateAllResult {
+  generated: number;
+  skipped: number;
+  errors: number;
+}
+
+/**
+ * Generate a wiki page for a single community using the LLM.
+ * Returns the generated markdown content and persists it to the DB.
+ */
+export async function generateWikiPage(
+  db: MonographDb,
+  communityId: string,
+  options?: GenerateWikiPageOptions,
+): Promise<string> {
+  const communityIdStr = String(communityId);
+
+  // 1. Get community label
+  const commRow = db.prepare('SELECT id, label FROM communities WHERE id = ?')
+    .get(Number(communityIdStr)) as { id: number; label: string | null } | undefined;
+  const label = commRow?.label ?? `Community ${communityIdStr}`;
+
+  // 2. Get top 5 symbols by degree (count of connected edges, since no centrality column)
+  const symbolRows = db.prepare(`
+    SELECT n.name, n.label, n.file_path,
+           COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) AS degree
+    FROM nodes n
+    LEFT JOIN edges e1 ON e1.source_id = n.id
+    LEFT JOIN edges e2 ON e2.target_id = n.id
+    WHERE n.community_id = ?
+    GROUP BY n.id
+    ORDER BY degree DESC, n.name ASC
+    LIMIT 5
+  `).all(Number(communityIdStr)) as { name: string; label: string; file_path: string | null }[];
+
+  // 3. Count incoming edges to community (edges whose target is in this community)
+  const incomingRow = db.prepare(`
+    SELECT COUNT(*) AS cnt FROM edges
+    WHERE target_id IN (SELECT id FROM nodes WHERE community_id = ?)
+  `).get(Number(communityIdStr)) as { cnt: number };
+
+  // 4. Count outgoing edges from community (edges whose source is in this community)
+  const outgoingRow = db.prepare(`
+    SELECT COUNT(*) AS cnt FROM edges
+    WHERE source_id IN (SELECT id FROM nodes WHERE community_id = ?)
+  `).get(Number(communityIdStr)) as { cnt: number };
+
+  // 5. Build prompt
+  const prompt = buildWikiPrompt({
+    communityId: communityIdStr,
+    label,
+    topSymbols: symbolRows.map(r => ({ name: r.name, label: r.label, filePath: r.file_path })),
+    incomingCount: incomingRow.cnt,
+    outgoingCount: outgoingRow.cnt,
+  });
+
+  // 6. Call LLM (injected client, multi-provider config, or Anthropic SDK)
+  let content: string;
+
+  if (options?.llmClient) {
+    content = await options.llmClient.generate(prompt);
+  } else if (options?.llmConfig) {
+    const result = await callLLM(prompt, options.llmConfig);
+    content = result.text;
+  } else {
+    const apiKey = options?.apiKey ?? process.env['ANTHROPIC_API_KEY'];
+    if (!apiKey) {
+      throw new Error('ANTHROPIC_API_KEY not set');
+    }
+    const { default: Anthropic } = await import('@anthropic-ai/sdk');
+    const client = new Anthropic({ apiKey });
+    const msg = await client.messages.create({
+      model: options?.model ?? 'claude-haiku-4-5-20251001',
+      max_tokens: 1024,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    const block = msg.content[0];
+    content = (block?.type === 'text') ? block.text : '';
+  }
+
+  // 7. Persist to DB
+  upsertWikiPage(db, communityIdStr, content);
+
+  return content;
+}
+
+/**
+ * Generate wiki pages for all (or a filtered) communities.
+ */
+export async function generateAllWikiPages(
+  db: MonographDb,
+  options?: GenerateAllWikiPagesOptions,
+): Promise<GenerateAllResult> {
+  // Get all distinct community_ids from nodes
+  let communityRows: { community_id: number }[];
+
+  if (options?.communityId != null) {
+    communityRows = [{ community_id: Number(options.communityId) }];
+  } else {
+    communityRows = db.prepare(
+      'SELECT DISTINCT community_id FROM nodes WHERE community_id IS NOT NULL',
+    ).all() as { community_id: number }[];
+  }
+
+  let generated = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for (const row of communityRows) {
+    const communityIdStr = String(row.community_id);
+
+    // Skip if already generated and force is not set
+    if (!options?.force) {
+      const existing = getWikiPage(db, communityIdStr);
+      if (existing) {
+        skipped++;
+        continue;
+      }
+    }
+
+    try {
+      await generateWikiPage(db, communityIdStr, {
+        model: options?.model,
+        llmClient: options?.llmClient,
+        llmConfig: options?.llmConfig,
+      });
+      generated++;
+    } catch {
+      errors++;
+    }
+  }
+
+  return { generated, skipped, errors };
+}
+
+export { upsertWikiPage, getWikiPage, listWikiPages };

package/src/wiki/wiki-store.ts

@@ -0,0 +1,49 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface WikiPage {
+  communityId: string;
+  content: string;
+  generatedAt: string;
+}
+
+/**
+ * Upsert a wiki page for a community.
+ * community_id is stored as TEXT (coerced from integer community_id in nodes).
+ */
+export function upsertWikiPage(db: MonographDb, communityId: string, content: string): void {
+  const generatedAt = new Date().toISOString();
+  db.prepare(`
+    INSERT INTO wiki_pages (community_id, content, generated_at)
+    VALUES (?, ?, ?)
+    ON CONFLICT(community_id) DO UPDATE SET content = excluded.content, generated_at = excluded.generated_at
+  `).run(String(communityId), content, generatedAt);
+}
+
+/**
+ * Get a single wiki page by community ID.
+ */
+export function getWikiPage(db: MonographDb, communityId: string): WikiPage | null {
+  const row = db.prepare('SELECT community_id, content, generated_at FROM wiki_pages WHERE community_id = ?')
+    .get(String(communityId)) as { community_id: string; content: string; generated_at: string } | undefined;
+
+  if (!row) return null;
+  return {
+    communityId: row.community_id,
+    content: row.content,
+    generatedAt: row.generated_at,
+  };
+}
+
+/**
+ * List all wiki pages.
+ */
+export function listWikiPages(db: MonographDb): WikiPage[] {
+  const rows = db.prepare('SELECT community_id, content, generated_at FROM wiki_pages ORDER BY community_id')
+    .all() as { community_id: string; content: string; generated_at: string }[];
+
+  return rows.map(row => ({
+    communityId: row.community_id,
+    content: row.content,
+    generatedAt: row.generated_at,
+  }));
+}

package/tsconfig.json

@@ -6,5 +6,5 @@
     "composite": true
   },
   "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist", "__tests__"]
+  "exclude": ["node_modules", "dist", "__tests__", "src/**/__tests__/**", "src/**/*.test.ts", "src/**/*.spec.ts"]
 }

package/.monomind/sessions/current.json

@@ -1,13 +0,0 @@
-{
-  "id": "session-1777578175215",
-  "startedAt": "2026-04-30T19:42:55.215Z",
-  "platform": "darwin",
-  "cwd": "/Users/morteza/Desktop/tools/monobrain/packages/@monomind/monograph",
-  "context": {},
-  "metrics": {
-    "edits": 9,
-    "commands": 0,
-    "tasks": 0,
-    "errors": 0
-  }
-}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024-2026 ruvnet
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.