@plures/praxis 1.2.13 → 1.2.41

package/src/conversations/candidates.ts

@@ -0,0 +1,114 @@
+/**
+ * Candidates module for praxis-conversations
+ * Generates emission candidates from classified conversations
+ */
+
+import type { Conversation, Candidate, CandidateMetadata } from './types.js';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Generate a candidate from a conversation
+ */
+export function generateCandidate(conversation: Conversation): Candidate | null {
+  if (!conversation.classified || !conversation.classification) {
+    throw new Error('Conversation must be classified before generating candidates');
+  }
+  
+  const { classification } = conversation;
+  
+  // Determine candidate type based on classification
+  let type: Candidate['type'] = 'documentation';
+  if (classification.category === 'bug-report') {
+    type = 'github-issue';
+  } else if (classification.category === 'feature-request') {
+    type = 'github-issue';
+  } else if (classification.category === 'documentation') {
+    type = 'documentation';
+  }
+  
+  // Generate title from first user turn
+  const firstUserTurn = conversation.turns.find(t => t.role === 'user');
+  if (!firstUserTurn) {
+    return null; // No user input to generate candidate from
+  }
+  
+  const title = generateTitle(firstUserTurn.content, classification.category);
+  const body = generateBody(conversation);
+  
+  // Determine priority
+  let priority: CandidateMetadata['priority'] = 'medium';
+  if (classification.category === 'bug-report' && (classification.confidence ?? 0) > 0.7) {
+    priority = 'high';
+  }
+  
+  // Deduplicate labels using Set for O(n) performance
+  const labels = [...new Set([classification.category, ...(classification.tags || [])].filter((label): label is string => label !== undefined))];
+  
+  return {
+    id: randomUUID(),
+    conversationId: conversation.id,
+    type,
+    title,
+    body,
+    metadata: {
+      priority,
+      labels,
+      source: {
+        conversationId: conversation.id,
+        timestamp: conversation.timestamp,
+      },
+    },
+    emitted: false,
+  };
+}
+
+/**
+ * Generate a title from content
+ */
+function generateTitle(content: string, category?: string): string {
+  // Take first line or first sentence, max 80 chars
+  const firstLine = content.split('\n')[0].trim();
+  const firstSentence = firstLine.split(/[.!?]/)[0].trim();
+  
+  let title = firstSentence.substring(0, 80);
+  if (firstSentence.length > 80) {
+    title += '...';
+  }
+  
+  // Add category prefix if available
+  if (category && category !== 'unknown') {
+    const prefix = category.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ');
+    title = `[${prefix}] ${title}`;
+  }
+  
+  return title;
+}
+
+/**
+ * Generate body from conversation
+ */
+function generateBody(conversation: Conversation): string {
+  const parts: string[] = [];
+  
+  // Add conversation summary
+  parts.push('## Conversation Summary\n');
+  
+  for (const turn of conversation.turns) {
+    const roleName = turn.role.charAt(0).toUpperCase() + turn.role.slice(1);
+    parts.push(`**${roleName}:**\n${turn.content}\n`);
+  }
+  
+  // Add metadata
+  if (conversation.classification) {
+    parts.push(`\n## Classification\n`);
+    parts.push(`- Category: ${conversation.classification.category}`);
+    parts.push(`- Confidence: ${(conversation.classification.confidence || 0).toFixed(2)}`);
+    if (conversation.classification.tags && conversation.classification.tags.length > 0) {
+      parts.push(`- Tags: ${conversation.classification.tags.join(', ')}`);
+    }
+  }
+  
+  parts.push(`\n---\n*Generated from conversation ${conversation.id}*`);
+  
+  return parts.join('\n');
+}

package/src/conversations/capture.ts

@@ -0,0 +1,56 @@
+/**
+ * Capture module for praxis-conversations
+ * Handles capturing conversations from various sources
+ */
+
+import type { Conversation } from './types.js';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Capture a conversation from raw input
+ */
+export function captureConversation(input: {
+  turns: Array<{ role: string; content: string; timestamp?: string }>;
+  metadata?: Record<string, unknown>;
+}): Conversation {
+  const now = new Date().toISOString();
+  
+  return {
+    id: randomUUID(),
+    timestamp: now,
+    turns: input.turns.map(turn => ({
+      role: turn.role as 'user' | 'assistant' | 'system',
+      content: turn.content,
+      timestamp: turn.timestamp || now,
+      metadata: {},
+    })),
+    metadata: {
+      source: (input.metadata?.source as string) || 'unknown',
+      userId: input.metadata?.userId as string,
+      sessionId: input.metadata?.sessionId as string,
+      tags: (input.metadata?.tags as string[]) || [],
+    },
+    redacted: false,
+    normalized: false,
+    classified: false,
+  };
+}
+
+/**
+ * Load a conversation from JSON
+ */
+export function loadConversation(json: string): Conversation {
+  const data = JSON.parse(json);
+  // Basic validation
+  if (!data.id || !data.timestamp || !data.turns || !data.metadata) {
+    throw new Error('Invalid conversation JSON: missing required fields');
+  }
+  return data as Conversation;
+}
+
+/**
+ * Serialize a conversation to JSON
+ */
+export function serializeConversation(conversation: Conversation): string {
+  return JSON.stringify(conversation, null, 2);
+}

