conatus 0.1.0

package/dist/strategy/strategy-template-registry.js

@@ -0,0 +1,350 @@
+import { randomUUID } from "node:crypto";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { z } from "zod";
+import { ValidationError } from "../utils/errors.js";
+import { StrategyTemplateSchema } from "../types/cross-portfolio.js";
+import { StrategySchema } from "../types/strategy.js";
+// ─── LLM Response Schemas ───
+const GeneralizeHypothesisResponseSchema = z.object({
+    hypothesis_pattern: z.string(),
+    domain_tags: z.array(z.string()),
+    applicable_dimensions: z.array(z.string()),
+});
+const AdaptTemplateResponseSchema = z.object({
+    hypothesis: z.string(),
+    target_dimensions: z.array(z.string()),
+    expected_effect: z.array(z.object({
+        dimension: z.string(),
+        direction: z.enum(["increase", "decrease"]),
+        magnitude: z.enum(["small", "medium", "large"]),
+    })),
+});
+// ─── StrategyTemplateRegistry ───
+/**
+ * StrategyTemplateRegistry manages successful strategy templates for cross-goal reuse.
+ *
+ * It stores templates derived from completed strategies, generates semantic embeddings
+ * for semantic search, and can adapt templates to new goal contexts.
+ *
+ * Persistence: {basePath}/strategy-templates.json
+ */
+export class StrategyTemplateRegistry {
+    llmClient;
+    vectorIndex;
+    embeddingClient;
+    basePath;
+    promptGateway;
+    templates = new Map();
+    persistPath;
+    logger;
+    constructor(llmClient, vectorIndex, embeddingClient, basePath, logger, promptGateway) {
+        this.llmClient = llmClient;
+        this.vectorIndex = vectorIndex;
+        this.embeddingClient = embeddingClient;
+        this.basePath = basePath;
+        this.promptGateway = promptGateway;
+        this.persistPath = path.join(basePath, "strategy-templates.json");
+        this.logger = logger;
+    }
+    /**
+     * Register a completed, effective strategy as a reusable template.
+     * Preconditions: strategy.state === "completed" AND effectiveness_score >= 0.5
+     */
+    async registerTemplate(strategy, goalId) {
+        if (strategy.state !== "completed") {
+            throw new ValidationError(`Cannot register template: strategy state is "${strategy.state}", expected "completed"`);
+        }
+        if (strategy.effectiveness_score === null ||
+            strategy.effectiveness_score < 0.5) {
+            throw new ValidationError(`Cannot register template: effectiveness_score is ${strategy.effectiveness_score ?? "null"}, must be >= 0.5`);
+        }
+        // Ask LLM to generalize the hypothesis into a reusable pattern
+        const generalizePrompt = [
+            "Generalize this successful strategy hypothesis into a reusable pattern.",
+            "Remove domain-specific details and keep the core approach.",
+            "",
+            `Hypothesis: ${strategy.hypothesis}`,
+            `Target dimensions: ${strategy.target_dimensions.join(", ")}`,
+            `Expected effects: ${JSON.stringify(strategy.expected_effect)}`,
+            "",
+            'Output JSON: { "hypothesis_pattern": string, "domain_tags": string[], "applicable_dimensions": string[] }',
+        ].join("\n");
+        let generalized;
+        if (this.promptGateway) {
+            generalized = await this.promptGateway.execute({
+                purpose: "strategy_generation",
+                goalId,
+                additionalContext: { generalize_prompt: generalizePrompt },
+                responseSchema: GeneralizeHypothesisResponseSchema,
+            });
+        }
+        else {
+            const llmResponse = await this.llmClient.sendMessage([
+                { role: "user", content: generalizePrompt },
+            ]);
+            generalized = this.llmClient.parseJSON(llmResponse.content, GeneralizeHypothesisResponseSchema);
+        }
+        // Create a VectorIndex entry for semantic search
+        const embeddingId = `tmpl-emb-${randomUUID()}`;
+        await this.vectorIndex.add(embeddingId, generalized.hypothesis_pattern, {
+            template_type: "strategy-template",
+            domain_tags: generalized.domain_tags,
+            applicable_dimensions: generalized.applicable_dimensions,
+            source_goal_id: goalId,
+            source_strategy_id: strategy.id,
+        });
+        // Create the StrategyTemplate object
+        const template = StrategyTemplateSchema.parse({
+            template_id: `tmpl-${randomUUID()}`,
+            source_goal_id: goalId,
+            source_strategy_id: strategy.id,
+            hypothesis_pattern: generalized.hypothesis_pattern,
+            domain_tags: generalized.domain_tags,
+            effectiveness_score: strategy.effectiveness_score,
+            applicable_dimensions: generalized.applicable_dimensions,
+            embedding_id: embeddingId,
+            created_at: new Date().toISOString(),
+        });
+        this.templates.set(template.template_id, template);
+        await this.save();
+        return template;
+    }
+    /**
+     * Search templates by semantic similarity.
+     * Optionally filter by domain tags (at least one tag must overlap).
+     */
+    async searchTemplates(query, limit = 5, domainTags) {
+        if (this.templates.size === 0) {
+            return [];
+        }
+        // Generate embedding for query and search VectorIndex
+        const queryVector = await this.embeddingClient.embed(query);
+        const searchResults = this.vectorIndex.searchByVector(queryVector, this.templates.size // fetch all, we'll slice after filtering
+        );
+        // Map results to StrategyTemplate objects, filtering by domain tags if needed
+        const matched = [];
+        for (const result of searchResults) {
+            // Each VectorIndex entry has the embeddingId as its id
+            // Find the template that references this embeddingId
+            const template = this._findTemplateByEmbeddingId(result.id);
+            if (!template)
+                continue;
+            // Filter by domain tags if specified
+            if (domainTags && domainTags.length > 0) {
+                const overlap = template.domain_tags.some((tag) => domainTags.includes(tag));
+                if (!overlap)
+                    continue;
+            }
+            matched.push({ template, similarity: result.similarity });
+        }
+        // Sort by similarity descending (searchByVector already sorts, but re-sort after filtering)
+        matched.sort((a, b) => b.similarity - a.similarity);
+        return matched.slice(0, limit).map((m) => m.template);
+    }
+    /**
+     * Adapt a template to a new goal context, generating a concrete Strategy.
+     * The caller is responsible for persisting the returned Strategy.
+     */
+    async applyTemplate(templateId, goalId, goalContext) {
+        const template = this.templates.get(templateId);
+        if (!template) {
+            throw new Error(`Template not found: ${templateId}`);
+        }
+        // Ask LLM to adapt the template to the new goal context
+        const adaptPrompt = [
+            "Adapt this strategy template to the following goal context.",
+            "Create a concrete strategy hypothesis.",
+            "",
+            `Template hypothesis pattern: ${template.hypothesis_pattern}`,
+            `Applicable dimensions: ${template.applicable_dimensions.join(", ")}`,
+            `Goal context: ${goalContext}`,
+            "",
+            'Output JSON: { "hypothesis": string, "target_dimensions": string[], "expected_effect": Array<{ "dimension": string, "direction": "increase"|"decrease", "magnitude": "small"|"medium"|"large" }> }',
+        ].join("\n");
+        let adapted;
+        if (this.promptGateway) {
+            adapted = await this.promptGateway.execute({
+                purpose: "strategy_generation",
+                goalId,
+                additionalContext: { adapt_prompt: adaptPrompt },
+                responseSchema: AdaptTemplateResponseSchema,
+            });
+        }
+        else {
+            const llmResponse = await this.llmClient.sendMessage([
+                { role: "user", content: adaptPrompt },
+            ]);
+            adapted = this.llmClient.parseJSON(llmResponse.content, AdaptTemplateResponseSchema);
+        }
+        // Create a new Strategy object
+        const now = new Date().toISOString();
+        const strategy = StrategySchema.parse({
+            id: `strat-${randomUUID()}`,
+            goal_id: goalId,
+            target_dimensions: adapted.target_dimensions,
+            primary_dimension: adapted.target_dimensions[0] ?? "default",
+            hypothesis: adapted.hypothesis,
+            expected_effect: adapted.expected_effect,
+            resource_estimate: {
+                sessions: 1,
+                duration: { unit: "hours", value: 1 },
+                llm_calls: null,
+            },
+            state: "candidate",
+            allocation: 0,
+            created_at: now,
+            started_at: null,
+            completed_at: null,
+            gap_snapshot_at_start: null,
+            tasks_generated: [],
+            effectiveness_score: null,
+            consecutive_stall_count: 0,
+            source_template_id: templateId,
+            cross_goal_context: goalContext,
+        });
+        return strategy;
+    }
+    /**
+     * Index all registered templates into a VectorIndex using the provided embedding client.
+     * Each template's hypothesis_pattern is embedded and stored with its template_id as metadata.
+     * Call this once after loading templates to enable recommendByEmbedding() / recommendHybrid().
+     */
+    async indexTemplates(embeddingClient, vectorIndex) {
+        for (const template of this.templates.values()) {
+            const indexId = `idx-${template.template_id}`;
+            await vectorIndex.add(indexId, template.hypothesis_pattern, {
+                template_id: template.template_id,
+                domain_tags: template.domain_tags,
+            });
+        }
+    }
+    /**
+     * Recommend templates for a goal description using semantic embedding similarity.
+     * Searches the provided VectorIndex for the top-K closest templates.
+     * Returns EmbeddingRecommendation[] sorted by similarity descending.
+     */
+    async recommendByEmbedding(goalDescription, embeddingClient, vectorIndex, topK = 5) {
+        if (this.templates.size === 0) {
+            return [];
+        }
+        const queryVector = await embeddingClient.embed(goalDescription);
+        const searchResults = vectorIndex.searchByVector(queryVector, topK);
+        const recommendations = [];
+        for (const result of searchResults) {
+            // Each indexed entry stores template_id in metadata
+            const templateId = result.metadata?.["template_id"];
+            if (!templateId)
+                continue;
+            const template = this.templates.get(templateId);
+            if (!template)
+                continue;
+            recommendations.push({
+                templateId,
+                similarity: result.similarity,
+                matchReason: `Semantic similarity to hypothesis pattern: "${template.hypothesis_pattern}"`,
+            });
+        }
+        return recommendations;
+    }
+    /**
+     * Hybrid recommendation combining tag-based matching with embedding similarity.
+     * tagScore: fraction of goal tags that overlap with template domain_tags (0 if no tags supplied).
+     * embeddingScore: cosine similarity from VectorIndex.
+     * combinedScore: tagWeight * tagScore + embeddingWeight * embeddingScore (default 0.4 / 0.6).
+     * Returns HybridRecommendation[] sorted by combinedScore descending.
+     */
+    async recommendHybrid(goalDescription, goalTags, embeddingClient, vectorIndex, options = {}) {
+        const { tagWeight = 0.4, embeddingWeight = 0.6, topK = 5, } = options;
+        if (this.templates.size === 0) {
+            return [];
+        }
+        // Get embedding scores for all templates (fetch all, we slice after combining)
+        const queryVector = await embeddingClient.embed(goalDescription);
+        const searchResults = vectorIndex.searchByVector(queryVector, this.templates.size);
+        // Build a lookup from templateId → embedding similarity
+        const embeddingMap = new Map();
+        for (const result of searchResults) {
+            const templateId = result.metadata?.["template_id"];
+            if (templateId) {
+                embeddingMap.set(templateId, result.similarity);
+            }
+        }
+        const hybrid = [];
+        for (const template of this.templates.values()) {
+            // Tag score: fraction of goal tags present in template domain_tags
+            let tagScore = 0;
+            if (goalTags.length > 0 && template.domain_tags.length > 0) {
+                const matchCount = goalTags.filter((t) => template.domain_tags.includes(t)).length;
+                tagScore = matchCount / goalTags.length;
+            }
+            const embeddingScore = embeddingMap.get(template.template_id) ?? 0;
+            const combinedScore = tagWeight * tagScore + embeddingWeight * embeddingScore;
+            hybrid.push({
+                templateId: template.template_id,
+                tagScore,
+                embeddingScore,
+                combinedScore,
+            });
+        }
+        hybrid.sort((a, b) => b.combinedScore - a.combinedScore);
+        return hybrid.slice(0, topK);
+    }
+    /**
+     * Persist all templates to JSON file (atomic write).
+     */
+    async save() {
+        const dir = path.dirname(this.persistPath);
+        await fsp.mkdir(dir, { recursive: true });
+        const data = JSON.stringify(Array.from(this.templates.values()), null, 2);
+        const tmpPath = `${this.persistPath}.tmp`;
+        await fsp.writeFile(tmpPath, data, "utf-8");
+        await fsp.rename(tmpPath, this.persistPath);
+    }
+    /**
+     * Load templates from JSON file.
+     * Silently succeeds if the file does not exist.
+     */
+    async load() {
+        try {
+            await fsp.access(this.persistPath);
+        }
+        catch {
+            return;
+        }
+        try {
+            const raw = await fsp.readFile(this.persistPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            this.templates.clear();
+            for (const item of parsed) {
+                const template = StrategyTemplateSchema.parse(item);
+                this.templates.set(template.template_id, template);
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`[StrategyTemplateRegistry] Failed to load templates from ${this.persistPath}, starting fresh: ${err}`);
+        }
+    }
+    /**
+     * Return the number of templates currently in the registry.
+     */
+    get size() {
+        return this.templates.size;
+    }
+    /**
+     * Retrieve a template by ID. Returns undefined if not found.
+     */
+    getTemplate(templateId) {
+        return this.templates.get(templateId);
+    }
+    // ─── Private Helpers ───
+    _findTemplateByEmbeddingId(embeddingId) {
+        for (const template of this.templates.values()) {
+            if (template.embedding_id === embeddingId) {
+                return template;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=strategy-template-registry.js.map

package/dist/strategy/strategy-template-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-template-registry.js","sourceRoot":"","sources":["../../src/strategy/strategy-template-registry.ts"],"names":[],"mappings":"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"}

package/dist/strategy-manager.d.ts

@@ -0,0 +1,128 @@
+import { StateManager } from "./state-manager.js";
+import type { Strategy, Portfolio } from "./types/strategy.js";
+import type { StrategyState } from "./types/core.js";
+import type { ILLMClient } from "./llm/llm-client.js";
+import type { KnowledgeGapSignal } from "./types/knowledge.js";
+/**
+ * StrategyManager manages strategy lifecycle for a goal:
+ * - LLM-driven candidate generation
+ * - State transitions (candidate → active → completed/terminated/evaluating)
+ * - Stall-driven pivots
+ *
+ * Persistence paths (relative to StateManager base):
+ *   strategies/<goal_id>/portfolio.json
+ *   strategies/<goal_id>/strategy-history.json
+ *
+ * In-memory index: strategyId → goalId for fast lookups without directory scanning.
+ */
+export declare class StrategyManager {
+    private readonly stateManager;
+    private readonly llmClient;
+    /** In-memory index: strategyId → goalId */
+    private readonly strategyIndex;
+    constructor(stateManager: StateManager, llmClient: ILLMClient);
+    /**
+     * Generate 1–2 strategy candidates via LLM.
+     * Validates each with StrategySchema, sets state="candidate", stores in portfolio.
+     */
+    generateCandidates(goalId: string, primaryDimension: string, targetDimensions: string[], context: {
+        currentGap: number;
+        pastStrategies: Strategy[];
+    }): Promise<Strategy[]>;
+    /**
+     * Activate the first candidate strategy for a goal.
+     * Sets state="active" and started_at=now.
+     */
+    activateBestCandidate(goalId: string): Promise<Strategy>;
+    /**
+     * Transition a strategy to a new state.
+     * Throws if the transition is not valid or strategy is not found.
+     */
+    updateState(strategyId: string, newState: StrategyState, metadata?: {
+        effectiveness_score?: number;
+    }): void;
+    /**
+     * React to a stall detection event.
+     * - stallCount === 1: return null (no strategy change; notify only)
+     * - stallCount >= 2: terminate current strategy, generate new candidates, activate best
+     * - If no candidates can be generated: return null
+     */
+    onStallDetected(goalId: string, stallCount: number): Promise<Strategy | null>;
+    /**
+     * Returns the currently active strategy for a goal, or null.
+     */
+    getActiveStrategy(goalId: string): Strategy | null;
+    /**
+     * Returns the full portfolio for a goal, or null if none has been persisted.
+     */
+    getPortfolio(goalId: string): Portfolio | null;
+    /**
+     * Returns all strategies in history (terminated/completed) for a goal.
+     */
+    getStrategyHistory(goalId: string): Strategy[];
+    /**
+     * Activate multiple candidate strategies simultaneously (Phase 2 parallel execution).
+     * Allocates resources equally, respecting min=0.1 and max=0.7 per strategy.
+     * Single strategy receives allocation=1.0.
+     */
+    activateMultiple(goalId: string, strategyIds: string[]): Strategy[];
+    /**
+     * Terminate a strategy and redistribute its allocation to remaining active strategies
+     * proportionally. If no remaining active strategies, allocation is not redistributed.
+     */
+    terminateStrategy(goalId: string, strategyId: string, reason: string): Strategy;
+    /**
+     * Create a WaitStrategy for a goal.
+     * Sets state="candidate" initially; caller activates when ready.
+     */
+    createWaitStrategy(goalId: string, params: {
+        hypothesis: string;
+        wait_reason: string;
+        wait_until: string;
+        measurement_plan: string;
+        fallback_strategy_id: string | null;
+        target_dimensions: string[];
+        primary_dimension: string;
+    }): Strategy;
+    /**
+     * Suspend an active strategy, redistributing its allocation to remaining active strategies.
+     */
+    suspendStrategy(goalId: string, strategyId: string): Strategy;
+    /**
+     * Resume a suspended strategy at the given allocation.
+     * Adjusts other active strategies proportionally to maintain sum=1.0.
+     */
+    resumeStrategy(goalId: string, strategyId: string, allocation: number): Strategy;
+    /**
+     * Return all strategies with state "active" or "evaluating" for a goal.
+     * Unlike getActiveStrategy, returns all concurrent active strategies.
+     */
+    getAllActiveStrategies(goalId: string): Strategy[];
+    /**
+     * Update a single strategy's allocation directly.
+     * Does NOT validate that the sum of all allocations equals 1.0;
+     * the caller (e.g., PortfolioManager) is responsible for maintaining that invariant.
+     */
+    updateAllocation(goalId: string, strategyId: string, newAllocation: number): void;
+    /**
+     * Detect whether a set of strategy candidates indicates a knowledge gap.
+     *
+     * Rules:
+     *   - Zero candidates → `strategy_deadlock` (no hypotheses can be formed)
+     *   - All candidates have effectiveness_score < 0.3 AND not null →
+     *     `strategy_deadlock` (all known approaches exhausted)
+     *
+     * Returns null when candidates look viable.
+     */
+    detectStrategyGap(candidates: Strategy[]): KnowledgeGapSignal | null;
+    private loadOrCreatePortfolio;
+    private savePortfolio;
+    private appendToHistory;
+    /**
+     * Resolve a goalId from a strategyId using the in-memory index.
+     * Falls back to scanning goal directories if not in index.
+     */
+    private resolveGoalId;
+    private buildGenerationPrompt;
+}
+//# sourceMappingURL=strategy-manager.d.ts.map

package/dist/strategy-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-manager.d.ts","sourceRoot":"","sources":["../src/strategy-manager.ts"],"names":[],"mappings":"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"}