darwin-agents 0.4.4

package/dist/types.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Darwin — Core Types
+ *
+ * Self-Evolving AI Agent Framework.
+ * Types for agents, experiments, memory, and evolution.
+ */
+export interface AgentDefinition {
+    /** Unique agent name (lowercase, no spaces) */
+    name: string;
+    /** Human-readable role description */
+    role: string;
+    /** What this agent does */
+    description: string;
+    /** System prompt — the core of what Darwin evolves */
+    systemPrompt: string;
+    /** MCP servers this agent needs */
+    mcp?: string[];
+    /** Built-in tools to allow (Read, Glob, Grep, etc.) */
+    tools?: string[];
+    /** Max conversation turns per run */
+    maxTurns?: number;
+    /** LLM model to use */
+    model?: string;
+    /** Agent type: 'llm' (default) or 'system' (no LLM, pure code) */
+    type?: 'llm' | 'system';
+    /** System agent handler (only for type: 'system') */
+    handler?: (ctx: SystemAgentContext) => Promise<Record<string, unknown>>;
+    /** Darwin evolution config (opt-in) */
+    evolution?: EvolutionConfig;
+}
+export interface SystemAgentContext {
+    memory: MemoryProvider;
+    config: DarwinConfig;
+}
+export interface EvolutionConfig {
+    /** Enable evolution for this agent */
+    enabled: boolean;
+    /** Agent to use as evaluator (default: 'critic') */
+    evaluator?: string;
+    /** Custom metric weights */
+    metrics?: MetricWeights;
+    /** Minimum runs before first optimization */
+    minRuns?: number;
+    /** Minimum output length to save (default: 2000). Lower for short-form agents like marketing. */
+    minOutputLength?: number;
+}
+export interface McpServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface DarwinConfig {
+    /** LLM provider */
+    provider: 'claude-cli' | 'anthropic-api' | 'openai' | 'ollama';
+    /** Memory backend */
+    memory: 'sqlite' | 'postgres' | 'custom';
+    /** Postgres connection string (only for memory: 'postgres') */
+    postgresUrl?: string;
+    /** Custom memory provider (only for memory: 'custom') */
+    memoryProvider?: MemoryProvider;
+    /** MCP server configurations */
+    mcp?: Record<string, McpServerConfig>;
+    /** Global evolution settings */
+    evolution?: {
+        enabled: boolean;
+        minRuns?: number;
+        safetyGate?: boolean;
+    };
+    /** Working directory for .darwin/ data */
+    dataDir?: string;
+}
+export interface DarwinMetrics {
+    /** Quality score from evaluator (1-10) */
+    qualityScore: number | null;
+    /** Number of sources cited */
+    sourceCount: number;
+    /** Character length of output */
+    outputLength: number;
+    /** Errors encountered */
+    errorCount: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+export interface DarwinExperiment {
+    /** Unique ID: exp-{agent}-{YYYY-MM-DD}-{NNN} */
+    id: string;
+    /** Agent name */
+    agentName: string;
+    /** Prompt version used */
+    promptVersion: string;
+    /** The task given */
+    task: string;
+    /** Task category (tech, webdesign, market, etc.) */
+    taskType: string;
+    /** ISO timestamp of start */
+    startedAt: string;
+    /** ISO timestamp of completion */
+    completedAt: string;
+    /** Whether the agent completed successfully */
+    success: boolean;
+    /** Measured metrics */
+    metrics: DarwinMetrics;
+    /** Critic feedback */
+    feedback?: ExperimentFeedback;
+    /** Raw agent output */
+    output?: string;
+}
+export interface ExperimentFeedback {
+    /** Critic score (1-10) */
+    score: number;
+    /** Critic report text */
+    report: string;
+    /** Who evaluated (agent name or 'user') */
+    evaluator: string;
+}
+export interface PromptVersion {
+    /** Version identifier: v1, v2, ... */
+    version: string;
+    /** Agent name */
+    agentName: string;
+    /** The full prompt text */
+    promptText: string;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** Parent version (null for initial) */
+    parentVersion: string | null;
+    /** Why this version was created */
+    changeReason: string;
+    /** Whether this is the active version */
+    active: boolean;
+    /** Aggregated stats */
+    stats: PromptVersionStats;
+}
+export interface PromptVersionStats {
+    totalRuns: number;
+    avgQuality: number;
+    avgDuration: number;
+    successRate: number;
+    avgSourceCount: number;
+}
+export interface ABTest {
+    versionA: string;
+    versionB: string;
+    runsA: number;
+    runsB: number;
+    /** Incomplete/failed runs per version (not counted in runsA/runsB) */
+    failsA: number;
+    failsB: number;
+    minRuns: number;
+    startedAt: string;
+}
+export interface DarwinState {
+    /** Active prompt version per agent */
+    activeVersions: Record<string, string>;
+    /** Active A/B test per agent */
+    abTests: Record<string, ABTest | null>;
+    /** Last known-good version per agent */
+    lastKnownGood: Record<string, string>;
+    /** Consecutive failure count per agent */
+    consecutiveFailures: Record<string, number>;
+    /** Total experiment count per agent */
+    experimentCounts: Record<string, number>;
+}
+export interface DarwinPattern {
+    description: string;
+    confidence: number;
+    evidence: number;
+    type: 'strength' | 'weakness' | 'trend' | 'anomaly';
+    suggestion: string;
+    taskType?: string;
+}
+export interface MetricWeights {
+    quality: number;
+    sourceCount: number;
+    outputLength: number;
+    duration: number;
+    success: number;
+}
+export declare const DEFAULT_WEIGHTS: MetricWeights;
+export interface SafetyThresholds {
+    minDataPoints: number;
+    maxRegression: number;
+    failureRollbackThreshold: number;
+}
+export declare const DEFAULT_SAFETY: SafetyThresholds;
+export interface MemoryProvider {
+    saveExperiment(exp: DarwinExperiment): Promise<void>;
+    loadExperiments(agentName: string, limit?: number): Promise<DarwinExperiment[]>;
+    savePromptVersion(pv: PromptVersion): Promise<void>;
+    getActivePrompt(agentName: string): Promise<PromptVersion | null>;
+    getAllPromptVersions(agentName: string): Promise<PromptVersion[]>;
+    saveLearning(learning: Learning): Promise<void>;
+    searchLearnings(query: string, limit?: number): Promise<Learning[]>;
+    getState(): Promise<DarwinState>;
+    saveState(state: DarwinState): Promise<void>;
+    /** Atomically read-modify-write the state (prevents race conditions) */
+    updateState(fn: (state: DarwinState) => DarwinState): Promise<DarwinState>;
+    init(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface Learning {
+    id?: string;
+    agentName: string;
+    content: string;
+    category: 'pattern' | 'mistake' | 'insight' | 'optimization';
+    tags: string[];
+    createdAt?: string;
+    confidence?: number;
+}
+export interface RunResult {
+    experiment: DarwinExperiment;
+    output: string;
+    reportPath?: string;
+    evolution?: {
+        patternsFound: DarwinPattern[];
+        promptEvolved: boolean;
+        abTestStarted: boolean;
+        newVersion?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * Darwin — Core Types
+ *
+ * Self-Evolving AI Agent Framework.
+ * Types for agents, experiments, memory, and evolution.
+ */
+export const DEFAULT_WEIGHTS = {
+    quality: 0.40,
+    sourceCount: 0.15,
+    outputLength: 0.10,
+    duration: 0.10,
+    success: 0.25,
+};
+export const DEFAULT_SAFETY = {
+    minDataPoints: 10,
+    maxRegression: 0.20,
+    failureRollbackThreshold: 3,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0MH,MAAM,CAAC,MAAM,eAAe,GAAkB;IAC5C,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,IAAI;IAClB,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,IAAI;CACd,CAAC;AAUF,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,aAAa,EAAE,EAAE;IACjB,aAAa,EAAE,IAAI;IACnB,wBAAwB,EAAE,CAAC;CAC5B,CAAC"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "darwin-agents",
+  "version": "0.4.4",
+  "description": "AI agents that improve themselves. Self-evolving prompts via A/B testing, multi-model critics, safety gates, and pattern detection.",
+  "type": "module",
+  "bin": {
+    "darwin": "./dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./providers": {
+      "import": "./dist/providers/index.js",
+      "types": "./dist/providers/index.d.ts"
+    },
+    "./memory": {
+      "import": "./dist/memory/index.js",
+      "types": "./dist/memory/index.d.ts"
+    },
+    "./agents": {
+      "import": "./dist/agents/index.js",
+      "types": "./dist/agents/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "darwin": "tsx src/cli/index.ts",
+    "test": "tsx --test tests/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "better-sqlite3": "^11.0.0",
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": { "optional": true },
+    "pg": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "self-evolving",
+    "darwin",
+    "claude",
+    "openai",
+    "gpt",
+    "mcp",
+    "prompt-optimization",
+    "ab-testing",
+    "multi-model",
+    "llm",
+    "evolution"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/studiomeyer-io/darwin-agents"
+  },
+  "author": "StudioMeyer <hello@studiomeyer.de>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}