package/src/conversations/classify.ts

@@ -0,0 +1,110 @@
+/**
+ * Classification module for praxis-conversations
+ * Handles deterministic classification of conversations (no LLM)
+ */
+
+import type { Conversation, Classification } from './types.js';
+
+/**
+ * Deterministic keyword-based classification rules
+ */
+const CLASSIFICATION_RULES = [
+  {
+    category: 'bug-report',
+    keywords: ['bug', 'error', 'crash', 'broken', 'issue', 'problem', 'fail', 'exception'],
+    weight: 1.0,
+  },
+  {
+    category: 'feature-request',
+    keywords: ['feature', 'enhancement', 'add', 'support', 'implement', 'would like', 'could you'],
+    weight: 1.0,
+  },
+  {
+    category: 'question',
+    keywords: ['how', 'what', 'why', 'when', 'where', '?', 'help', 'question'],
+    weight: 0.8,
+  },
+  {
+    category: 'documentation',
+    keywords: ['docs', 'documentation', 'readme', 'guide', 'tutorial', 'example'],
+    weight: 0.9,
+  },
+  {
+    category: 'performance',
+    keywords: ['slow', 'performance', 'optimize', 'speed', 'memory', 'cpu'],
+    weight: 1.0,
+  },
+];
+
+/**
+ * Extract keywords from text (simple tokenization)
+ */
+function extractKeywords(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/\s+/)
+    .map(word => word.replace(/[^\w]/g, ''))
+    .filter(word => word.length > 2);
+}
+
+/**
+ * Calculate classification scores for a conversation
+ */
+function calculateScores(conversation: Conversation): Record<string, number> {
+  const scores: Record<string, number> = {};
+  
+  // Combine all turn content
+  const allContent = conversation.turns
+    .map(t => t.content)
+    .join(' ');
+  
+  const keywords = extractKeywords(allContent);
+  const keywordSet = new Set(keywords);
+  
+  for (const rule of CLASSIFICATION_RULES) {
+    let matchCount = 0;
+    for (const keyword of rule.keywords) {
+      if (keywordSet.has(keyword.toLowerCase())) {
+        matchCount++;
+      }
+    }
+    
+    if (matchCount > 0) {
+      scores[rule.category] = (matchCount / rule.keywords.length) * rule.weight;
+    }
+  }
+  
+  return scores;
+}
+
+/**
+ * Classify a conversation using deterministic keyword matching
+ */
+export function classifyConversation(conversation: Conversation): Conversation {
+  const scores = calculateScores(conversation);
+  
+  // Find the highest scoring category
+  let bestCategory = 'unknown';
+  let bestScore = 0;
+  
+  for (const [category, score] of Object.entries(scores)) {
+    if (score > bestScore) {
+      bestScore = score;
+      bestCategory = category;
+    }
+  }
+  
+  const classification: Classification = {
+    category: bestCategory,
+    confidence: Math.min(bestScore, 1.0),
+    tags: Object.entries(scores)
+      .filter(([_, score]) => score > 0.3)
+      .map(([category]) => category),
+  };
+  
+  return {
+    ...conversation,
+    classification,
+    classified: true,
+  };
+}

package/src/conversations/conversation.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://praxis.dev/schemas/conversation.json",
+  "title": "Conversation",
+  "description": "Schema for a conversation in the praxis-conversations ingestion subsystem",
+  "type": "object",
+  "required": ["id", "timestamp", "turns", "metadata"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier for the conversation"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of conversation start"
+    },
+    "turns": {
+      "type": "array",
+      "description": "Array of conversation turns",
+      "items": {
+        "type": "object",
+        "required": ["role", "content", "timestamp"],
+        "properties": {
+          "role": {
+            "type": "string",
+            "enum": ["user", "assistant", "system"],
+            "description": "Role of the speaker"
+          },
+          "content": {
+            "type": "string",
+            "description": "Content of the turn"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp of the turn"
+          },
+          "metadata": {
+            "type": "object",
+            "description": "Optional metadata for the turn"
+          }
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Conversation metadata",
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "Source of the conversation (e.g., 'github-copilot', 'cli', 'web')"
+        },
+        "userId": {
+          "type": "string",
+          "description": "User identifier (may be redacted)"
+        },
+        "sessionId": {
+          "type": "string",
+          "description": "Session identifier"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tags for categorization"
+        }
+      }
+    },
+    "redacted": {
+      "type": "boolean",
+      "description": "Whether PII has been redacted",
+      "default": false
+    },
+    "normalized": {
+      "type": "boolean",
+      "description": "Whether the conversation has been normalized",
+      "default": false
+    },
+    "classified": {
+      "type": "boolean",
+      "description": "Whether the conversation has been classified",
+      "default": false
+    },
+    "classification": {
+      "type": "object",
+      "description": "Classification results",
+      "properties": {
+        "category": {
+          "type": "string",
+          "description": "Primary category (e.g., 'feature-request', 'bug-report', 'question')"
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Confidence score for classification"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Additional classification tags"
+        }
+      }
+    }
+  }
+}

