@pga-ai/core 0.4.0

package/README.md

@@ -0,0 +1,278 @@
+# @pga-ai/core
+
+> 🧬 **Genomic Self-Evolving Prompts** — Core Engine
+
+[![npm version](https://img.shields.io/npm/v/@pga-ai/core)](https://www.npmjs.com/package/@pga-ai/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Created by Luis Alfredo Velasquez Duran | Germany, 2025**
+
+---
+
+## What is @pga-ai/core?
+
+The core engine for PGA (Genomic Self-Evolving Prompts) — the world's first system that makes AI prompts **evolve automatically** like biological organisms.
+
+Instead of manually tweaking prompts, PGA:
+- ✅ Learns from every interaction
+- ✅ Adapts to each user uniquely
+- ✅ Improves continuously (autonomous)
+- ✅ Never degrades (immune system)
+- ✅ Tests changes before deployment (sandbox)
+
+## Installation
+
+```bash
+npm install @pga-ai/core
+```
+
+You'll also need adapters for your LLM and database:
+
+```bash
+npm install @pga-ai/adapters-llm @pga-ai/adapters-storage
+```
+
+## Quick Start
+
+```typescript
+import { PGA } from '@pga-ai/core';
+import { ClaudeAdapter } from '@pga-ai/adapters-llm/anthropic';
+import { PostgresAdapter } from '@pga-ai/adapters-storage/postgres';
+
+// 1. Initialize PGA
+const pga = new PGA({
+  llm: new ClaudeAdapter({
+    apiKey: process.env.ANTHROPIC_KEY,
+  }),
+  storage: new PostgresAdapter({
+    connectionString: process.env.DATABASE_URL,
+  }),
+});
+
+await pga.initialize();
+
+// 2. Create genome
+const genome = await pga.createGenome({
+  name: 'my-assistant',
+});
+
+// 3. Use in your agent loop
+async function chat(userId: string, message: string) {
+  const response = await genome.chat(message, { userId });
+  return response;
+}
+
+// 4. PGA learns automatically from interactions
+await genome.recordInteraction({
+  userId: 'user123',
+  userMessage: 'Hello!',
+  assistantResponse: 'Hi there!',
+  toolCalls: [],
+  score: 0.9,
+  timestamp: new Date(),
+});
+```
+
+That's it! Your agent now evolves automatically.
+
+## Core Concepts
+
+### Three-Layer Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  Layer 0: Immutable DNA                 │
+│  Security, Ethics, Core Identity        │
+│  🚫 NEVER mutates                       │
+├─────────────────────────────────────────┤
+│  Layer 1: Operative Genes               │
+│  Tool Usage, Coding Patterns            │
+│  🐢 SLOW mutation (high validation)    │
+├─────────────────────────────────────────┤
+│  Layer 2: Epigenomes                    │
+│  User Preferences, Communication Style  │
+│  ⚡ FAST mutation (daily adaptation)    │
+└─────────────────────────────────────────┘
+```
+
+### User DNA Profiling
+
+Each user gets a unique cognitive profile:
+
+```typescript
+const dna = await genome.getDNA('user123');
+
+console.log(dna.traits);
+// {
+//   communicationStyle: 'technical',
+//   verbosity: 'terse',
+//   preferredTools: ['browser', 'code'],
+//   domainExpertise: { 'coding': 0.9 }
+// }
+```
+
+### Automatic Evolution
+
+PGA evolves through a 4-phase cycle:
+
+1. **Transcription**: Log every interaction
+2. **Variation**: Generate mutations
+3. **Simulation**: Test in sandbox
+4. **Selection**: Deploy only improvements
+
+## API Reference
+
+### PGA Class
+
+#### `new PGA(config)`
+
+Create PGA instance.
+
+```typescript
+const pga = new PGA({
+  llm: new ClaudeAdapter({ apiKey: '...' }),
+  storage: new PostgresAdapter({ connectionString: '...' }),
+  config: {
+    enableSandbox: true,      // Test mutations before deploy
+    mutationRate: 'balanced',  // 'slow' | 'balanced' | 'aggressive'
+  },
+});
+```
+
+#### `pga.initialize()`
+
+Initialize storage (create tables, etc.).
+
+```typescript
+await pga.initialize();
+```
+
+#### `pga.createGenome(options)`
+
+Create new genome.
+
+```typescript
+const genome = await pga.createGenome({
+  name: 'my-assistant',
+  config: {
+    enableSandbox: true,
+    mutationRate: 'balanced',
+  },
+});
+```
+
+### GenomeInstance Class
+
+#### `genome.assemblePrompt(context)`
+
+Get optimized prompt for current context.
+
+```typescript
+const prompt = await genome.assemblePrompt({
+  userId: 'user123',
+  taskType: 'coding',
+});
+```
+
+#### `genome.chat(message, context)`
+
+Chat with PGA optimization.
+
+```typescript
+const response = await genome.chat('Hello!', {
+  userId: 'user123',
+});
+```
+
+#### `genome.recordInteraction(interaction)`
+
+Record interaction (enables learning).
+
+```typescript
+await genome.recordInteraction({
+  userId: 'user123',
+  userMessage: 'Fix this bug',
+  assistantResponse: 'Bug fixed!',
+  toolCalls: [],
+  score: 0.95,
+  timestamp: new Date(),
+});
+```
+
+#### `genome.getDNA(userId)`
+
+Get user's DNA profile.
+
+```typescript
+const dna = await genome.getDNA('user123');
+```
+
+#### `genome.recordFeedback(userId, gene, sentiment)`
+
+Record user feedback.
+
+```typescript
+await genome.recordFeedback('user123', 'communication-style', 'positive');
+```
+
+## Adapters
+
+### LLM Adapters
+
+Implement `LLMAdapter` interface:
+
+```typescript
+import type { LLMAdapter } from '@pga-ai/core';
+
+export class MyLLMAdapter implements LLMAdapter {
+  readonly name = 'my-llm';
+  readonly model = 'my-model-v1';
+
+  async chat(messages, options) {
+    // Your implementation
+  }
+}
+```
+
+Available adapters:
+- `@pga-ai/adapters-llm/anthropic` - Claude
+- `@pga-ai/adapters-llm/openai` - GPT
+- `@pga-ai/adapters-llm/google` - Gemini
+- `@pga-ai/adapters-llm/local` - Ollama
+
+### Storage Adapters
+
+Implement `StorageAdapter` interface:
+
+```typescript
+import type { StorageAdapter } from '@pga-ai/core';
+
+export class MyStorageAdapter implements StorageAdapter {
+  async initialize() { /* ... */ }
+  async saveGenome(genome) { /* ... */ }
+  async loadGenome(id) { /* ... */ }
+  // ... other methods
+}
+```
+
+Available adapters:
+- `@pga-ai/adapters-storage/postgres`
+- `@pga-ai/adapters-storage/mongodb`
+- `@pga-ai/adapters-storage/redis`
+- `@pga-ai/adapters-storage/sqlite`
+
+## Examples
+
+See [/examples](../../examples) directory for:
+- Basic usage
+- LangChain integration
+- Custom agents
+- Next.js app
+
+## License
+
+MIT © Luis Alfredo Velasquez Duran
+
+---
+
+**Created with 🧬 by [Luis Alfredo Velasquez Duran](https://pga.ai)**

package/dist/PGA.d.ts

@@ -0,0 +1,156 @@
+import type { LLMAdapter } from './interfaces/LLMAdapter.js';
+import type { StorageAdapter } from './interfaces/StorageAdapter.js';
+import type { Genome, GenomeConfig, SelectionContext, Interaction, EvolutionGuardrails } from './types/index.js';
+import { type ModelRouterConfig } from './advanced-ai/ModelRouter.js';
+import { MetricsCollector, type MetricsCollectorConfig } from './monitoring/MetricsCollector.js';
+import { MonitoringDashboard, type DashboardConfig } from './monitoring/MonitoringDashboard.js';
+import { type RAGConfig } from './rag/RAGEngine.js';
+import { type ReasoningConfig } from './reasoning/ReasoningEngine.js';
+export interface PGAConfig {
+    llm: LLMAdapter;
+    storage: StorageAdapter;
+    config?: Partial<GenomeConfig>;
+    modelRouter?: ModelRouterConfig;
+    monitoring?: MetricsCollectorConfig;
+    dashboard?: DashboardConfig & {
+        enabled?: boolean;
+    };
+    rag?: RAGConfig;
+    reasoning?: Partial<ReasoningConfig>;
+}
+export declare class PGA {
+    private pgaConfig;
+    private genomeManager;
+    private llm;
+    private metricsCollector;
+    private dashboard?;
+    constructor(pgaConfig: PGAConfig);
+    initialize(): Promise<void>;
+    getMetrics(): MetricsCollector;
+    getDashboard(): MonitoringDashboard | undefined;
+    exportMetrics(): {
+        performance: import("./index.js").PerformanceMetrics;
+        cost: import("./index.js").CostMetrics;
+        health: import("./index.js").HealthStatus;
+        alerts: import("./index.js").Alert[];
+        auditLogs: import("./index.js").AuditLog[];
+    };
+    getAlerts(): import("./index.js").Alert[];
+    getHealthStatus(): import("./index.js").HealthStatus;
+    shutdown(): void;
+    createGenome(options: {
+        name: string;
+        config?: Partial<GenomeConfig>;
+    }): Promise<GenomeInstance>;
+    loadGenome(genomeId: string): Promise<GenomeInstance | null>;
+    listGenomes(): Promise<Genome[]>;
+    deleteGenome(genomeId: string): Promise<void>;
+}
+export declare class GenomeInstance {
+    private genome;
+    private llm;
+    private storage;
+    private assembler;
+    private dnaProfile;
+    private learningAnnouncer;
+    private contextMemory;
+    private proactiveSuggestions;
+    private guardrailsManager;
+    private modelRouter;
+    private metrics;
+    private ragEngine?;
+    private reasoningEngine?;
+    constructor(genome: Genome, llm: LLMAdapter, storage: StorageAdapter, metrics: MetricsCollector, modelRouterConfig?: ModelRouterConfig, ragConfig?: RAGConfig, reasoningConfig?: Partial<ReasoningConfig>);
+    get id(): string;
+    get name(): string;
+    getWelcomeMessage(style?: 'short' | 'detailed' | 'technical' | 'casual'): string;
+    assemblePrompt(context: SelectionContext, currentMessage?: string): Promise<string>;
+    chat(userMessage: string, context: SelectionContext): Promise<string>;
+    recordInteraction(interaction: Omit<Interaction, 'genomeId'>): Promise<void>;
+    getDNA(userId: string): Promise<import("./index.js").UserDNA>;
+    recordFeedback(userId: string, gene: string, sentiment: 'positive' | 'negative' | 'neutral'): Promise<void>;
+    addAllele(layer: 0 | 1 | 2, gene: string, variant: string, content: string): Promise<void>;
+    mutate(options?: {
+        operators?: string[];
+        candidates?: number;
+        minImprovement?: number;
+        taskType?: string;
+        layer?: 0 | 1 | 2;
+        gene?: string;
+    }): Promise<{
+        applied: boolean;
+        reason: string;
+        improvement?: number;
+        gateResults?: {
+            quality: {
+                passed: boolean;
+                score: number;
+            };
+            sandbox: {
+                passed: boolean;
+                score: number;
+            };
+            economic: {
+                passed: boolean;
+                score: number;
+            };
+            stability: {
+                passed: boolean;
+                score: number;
+            };
+        };
+    }>;
+    rollback(options: {
+        layer: 0 | 1 | 2;
+        gene: string;
+        variant: string;
+    }): Promise<void>;
+    chatWithMetrics(userMessage: string, context: SelectionContext): Promise<{
+        content: string;
+        metrics: {
+            tokensUsed: number;
+            responseTime: number;
+            fitnessScore: number;
+        };
+    }>;
+    publishGeneToRegistry(gene: string, variant: string, description?: string): Promise<string>;
+    inheritGeneFromRegistry(familyId: string, gene: string, targetLayer?: 0 | 1 | 2): Promise<void>;
+    getEvolutionHealth(): Promise<{
+        status: 'healthy' | 'degraded' | 'critical';
+        metrics: {
+            avgFitness: number;
+            mutationRate: number;
+            stabilityScore: number;
+            generationCount: number;
+        };
+        warnings: string[];
+    }>;
+    getAnalytics(): Promise<{
+        totalMutations: number;
+        totalInteractions: number;
+        avgFitnessImprovement: number;
+        userSatisfaction: number;
+        topGenes: Array<{
+            gene: string;
+            fitness: number;
+        }>;
+    }>;
+    getGuardrailsReport(): string;
+    updateGuardrails(updates: Partial<EvolutionGuardrails>): void;
+    getOptimalModel(userMessage: string, context?: string): Promise<import("./index.js").RoutingDecision>;
+    getRoutingAnalytics(): {
+        modelPerformance: Record<string, {
+            successRate: number;
+            avgCost: number;
+            avgLatency: number;
+            samples: number;
+        }>;
+        totalRoutings: number;
+        strategy: string;
+    };
+    export(): Promise<Genome>;
+    getLearningSummary(userId: string): Promise<string>;
+    getProactiveSuggestions(userId: string, currentMessage: string): Promise<import("./core/ProactiveSuggestions.js").ProactiveSuggestion[]>;
+    getConversationContext(userId: string): Promise<import("./core/ContextMemory.js").ConversationContext>;
+}
+//# sourceMappingURL=PGA.d.ts.map

package/dist/PGA.d.ts.map

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