npm package: @gsep/core
Description: GSEP Core - Genomic Self-Evolving Prompts with Gene Bank, THK, Layered Memory, RAG, and Advanced Reasoning
Author: Luis Alfredo Velasquez Duran
Latest version: 1.0.1

# @gsep/core

> 🧬 **Genomic Self-Evolving Prompts** — Core Engine

[![npm version](https://img.shields.io/npm/v/@gsep/core)](https://www.npmjs.com/package/@gsep/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 @gsep/core?

The core engine for GSEP (Genomic Self-Evolving Prompts) — the world's first system that makes AI prompts **evolve automatically** like biological organisms.

Instead of manually tweaking prompts, GSEP:
- ✅ 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 @gsep/core
```

You'll also need adapters for your LLM and database:

```bash
npm install @gsep/adapters-llm @gsep/adapters-storage
```

## Quick Start

```typescript
import { GSEP } from '@gsep/core';
import { ClaudeAdapter } from '@gsep/adapters-llm/anthropic';
import { PostgresAdapter } from '@gsep/adapters-storage/postgres';

// 1. Initialize GSEP
const gsep = new GSEP({
  llm: new ClaudeAdapter({
    apiKey: process.env.ANTHROPIC_KEY,
  }),
  storage: new PostgresAdapter({
    connectionString: process.env.DATABASE_URL,
  }),
});

await gsep.initialize();

// 2. Create genome
const genome = await gsep.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. GSEP 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

### Five-Layer Chromosome Architecture

```
┌─────────────────────────────────────────┐
│  C0: Immutable DNA                      │
│  Security, Ethics, Core Identity        │
│  🚫 NEVER mutates (SHA-256 protected)  │
├─────────────────────────────────────────┤
│  C1: Operative Genes                    │
│  Tool Usage, Coding Patterns            │
│  🐢 SLOW mutation (sandbox-tested)     │
├─────────────────────────────────────────┤
│  C2: Epigenomes                         │
│  User Preferences, Communication Style  │
│  ⚡ FAST mutation (daily adaptation)    │
├─────────────────────────────────────────┤
│  C3: Content Firewall                   │
│  Input Security, Prompt Defense         │
│  🛡️ 57 threat patterns, trust policies │
├─────────────────────────────────────────┤
│  C4: Behavioral Immune System           │
│  Output Infection Detection             │
│  🧬 6 checks — auto-heal + quarantine  │
└─────────────────────────────────────────┘
```

### 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

GSEP 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

### GSEP Class

#### `new GSEP(config)`

Create GSEP instance.

```typescript
const gsep = new GSEP({
  llm: new ClaudeAdapter({ apiKey: '...' }),
  storage: new PostgresAdapter({ connectionString: '...' }),
  config: {
    enableSandbox: true,      // Test mutations before deploy
    mutationRate: 'balanced',  // 'slow' | 'balanced' | 'aggressive'
  },
});
```

#### `gsep.initialize()`

Initialize storage (create tables, etc.).

```typescript
await gsep.initialize();
```

#### `gsep.createGenome(options)`

Create new genome.

```typescript
const genome = await gsep.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 GSEP 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 '@gsep/core';

export class MyLLMAdapter implements LLMAdapter {
  readonly name = 'my-llm';
  readonly model = 'my-model-v1';

  async chat(messages, options) {
    // Your implementation
  }
}
```

Available adapters:
- `@gsep/adapters-llm/anthropic` - Claude
- `@gsep/adapters-llm/openai` - GPT
- `@gsep/adapters-llm/google` - Gemini
- `@gsep/adapters-llm/local` - Ollama

### Storage Adapters

Implement `StorageAdapter` interface:

```typescript
import type { StorageAdapter } from '@gsep/core';

export class MyStorageAdapter implements StorageAdapter {
  async initialize() { /* ... */ }
  async saveGenome(genome) { /* ... */ }
  async loadGenome(id) { /* ... */ }
  // ... other methods
}
```

Available adapters:
- `@gsep/adapters-storage/postgres`
- `@gsep/adapters-storage/mongodb`
- `@gsep/adapters-storage/redis`
- `@gsep/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://gsepcore.com)**