package/src/conversations/emitters/fs.ts

@@ -0,0 +1,65 @@
+/**
+ * Filesystem emitter for praxis-conversations
+ * Emits candidates to the local filesystem
+ */
+
+import type { Candidate, FSEmitterOptions, EmissionResult } from '../types.js';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Emit a candidate to the filesystem
+ */
+export async function emitToFS(
+  candidate: Candidate,
+  options: FSEmitterOptions
+): Promise<Candidate> {
+  const { outputDir, dryRun = false } = options;
+  
+  if (dryRun) {
+    console.log(`[DRY RUN] Would emit candidate ${candidate.id} to ${outputDir}`);
+    return {
+      ...candidate,
+      emitted: true,
+      emissionResult: {
+        success: true,
+        timestamp: new Date().toISOString(),
+        externalId: `fs://${outputDir}/${candidate.id}.json`,
+      },
+    };
+  }
+  
+  try {
+    // Ensure output directory exists
+    await fs.mkdir(outputDir, { recursive: true });
+    
+    // Write candidate to file
+    const filename = `${candidate.id}.json`;
+    const filepath = path.join(outputDir, filename);
+    await fs.writeFile(filepath, JSON.stringify(candidate, null, 2), 'utf-8');
+    
+    const result: EmissionResult = {
+      success: true,
+      timestamp: new Date().toISOString(),
+      externalId: `fs://${filepath}`,
+    };
+    
+    return {
+      ...candidate,
+      emitted: true,
+      emissionResult: result,
+    };
+  } catch (error) {
+    const result: EmissionResult = {
+      success: false,
+      timestamp: new Date().toISOString(),
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+    
+    return {
+      ...candidate,
+      emitted: false,
+      emissionResult: result,
+    };
+  }
+}

package/src/conversations/emitters/github.ts

@@ -0,0 +1,115 @@
+/**
+ * GitHub emitter for praxis-conversations
+ * Emits candidates to GitHub as issues (HARD GATED by commit_intent=true)
+ */
+
+import type { Candidate, GitHubEmitterOptions, EmissionResult } from '../types.js';
+
+/**
+ * CRITICAL: GitHub emitter is HARD GATED by commit_intent=true
+ * This ensures no accidental issue creation
+ */
+export async function emitToGitHub(
+  candidate: Candidate,
+  options: GitHubEmitterOptions
+): Promise<Candidate> {
+  const { owner, repo, token, dryRun = false, commitIntent = false } = options;
+  
+  // HARD GATE: Must have commit_intent=true
+  if (!commitIntent) {
+    const result: EmissionResult = {
+      success: false,
+      timestamp: new Date().toISOString(),
+      error: 'GATE FAILURE: commit_intent must be explicitly set to true for GitHub emission',
+    };
+    
+    console.error(`[GATE BLOCKED] ${result.error}`);
+    
+    return {
+      ...candidate,
+      emitted: false,
+      emissionResult: result,
+    };
+  }
+  
+  if (dryRun) {
+    console.log(`[DRY RUN] Would create GitHub issue in ${owner}/${repo}`);
+    console.log(`Title: ${candidate.title}`);
+    console.log(`Labels: ${candidate.metadata.labels?.join(', ') || 'none'}`);
+    
+    return {
+      ...candidate,
+      emitted: true,
+      emissionResult: {
+        success: true,
+        timestamp: new Date().toISOString(),
+        externalId: `github://${owner}/${repo}/issues/DRY_RUN`,
+      },
+    };
+  }
+  
+  try {
+    // Validate required options
+    if (!owner || !repo) {
+      throw new Error('GitHub owner and repo are required');
+    }
+    
+    if (!token) {
+      throw new Error('GitHub token is required for emission');
+    }
+    
+    // Prepare issue data
+    const issueData = {
+      title: candidate.title,
+      body: candidate.body,
+      labels: candidate.metadata.labels || [],
+      assignees: candidate.metadata.assignees || [],
+    };
+    
+    // Make GitHub API call
+    const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `token ${token}`,
+        'Accept': 'application/vnd.github.v3+json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(issueData),
+    });
+    
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(`GitHub API error: ${errorData.message || response.statusText}`);
+    }
+    
+    const issue = await response.json() as { number: number; html_url: string };
+    
+    const result: EmissionResult = {
+      success: true,
+      timestamp: new Date().toISOString(),
+      externalId: `github://${owner}/${repo}/issues/${issue.number}`,
+    };
+    
+    console.log(`✓ Created GitHub issue #${issue.number}: ${issue.html_url}`);
+    
+    return {
+      ...candidate,
+      emitted: true,
+      emissionResult: result,
+    };
+  } catch (error) {
+    const result: EmissionResult = {
+      success: false,
+      timestamp: new Date().toISOString(),
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+    
+    console.error(`✗ Failed to create GitHub issue: ${result.error}`);
+    
+    return {
+      ...candidate,
+      emitted: false,
+      emissionResult: result,
+    };
+  }
+}

