pi-para 0.6.7 → 0.7.0

package/src/maintainer.ts

@@ -1,404 +0,0 @@
-/**
- * Wiki maintenance agent - uses LLM to intelligently maintain the wiki.
- *
- * Replaces brittle code-based maintenance (link discovery, dedup detection,
- * tag canonicalization, category review) with an LLM agent that understands
- * content and can make smarter decisions.
- *
- * Deterministic operations (secret redaction, schema validation, index rebuild)
- * stay in code. This agent handles everything that needs intelligence.
- */
-
-import { Agent } from "@earendil-works/pi-agent-core";
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type { Model } from "@earendil-works/pi-ai";
-import type { QMDStore } from "qmd-engine";
-import { Type } from "typebox";
-import { StringEnum } from "@earendil-works/pi-ai";
-
-import {
-  readPage,
-  writePage,
-  listPages,
-  writeIndex,
-  gitCommit,
-  PARA_CATEGORIES,
-} from "./wiki.js";
-import type { WikiPage, ParaCategory, PageRef } from "./wiki.js";
-import { validateFrontmatter } from "./frontmatter.js";
-import { searchWiki, reindex } from "./store.js";
-import { extractWikilinks, syncFrontmatterLinks } from "./link-utils.js";
-import { normalizeTags, normalizeScopes } from "./tag-registry.js";
-import { redactSecrets } from "./redact.js";
-import { lintWiki } from "./lint.js";
-
-// -- Types -------------------------------------------------------------------
-
-export interface MaintenanceResult {
-  pagesUpdated: number;
-  pagesMerged: number;
-  linksAdded: number;
-  issuesFixed: number;
-  summary: string;
-}
-
-// -- Maintenance prompt ------------------------------------------------------
-
-const MAINTENANCE_SYSTEM_PROMPT = `You are a wiki maintenance agent. Your job is to keep a PARA knowledge base healthy, well-linked, and free of duplicates.
-
-You have tools to inspect and modify the wiki:
-- wiki_list: List all pages with their scope, tags, and link counts
-- wiki_read: Read a page's full content
-- wiki_query: Search for pages by keyword
-- wiki_write: Update a page (merge content, add links, fix category)
-- wiki_merge: Merge two pages into one (keeps the target, deletes the source)
-- wiki_lint: Run automated checks and get a report of issues
-
-Your maintenance tasks (in priority order):
-
-1. DUPLICATE DETECTION & MERGING
-   - Find pages covering the same topic with different slugs
-   - Merge them: combine content into the older/more complete page, delete the duplicate
-   - Examples: "pi-para daemon architecture" and "pi-para daemon" are duplicates
-
-2. WIKILINK DISCOVERY
-   - Find pages that discuss related topics but aren't linked
-   - Add [[wikilinks]] in body text and ## Connections sections
-   - Every page should link to at least 2 related pages
-
-3. CATEGORY REVIEW
-   - resources/ should have reference docs, architecture, how-tos, patterns
-   - areas/ should have ongoing responsibilities only
-   - projects/ should ONLY have actual goals with end dates (almost never used)
-   - Move miscategorized pages
-
-4. TAG CLEANUP
-   - Remove redundant tags (tags that duplicate scope values)
-   - Canonicalize similar tags (e.g. "capture" and "session-capture" → keep "session-capture")
-   - Ensure tags are kebab-case
-
-5. CONTENT QUALITY
-   - Pages should have: Topic, Key Facts, Connections sections at minimum
-   - Flag pages with very thin content for expansion
-   - Flag pages with no ## Connections section
-
-6. STALENESS REVIEW
-   - Identify pages not updated in >30 days that make specific claims about code, file paths, configs, ports, or API endpoints
-   - These are high-risk for being outdated - add a note in Open Questions: "⚠️ This page has not been updated since [date]. Claims about [specific thing] should be verified."
-   - If you can determine from other pages or context that a claim is now wrong, fix it directly
-   - Pages about architecture decisions or historical events are less likely to go stale than pages about configs or deployment
-
-7. PROJECT LIFECYCLE REVIEW
-   - Review projects/ pages — only archive a project if ALL of these are true:
-     a) The End Condition section explicitly says the goal is met or done
-     b) There are NO unchecked items ([ ]) remaining anywhere in the page
-     c) The page has no Open Questions or pending tasks
-   - Do NOT archive just because status checkboxes are ticked — there may be remaining work not captured in checkboxes
-   - When archiving: use wiki_write to create the page in archives/ with '(Completed)' in the title, then wiki_merge to remove the projects/ copy
-
-8. AREAS HEALTH METRICS
-   - Review areas/ pages - update current health metrics based on recent lint results and maintenance findings
-   - Areas represent ongoing responsibilities; keep them current with the latest status
-
-Rules:
-- Work systematically: list all pages first, then process in batches
-- For merges: preserve ALL information from both pages, combine into the better-structured one
-- For links: only add links between genuinely related pages, not random connections
-- Be conservative: when unsure, leave it alone
-- Never include secrets/API keys in page content
-- Scope must be a kebab-case project name, not a topic description
-
-When done, summarize what you changed.`;
-
-// -- Tools -------------------------------------------------------------------
-
-function createMaintenanceTools(wikiDir: string, store: QMDStore): AgentTool[] {
-  const WikiListParams = Type.Object({});
-  const WikiReadParams = Type.Object({ path: Type.String({ description: "category/slug" }) });
-  const WikiQueryParams = Type.Object({ query: Type.String() });
-  const WikiWriteParams = Type.Object({
-    category: StringEnum(["projects", "areas", "resources", "archives"] as const),
-    slug: Type.String(),
-    title: Type.String(),
-    scope: Type.Array(Type.String()),
-    tags: Type.Array(Type.String()),
-    body: Type.String(),
-  });
-  const WikiMergeParams = Type.Object({
-    keepCategory: StringEnum(["projects", "areas", "resources", "archives"] as const),
-    keepSlug: Type.String({ description: "Slug of the page to keep (target)" }),
-    deleteCategory: StringEnum(["projects", "areas", "resources", "archives"] as const),
-    deleteSlug: Type.String({ description: "Slug of the page to delete (source)" }),
-    mergedBody: Type.String({ description: "Combined body text for the kept page" }),
-  });
-  const WikiLintParams = Type.Object({});
-
-  const wikiList: AgentTool<typeof WikiListParams> = {
-    name: "wiki_list",
-    label: "Wiki List",
-    description: "List all wiki pages with scope, tags, and outgoing link count.",
-    parameters: WikiListParams,
-    execute: async () => {
-      const refs = await listPages(wikiDir);
-      const lines: string[] = [];
-      for (const ref of refs) {
-        const page = await readPage(wikiDir, ref.category, ref.slug);
-        if (!page) continue;
-        const linkCount = extractWikilinks(page.body).length;
-        lines.push(
-          `${ref.category}/${ref.slug} | "${page.frontmatter.title}" | scope:[${page.frontmatter.scope.join(",")}] | tags:[${page.frontmatter.tags.join(",")}] | links:${linkCount}`
-        );
-      }
-      return {
-        content: [{ type: "text", text: `${lines.length} pages:\n${lines.join("\n")}` }],
-        details: { count: lines.length },
-      };
-    },
-  };
-
-  const wikiRead: AgentTool<typeof WikiReadParams> = {
-    name: "wiki_read",
-    label: "Wiki Read",
-    description: "Read a wiki page by path (category/slug).",
-    parameters: WikiReadParams,
-    execute: async (_id, params: { path: string }) => {
-      const parts = params.path.split("/");
-      if (parts.length !== 2) {
-        return { content: [{ type: "text", text: `Invalid path: ${params.path}` }], details: {} };
-      }
-      const page = await readPage(wikiDir, parts[0] as ParaCategory, parts[1]);
-      if (!page) {
-        return { content: [{ type: "text", text: `Not found: ${params.path}` }], details: {} };
-      }
-      return {
-        content: [{ type: "text", text: `# ${page.frontmatter.title}\nCategory: ${page.category}\nScope: ${page.frontmatter.scope.join(", ")}\nTags: ${page.frontmatter.tags.join(", ")}\nLinks: ${page.frontmatter.links.join(", ") || "none"}\n\n${page.body}` }],
-        details: { title: page.frontmatter.title },
-      };
-    },
-  };
-
-  const wikiQuery: AgentTool<typeof WikiQueryParams> = {
-    name: "wiki_query",
-    label: "Wiki Query",
-    description: "Search wiki pages by keyword. Returns top matches with scores.",
-    parameters: WikiQueryParams,
-    execute: async (_id, params: { query: string }) => {
-      const results = await searchWiki(store, params.query, { limit: 8 });
-      if (results.length === 0) {
-        return { content: [{ type: "text", text: "No results." }], details: { count: 0 } };
-      }
-      const text = results
-        .map(r => `${r.page.path} | "${r.frontmatter.title}" | score:${r.score.toFixed(3)}`)
-        .join("\n");
-      return {
-        content: [{ type: "text", text: `${results.length} results:\n${text}` }],
-        details: { count: results.length },
-      };
-    },
-  };
-
-  const wikiWrite: AgentTool<typeof WikiWriteParams> = {
-    name: "wiki_write",
-    label: "Wiki Write",
-    description: "Create or update a wiki page. Always redacts secrets and normalizes tags/scope.",
-    parameters: WikiWriteParams,
-    execute: async (_id, params: { category: ParaCategory; slug: string; title: string; scope: string[]; tags: string[]; body: string }) => {
-      const now = new Date().toISOString();
-      const slug = params.slug.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-      const existing = await readPage(wikiDir, params.category, slug);
-      const body = redactSecrets(params.body).text;
-      const scope = normalizeScopes(params.scope);
-      const tags = normalizeTags(params.tags, scope);
-      const links = syncFrontmatterLinks(body);
-
-      if (existing) {
-        const updated: WikiPage = {
-          ...existing,
-          body,
-          frontmatter: { ...existing.frontmatter, title: params.title, scope, tags, updated: now, links },
-        };
-        await writePage(wikiDir, updated);
-      } else {
-        const fm = validateFrontmatter({ title: params.title, para: params.category, scope, tags, sources: [], created: now, updated: now, links });
-        await writePage(wikiDir, { category: params.category, slug, frontmatter: fm, body });
-      }
-      await reindex(store);
-      return {
-        content: [{ type: "text", text: `Wrote ${params.category}/${slug}` }],
-        details: { path: `${params.category}/${slug}` },
-      };
-    },
-  };
-
-  const wikiMerge: AgentTool<typeof WikiMergeParams> = {
-    name: "wiki_merge",
-    label: "Wiki Merge",
-    description: "Merge two pages: update the target page with combined content, delete the source page.",
-    parameters: WikiMergeParams,
-    execute: async (_id, params: { keepCategory: ParaCategory; keepSlug: string; deleteCategory: ParaCategory; deleteSlug: string; mergedBody: string }) => {
-      const keepPage = await readPage(wikiDir, params.keepCategory, params.keepSlug);
-      const deletePage = await readPage(wikiDir, params.deleteCategory, params.deleteSlug);
-      if (!keepPage) return { content: [{ type: "text", text: `Target not found: ${params.keepCategory}/${params.keepSlug}` }], details: {} };
-      if (!deletePage) return { content: [{ type: "text", text: `Source not found: ${params.deleteCategory}/${params.deleteSlug}` }], details: {} };
-
-      const now = new Date().toISOString();
-      const body = redactSecrets(params.mergedBody).text;
-      const mergedScope = normalizeScopes([...new Set([...keepPage.frontmatter.scope, ...deletePage.frontmatter.scope])]);
-      const mergedTags = normalizeTags([...new Set([...keepPage.frontmatter.tags, ...deletePage.frontmatter.tags])], mergedScope);
-
-      // Update target
-      const updated: WikiPage = {
-        ...keepPage,
-        body,
-        frontmatter: {
-          ...keepPage.frontmatter,
-          scope: mergedScope,
-          tags: mergedTags,
-          updated: now,
-          links: syncFrontmatterLinks(body),
-        },
-      };
-      await writePage(wikiDir, updated);
-
-      // Delete source
-      const { unlink } = await import("node:fs/promises");
-      const { join } = await import("node:path");
-      await unlink(join(wikiDir, params.deleteCategory, params.deleteSlug + ".md"));
-
-      await reindex(store);
-      return {
-        content: [{ type: "text", text: `Merged ${params.deleteCategory}/${params.deleteSlug} into ${params.keepCategory}/${params.keepSlug}, deleted source.` }],
-        details: { kept: `${params.keepCategory}/${params.keepSlug}`, deleted: `${params.deleteCategory}/${params.deleteSlug}` },
-      };
-    },
-  };
-
-  const wikiLint: AgentTool<typeof WikiLintParams> = {
-    name: "wiki_lint",
-    label: "Wiki Lint",
-    description: "Run lint checks and return a report. Does NOT auto-fix - you decide what to fix.",
-    parameters: WikiLintParams,
-    execute: async () => {
-      const report = await lintWiki(wikiDir, { autoFix: false });
-      const lines = report.issues.map(i => `[${i.severity}] ${i.category}: ${i.page ?? ""} - ${i.message}`);
-      return {
-        content: [{ type: "text", text: `${report.issues.length} issues:\n${lines.join("\n")}\n\nStats: ${JSON.stringify(report.stats.byCategory)}` }],
-        details: { issueCount: report.issues.length },
-      };
-    },
-  };
-
-  return [wikiList, wikiRead, wikiQuery, wikiWrite, wikiMerge, wikiLint];
-}
-
-// -- Rebuild index helper (shared with processor) ----------------------------
-
-async function rebuildIndex(wikiDir: string): Promise<void> {
-  const allPages = await listPages(wikiDir);
-  const sections: Record<ParaCategory, string[]> = {
-    projects: [], areas: [], resources: [], archives: [],
-  };
-  for (const ref of allPages) {
-    const page = await readPage(wikiDir, ref.category, ref.slug);
-    const title = page?.frontmatter.title ?? ref.title;
-    const summary = page?.body.split("\n").find(l => l.trim() && !l.startsWith("#") && !l.startsWith("---"))?.trim() ?? "";
-    const desc = summary.length > 120 ? summary.slice(0, 117) + "..." : summary;
-    sections[ref.category].push(`- [[${ref.slug}]] - ${title}${desc ? ": " + desc : ""}`);
-  }
-  const indexLines = [
-    "# Wiki Index", "",
-    "## Projects", "", sections.projects.length > 0 ? sections.projects.join("\n") : "_No active projects._", "",
-    "## Areas", "", sections.areas.length > 0 ? sections.areas.join("\n") : "_No areas._", "",
-    "## Resources", "", sections.resources.length > 0 ? sections.resources.join("\n") : "_No resources._", "",
-    "## Archives", "", sections.archives.length > 0 ? sections.archives.join("\n") : "_No archived items._",
-  ];
-  await writeIndex(wikiDir, indexLines.join("\n"));
-}
-
-// -- Main entry point --------------------------------------------------------
-
-/**
- * Run the maintenance agent. Called periodically by the daemon.
- */
-export async function runMaintenance(
-  wikiDir: string,
-  store: QMDStore,
-  model: Model<any>,
-  getApiKey: (provider: string) => Promise<string | undefined>,
-): Promise<MaintenanceResult> {
-  const tools = createMaintenanceTools(wikiDir, store);
-
-  const agent = new Agent({
-    initialState: {
-      systemPrompt: MAINTENANCE_SYSTEM_PROMPT,
-      model,
-      tools,
-      messages: [],
-    },
-    getApiKey,
-  });
-
-  const prompt = `Run a maintenance pass on the wiki. Start by listing all pages, then:
-1. Look for duplicate pages (same topic, different slugs) and merge them
-2. Find pages with 0 outgoing links and add relevant [[wikilinks]]
-3. Check for any category misuse or tag issues
-4. Review pages not updated in >30 days for staleness - add Open Questions warnings for pages making specific claims about code/configs/ports that may have changed
-Be thorough but conservative. Summarize what you changed at the end.`;
-
-  try {
-    await agent.prompt(prompt);
-  } catch (err) {
-    return {
-      pagesUpdated: 0,
-      pagesMerged: 0,
-      linksAdded: 0,
-      issuesFixed: 0,
-      summary: `Agent error: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-
-  // Rebuild index after all changes
-  await rebuildIndex(wikiDir);
-
-  // Extract summary from agent's last message
-  const messages = agent.state.messages;
-  const lastAssistant = [...messages].reverse().find(m => m.role === "assistant");
-  let summary = "Maintenance completed.";
-  if (lastAssistant && "content" in lastAssistant) {
-    const content = lastAssistant.content;
-    if (typeof content === "string") summary = content;
-    else if (Array.isArray(content)) {
-      const textBlock = content.find((b: any) => b.type === "text" && typeof b.text === "string") as { text: string } | undefined;
-      if (textBlock) summary = textBlock.text;
-    }
-  }
-
-  // Count changes from tool results
-  let pagesUpdated = 0;
-  let pagesMerged = 0;
-  for (const msg of messages) {
-    if (msg.role !== "toolResult") continue;
-    const c = msg.content;
-    if (!Array.isArray(c)) continue;
-    for (const block of c) {
-      const b = block as unknown as Record<string, unknown>;
-      if (b.type === "text" && typeof b.text === "string") {
-        if (b.text.startsWith("Wrote ")) pagesUpdated++;
-        if (b.text.startsWith("Merged ")) pagesMerged++;
-      }
-    }
-  }
-
-  // Git commit all maintenance changes
-  if (pagesUpdated > 0 || pagesMerged > 0) {
-    await gitCommit(wikiDir, `maintenance: ${pagesUpdated} updated, ${pagesMerged} merged`);
-  }
-
-  return {
-    pagesUpdated,
-    pagesMerged,
-    linksAdded: 0, // Agent handles this via wiki_write
-    issuesFixed: pagesUpdated + pagesMerged,
-    summary,
-  };
-}

package/src/python/minimax_lm.py

@@ -1,198 +0,0 @@
-"""MiniMax LM for DSPy.
-
-MiniMax provides an Anthropic-compatible API at a custom base URL.
-This module wraps the Anthropic SDK to work with MiniMax endpoints.
-
-MiniMax Models:
-- MiniMax-M2: 196K context, 128K output, reasoning capable
-- MiniMax-M2.1: 196K context, 128K output, reasoning capable
-
-Endpoints:
-- International: https://api.minimax.io/anthropic
-- China: https://api.minimaxi.com/anthropic
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-from typing import Any, Literal
-
-import anthropic
-from dspy.clients.base_lm import BaseLM
-
-logger = logging.getLogger(__name__)
-
-# MiniMax API endpoints
-MINIMAX_BASE_URL = "https://api.minimax.io/anthropic"
-MINIMAX_CN_BASE_URL = "https://api.minimaxi.com/anthropic"
-
-
-def get_minimax_api_key(china: bool = False) -> str | None:
-    """Get MiniMax API key from environment."""
-    if china:
-        return os.environ.get("MINIMAX_CN_API_KEY")
-    return os.environ.get("MINIMAX_API_KEY")
-
-
-class MiniMaxLM(BaseLM):
-    """DSPy-compatible LM for MiniMax models via Anthropic-compatible API.
-    
-    MiniMax provides an Anthropic Messages API compatible endpoint,
-    so we use the Anthropic SDK with a custom base URL.
-    """
-    
-    def __init__(
-        self,
-        model: str = "MiniMax-M2",
-        api_key: str | None = None,
-        china: bool = False,
-        temperature: float | None = None,
-        max_tokens: int | None = None,
-        cache: bool = True,
-        num_retries: int = 3,
-        model_type: Literal["chat", "text"] = "chat",
-        **kwargs,
-    ):
-        """Initialize MiniMax LM.
-        
-        Args:
-            model: Model ID (e.g., "MiniMax-M2", "MiniMax-M2.1")
-            api_key: MiniMax API key (or from MINIMAX_API_KEY env var)
-            china: Use China endpoint (api.minimaxi.com) instead of international
-            temperature: Sampling temperature
-            max_tokens: Maximum tokens to generate
-        """
-        super().__init__(
-            model=f"minimax/{model}" if not model.startswith("minimax/") else model,
-            model_type=model_type,
-            temperature=temperature or 0.0,
-            max_tokens=max_tokens or 8192,
-            cache=cache,
-            num_retries=num_retries,
-        )
-        
-        self._model_id = model.replace("minimax/", "") if model.startswith("minimax/") else model
-        self._china = china
-        self._temperature = temperature or 0.0
-        self._max_tokens = max_tokens or 8192
-        
-        # Get API key
-        self._api_key = api_key or get_minimax_api_key(china)
-        if not self._api_key:
-            env_var = "MINIMAX_CN_API_KEY" if china else "MINIMAX_API_KEY"
-            raise ValueError(f"No MiniMax API key found. Set {env_var} environment variable.")
-        
-        # Create Anthropic client with MiniMax base URL
-        self._base_url = MINIMAX_CN_BASE_URL if china else MINIMAX_BASE_URL
-        self._client = anthropic.Anthropic(
-            api_key=self._api_key,
-            base_url=self._base_url,
-            default_headers={
-                "accept": "application/json",
-            },
-        )
-    
-    def __getstate__(self) -> dict:
-        """Get state for pickling - exclude non-picklable client."""
-        state = self.__dict__.copy()
-        state.pop('_client', None)
-        return state
-    
-    def __setstate__(self, state: dict) -> None:
-        """Restore state from pickle - recreate client."""
-        self.__dict__.update(state)
-        self._client = anthropic.Anthropic(
-            api_key=self._api_key,
-            base_url=self._base_url,
-            default_headers={"accept": "application/json"},
-        )
-    
-    def _convert_messages(self, messages: list[dict]) -> tuple[list[dict], str | None]:
-        """Convert to Anthropic message format."""
-        converted = []
-        system = None
-        
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-            
-            if role == "system":
-                system = content
-            elif role == "assistant":
-                converted.append({"role": "assistant", "content": content})
-            else:
-                converted.append({"role": "user", "content": content})
-        
-        return converted, system
-    
-    def __call__(
-        self,
-        prompt: str | None = None,
-        messages: list[dict] | None = None,
-        **kwargs,
-    ) -> list[dict]:
-        """Call the MiniMax API.
-        
-        Args:
-            prompt: Single prompt string
-            messages: List of messages (OpenAI format)
-            **kwargs: Additional parameters
-            
-        Returns:
-            List of response dicts with 'text' key (DSPy format)
-        """
-        # Build messages
-        if messages is None:
-            messages = []
-        if prompt:
-            messages = [{"role": "user", "content": prompt}]
-        
-        # Convert to Anthropic format
-        converted_messages, system = self._convert_messages(messages)
-        
-        # Build request kwargs
-        request_kwargs: dict[str, Any] = {
-            "model": self._model_id,
-            "messages": converted_messages,
-            "max_tokens": kwargs.get("max_tokens", self._max_tokens),
-            "temperature": kwargs.get("temperature", self._temperature),
-        }
-        
-        if system:
-            request_kwargs["system"] = system
-        
-        # Call API with streaming to support large max_tokens
-        # The Anthropic SDK requires streaming for operations > 10 minutes
-        try:
-            text = ""
-            with self._client.messages.stream(**request_kwargs) as stream:
-                for chunk in stream.text_stream:
-                    text += chunk
-        except anthropic.APIError as e:
-            logger.error("MiniMax API error: %s", e)
-            raise ValueError(f"MiniMax API error: {e}")
-        
-        # Update history for BaseLM
-        self.history.append({
-            "prompt": prompt,
-            "messages": messages,
-            "kwargs": kwargs,
-            "response": {"text": text},
-        })
-        
-        # Return in DSPy format
-        return [{"text": text}]
-
-
-def create_minimax_lm(model: str = "MiniMax-M2", china: bool = False, **kwargs) -> MiniMaxLM:
-    """Create a MiniMax LM instance.
-    
-    Args:
-        model: Model ID (without minimax/ prefix)
-        china: Use China endpoint
-        **kwargs: Additional parameters
-    """
-    if model.startswith("minimax/"):
-        model = model[8:]
-    return MiniMaxLM(model=model, china=china, **kwargs)