package/src/conversations/gate.ts

@@ -0,0 +1,102 @@
+/**
+ * Gating module for praxis-conversations
+ * Applies deterministic gates to candidates before emission
+ */
+
+import type { Candidate, GateStatus, GateResult } from './types.js';
+
+/**
+ * Gate: Minimum content length
+ */
+function gateMinimumLength(candidate: Candidate): GateResult {
+  const minLength = 50;
+  const passed = candidate.body.length >= minLength;
+  
+  return {
+    name: 'minimum-length',
+    passed,
+    message: passed 
+      ? 'Content meets minimum length requirement'
+      : `Content too short (${candidate.body.length} < ${minLength} chars)`,
+  };
+}
+
+/**
+ * Gate: Has valid title
+ */
+function gateValidTitle(candidate: Candidate): GateResult {
+  const passed = candidate.title.length > 10 && candidate.title.length < 200;
+  
+  return {
+    name: 'valid-title',
+    passed,
+    message: passed
+      ? 'Title is valid'
+      : 'Title length must be between 10 and 200 characters',
+  };
+}
+
+/**
+ * Gate: Not duplicate (simple check based on title)
+ * In production, this would check against existing issues
+ */
+function gateNotDuplicate(_candidate: Candidate): GateResult {
+  // For now, always pass - would implement duplicate detection in production
+  return {
+    name: 'not-duplicate',
+    passed: true,
+    message: 'Duplicate check passed (stub)',
+  };
+}
+
+/**
+ * Gate: Has metadata
+ */
+function gateHasMetadata(candidate: Candidate): GateResult {
+  const hasLabels = !!(candidate.metadata.labels && candidate.metadata.labels.length > 0);
+  const hasPriority = !!candidate.metadata.priority;
+  const passed: boolean = hasLabels && hasPriority;
+  
+  return {
+    name: 'has-metadata',
+    passed,
+    message: passed
+      ? 'Candidate has required metadata'
+      : 'Missing labels or priority in metadata',
+  };
+}
+
+/**
+ * Apply all gates to a candidate
+ */
+export function applyGates(candidate: Candidate): Candidate {
+  const gates: GateResult[] = [
+    gateMinimumLength(candidate),
+    gateValidTitle(candidate),
+    gateNotDuplicate(candidate),
+    gateHasMetadata(candidate),
+  ];
+  
+  const allPassed = gates.every(g => g.passed);
+  const failedGates = gates.filter(g => !g.passed);
+  
+  const gateStatus: GateStatus = {
+    passed: allPassed,
+    reason: allPassed 
+      ? 'All gates passed'
+      : `Failed gates: ${failedGates.map(g => g.name).join(', ')}`,
+    gates,
+  };
+  
+  return {
+    ...candidate,
+    gateStatus,
+  };
+}
+
+/**
+ * Check if a candidate passed all gates
+ */
+export function candidatePassed(candidate: Candidate): boolean {
+  return candidate.gateStatus?.passed || false;
+}

package/src/conversations/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Praxis Conversations Subsystem
+ * 
+ * Deterministic-first conversation ingestion pipeline:
+ * capture -> redact -> normalize -> classify -> candidates -> gate -> emit
+ */
+
+export * from './types.js';
+export * from './capture.js';
+export * from './redact.js';
+export * from './normalize.js';
+export * from './classify.js';
+export * from './candidates.js';
+export * from './gate.js';
+
+// Emitters
+export * from './emitters/fs.js';
+export * from './emitters/github.js';
+
+// Re-export main pipeline functions
+export { captureConversation, loadConversation, serializeConversation } from './capture.js';
+export { redactConversation, redactText } from './redact.js';
+export { normalizeConversation } from './normalize.js';
+export { classifyConversation } from './classify.js';
+export { generateCandidate } from './candidates.js';
+export { applyGates, candidatePassed } from './gate.js';
+export { emitToFS } from './emitters/fs.js';
+export { emitToGitHub } from './emitters/github.js';