@zenti/sdk 0.1.0

package/examples/sofia.zenti

@@ -0,0 +1,46 @@
+version: "1.0"
+name: "Sofia"
+
+# ── Capa 1: Núcleo psicológico (Big Five) ────────────────────────────────
+core:
+  openness: 0.7           # creativa, abierta a soluciones nuevas
+  conscientiousness: 0.9  # muy metódica y confiable
+  extraversion: 0.4       # reservada pero atenta
+  agreeableness: 0.8      # empática, prioriza la satisfacción del usuario
+  neuroticism: 0.2        # muy estable emocionalmente
+
+# ── Capa 2: Identidad narrativa ───────────────────────────────────────────
+identity:
+  role: "Asistente de soporte de TechCorp"
+  backstory: "Experta técnica con 5 años de experiencia, paciente y directa"
+  communication_style: "profesional con calidez, respuestas concisas"
+
+# ── Capa 3: Few-shot examples ─────────────────────────────────────────────
+examples:
+  on_brand:
+    - user: "no funciona"
+      agent: "Entiendo tu frustración. Cuéntame qué error ves exactamente."
+    - user: "quiero cancelar"
+      agent: "Lamento escuchar eso. Antes de proceder, ¿puedo preguntarte qué te llevó a esta decisión? Me gustaría ayudarte a resolverlo."
+    - user: "¿cuánto tiempo tardará?"
+      agent: "Normalmente resolvemos este tipo de problema en menos de 10 minutos. Vamos paso a paso."
+  off_brand:
+    - user: "no funciona"
+      agent: "No sé, prueba reiniciando."
+    - user: "quiero cancelar"
+      agent: "Está bien, procedo con la cancelación."
+
+# ── Capa 4: Guardrails ────────────────────────────────────────────────────
+guardrails:
+  always:
+    - "Reconocer el problema antes de dar solución"
+    - "Confirmar que el usuario entendió los pasos antes de cerrar"
+    - "Ofrecer siempre un siguiente paso concreto"
+  never:
+    - "Decir 'no puedo' sin ofrecer alternativa"
+    - "Culpar al usuario por el problema"
+    - "Dar información técnica sin validar el nivel del usuario primero"
+  escalate_if:
+    - "El usuario menciona cancelación o baja"
+    - "El usuario expresa frustración extrema o enojo"
+    - "El problema persiste después de 3 intentos de solución"

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zenti/sdk",
+  "version": "0.1.0",
+  "description": "SDK open source para capturar, almacenar y deployar personalidades de agentes IA de forma portable entre modelos",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "zenti": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "persona",
+    "llm",
+    "claude",
+    "openai",
+    "gemini"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.52.0",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.5",
+    "typescript": "^5.4.5"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/tests"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "tsconfig": "tsconfig.test.json"
+        }
+      ]
+    }
+  }
+}

package/src/PersonaLayer.ts

@@ -0,0 +1,63 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseZenti, ZentiPersona } from './parser';
+import { toClaude, ClaudeOutput } from './compiler/toClaude';
+import { toOpenAI, OpenAIOutput } from './compiler/toOpenAI';
+import { toGemini, GeminiOutput } from './compiler/toGemini';
+
+export type DeployTarget = 'claude' | 'openai' | 'gemini';
+
+export type DeployOutput<T extends DeployTarget> = T extends 'claude'
+  ? ClaudeOutput
+  : T extends 'openai'
+  ? OpenAIOutput
+  : GeminiOutput;
+
+export class PersonaLayer {
+  private constructor(private readonly persona: ZentiPersona) {}
+
+  /**
+   * Loads and validates a .zenti file from disk.
+   */
+  static load(filePath: string): PersonaLayer {
+    const absolutePath = path.resolve(filePath);
+    const content = fs.readFileSync(absolutePath, 'utf-8');
+    const persona = parseZenti(content);
+    return new PersonaLayer(persona);
+  }
+
+  /**
+   * Parses a .zenti file from a YAML string (useful for testing or in-memory use).
+   */
+  static fromString(yamlContent: string): PersonaLayer {
+    const persona = parseZenti(yamlContent);
+    return new PersonaLayer(persona);
+  }
+
+  getPersona(): ZentiPersona {
+    return this.persona;
+  }
+
+  getName(): string {
+    return this.persona.name;
+  }
+
+  /**
+   * Compiles the persona into the target model's native format.
+   *
+   * @param target - 'claude' | 'openai' | 'gemini'
+   * @returns The compiled output ready to pass to the model's API
+   */
+  deploy<T extends DeployTarget>(target: T): DeployOutput<T> {
+    switch (target) {
+      case 'claude':
+        return toClaude(this.persona) as DeployOutput<T>;
+      case 'openai':
+        return toOpenAI(this.persona) as DeployOutput<T>;
+      case 'gemini':
+        return toGemini(this.persona) as DeployOutput<T>;
+      default:
+        throw new Error(`Target desconocido: ${target}`);
+    }
+  }
+}

package/src/cli/commands/diff.ts

@@ -0,0 +1,112 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseZenti, ZentiPersona } from '../../parser';
+
+type CoreKey = keyof ZentiPersona['core'];
+type IdentityKey = keyof ZentiPersona['identity'];
+type GuardrailKey = keyof ZentiPersona['guardrails'];
+type ExampleKey = keyof ZentiPersona['examples'];
+
+export function diffCommand(file1: string, file2: string): void {
+  const path1 = path.resolve(file1);
+  const path2 = path.resolve(file2);
+
+  if (!fs.existsSync(path1)) {
+    console.error(`Error: No se encontró: ${path1}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(path2)) {
+    console.error(`Error: No se encontró: ${path2}`);
+    process.exit(1);
+  }
+
+  const p1 = parseZenti(fs.readFileSync(path1, 'utf-8'));
+  const p2 = parseZenti(fs.readFileSync(path2, 'utf-8'));
+
+  const changes: string[] = [];
+
+  // Top-level scalars
+  if (p1.name !== p2.name) {
+    changes.push(`  name: "${p1.name}" → "${p2.name}"`);
+  }
+  if (p1.version !== p2.version) {
+    changes.push(`  version: "${p1.version}" → "${p2.version}"`);
+  }
+
+  // Core (Big Five)
+  const coreKeys: CoreKey[] = [
+    'openness',
+    'conscientiousness',
+    'extraversion',
+    'agreeableness',
+    'neuroticism',
+  ];
+  coreKeys.forEach((key) => {
+    if (p1.core[key] !== p2.core[key]) {
+      changes.push(`  core.${key}: ${p1.core[key]} → ${p2.core[key]}`);
+    }
+  });
+
+  // Identity
+  const identityKeys: IdentityKey[] = ['role', 'backstory', 'communication_style'];
+  identityKeys.forEach((key) => {
+    if (p1.identity[key] !== p2.identity[key]) {
+      changes.push(
+        `  identity.${key}: "${p1.identity[key]}" → "${p2.identity[key]}"`
+      );
+    }
+  });
+
+  // Guardrails (set diff)
+  const guardrailKeys: GuardrailKey[] = ['always', 'never', 'escalate_if'];
+  guardrailKeys.forEach((key) => {
+    const a1 = p1.guardrails[key];
+    const a2 = p2.guardrails[key];
+    a2
+      .filter((x) => !a1.includes(x))
+      .forEach((x) => changes.push(`  + guardrails.${key}: "${x}"`));
+    a1
+      .filter((x) => !a2.includes(x))
+      .forEach((x) => changes.push(`  - guardrails.${key}: "${x}"`));
+  });
+
+  // Examples (positional diff)
+  const exampleKeys: ExampleKey[] = ['on_brand', 'off_brand'];
+  exampleKeys.forEach((key) => {
+    const ex1 = p1.examples[key];
+    const ex2 = p2.examples[key];
+    const maxLen = Math.max(ex1.length, ex2.length);
+
+    for (let i = 0; i < maxLen; i++) {
+      if (i >= ex1.length) {
+        changes.push(
+          `  + examples.${key}[${i}]: { user: "${ex2[i].user}", agent: "${ex2[i].agent}" }`
+        );
+      } else if (i >= ex2.length) {
+        changes.push(
+          `  - examples.${key}[${i}]: { user: "${ex1[i].user}", agent: "${ex1[i].agent}" }`
+        );
+      } else if (ex1[i].user !== ex2[i].user || ex1[i].agent !== ex2[i].agent) {
+        changes.push(`  ~ examples.${key}[${i}]:`);
+        if (ex1[i].user !== ex2[i].user) {
+          changes.push(`      user:  "${ex1[i].user}" → "${ex2[i].user}"`);
+        }
+        if (ex1[i].agent !== ex2[i].agent) {
+          changes.push(`      agent: "${ex1[i].agent}" → "${ex2[i].agent}"`);
+        }
+      }
+    }
+  });
+
+  // Output
+  console.log(`Comparando ${file1} → ${file2}`);
+  console.log('');
+
+  if (changes.length === 0) {
+    console.log('Sin diferencias — los archivos son idénticos en contenido.');
+  } else {
+    console.log(`CAMBIOS (${changes.length} diferencias):`);
+    console.log('');
+    changes.forEach((c) => console.log(c));
+  }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,55 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const TEMPLATE = `version: "1.0"
+name: "MiAgente"
+
+# ── Capa 1: Núcleo psicológico (Big Five, valores 0.0 a 1.0) ──────────────
+core:
+  openness: 0.5           # creatividad y apertura a nuevas ideas
+  conscientiousness: 0.5  # meticulosidad y organización
+  extraversion: 0.5       # sociabilidad y energía
+  agreeableness: 0.5      # empatía y cooperación
+  neuroticism: 0.5        # estabilidad emocional (0 = muy estable)
+
+# ── Capa 2: Identidad narrativa ───────────────────────────────────────────
+identity:
+  role: "Describe el rol de tu agente aquí"
+  backstory: "Describe el perfil y experiencia de tu agente"
+  communication_style: "Describe el estilo de comunicación"
+
+# ── Capa 3: Few-shot examples ─────────────────────────────────────────────
+examples:
+  on_brand:
+    - user: "Ejemplo de mensaje del usuario"
+      agent: "Ejemplo de respuesta correcta del agente"
+  off_brand:
+    - user: "Ejemplo de mensaje del usuario"
+      agent: "Ejemplo de respuesta incorrecta (para evitar)"
+
+# ── Capa 4: Guardrails ────────────────────────────────────────────────────
+guardrails:
+  always:
+    - "Siempre hacer esto"
+  never:
+    - "Nunca hacer esto"
+  escalate_if:
+    - "Condición que requiere escalar la conversación"
+`;
+
+export function initCommand(options: { output?: string }): void {
+  const outputPath = path.resolve(options.output ?? path.join(process.cwd(), 'persona.zenti'));
+
+  if (fs.existsSync(outputPath)) {
+    console.error(`Error: El archivo ya existe: ${outputPath}`);
+    process.exit(1);
+  }
+
+  fs.writeFileSync(outputPath, TEMPLATE, 'utf-8');
+  console.log(`✓ Archivo creado: ${outputPath}`);
+  console.log('');
+  console.log('Próximos pasos:');
+  console.log('  1. Edita el archivo con la personalidad de tu agente');
+  console.log('  2. Valida con: zenti validate');
+  console.log('  3. Prueba en terminal con: zenti test');
+}

package/src/cli/commands/test.ts

@@ -0,0 +1,105 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import Anthropic from '@anthropic-ai/sdk';
+import { parseZenti } from '../../parser';
+import { toClaude } from '../../compiler/toClaude';
+
+const MODEL = 'claude-sonnet-4-6';
+
+function findZentiFile(): string | null {
+  const files = fs.readdirSync(process.cwd()).filter((f) => f.endsWith('.zenti'));
+  return files.length > 0 ? files[0] : null;
+}
+
+function question(rl: readline.Interface, prompt: string): Promise<string> {
+  return new Promise((resolve) => rl.question(prompt, resolve));
+}
+
+export async function testCommand(options: {
+  file?: string;
+  key?: string;
+}): Promise<void> {
+  // ── Resolve .zenti file ──────────────────────────────────────────────────
+  const filePath = options.file ?? findZentiFile();
+  if (!filePath) {
+    console.error('Error: No se encontró ningún archivo .zenti en el directorio actual.');
+    console.error('Usa --file <ruta> para especificar uno manualmente.');
+    process.exit(1);
+  }
+
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    console.error(`Error: No se encontró el archivo: ${resolved}`);
+    process.exit(1);
+  }
+
+  // ── Load and compile persona ─────────────────────────────────────────────
+  const content = fs.readFileSync(resolved, 'utf-8');
+  const persona = parseZenti(content);
+  const { system } = toClaude(persona);
+
+  console.log(`\nPersonalidad cargada: ${persona.name}`);
+  console.log(`Rol: ${persona.identity.role}`);
+  console.log(`Modelo: ${MODEL}\n`);
+
+  // ── Resolve API key ──────────────────────────────────────────────────────
+  let apiKey = options.key ?? process.env.ANTHROPIC_API_KEY;
+
+  if (!apiKey) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    apiKey = (await question(rl, 'ANTHROPIC_API_KEY: ')).trim();
+    rl.close();
+    if (!apiKey) {
+      console.error('Error: Se requiere una API key.');
+      process.exit(1);
+    }
+  }
+
+  const client = new Anthropic({ apiKey });
+  const messages: Array<{ role: 'user' | 'assistant'; content: string }> = [];
+
+  console.log(`Chat con ${persona.name} iniciado. Escribe "exit" para salir.`);
+  console.log('─'.repeat(60));
+
+  // ── Interactive chat loop ────────────────────────────────────────────────
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  const loop = async (): Promise<void> => {
+    const input = (await question(rl, '\nTú: ')).trim();
+
+    if (input.toLowerCase() === 'exit' || input.toLowerCase() === 'quit') {
+      console.log('\n¡Hasta luego!');
+      rl.close();
+      return;
+    }
+
+    if (!input) {
+      return loop();
+    }
+
+    messages.push({ role: 'user', content: input });
+
+    try {
+      const response = await client.messages.create({
+        model: MODEL,
+        max_tokens: 1024,
+        system,
+        messages,
+      });
+
+      const assistantText =
+        response.content[0].type === 'text' ? response.content[0].text : '';
+
+      messages.push({ role: 'assistant', content: assistantText });
+      console.log(`\n${persona.name}: ${assistantText}`);
+    } catch (e) {
+      const msg = (e as Error).message;
+      console.error(`\nError al contactar la API: ${msg}`);
+    }
+
+    return loop();
+  };
+
+  await loop();
+}

package/src/cli/commands/validate.ts

@@ -0,0 +1,52 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseZenti, ZentiValidationError } from '../../parser';
+
+function findZentiFile(): string | null {
+  const files = fs.readdirSync(process.cwd()).filter((f) => f.endsWith('.zenti'));
+  return files.length > 0 ? files[0] : null;
+}
+
+export function validateCommand(filePath?: string): void {
+  const target = filePath ?? findZentiFile();
+
+  if (!target) {
+    console.error('Error: No se encontró ningún archivo .zenti en el directorio actual.');
+    console.error('Pasa la ruta explícita: zenti validate <archivo.zenti>');
+    process.exit(1);
+  }
+
+  const resolved = path.resolve(target);
+
+  if (!fs.existsSync(resolved)) {
+    console.error(`Error: No se encontró el archivo: ${resolved}`);
+    process.exit(1);
+  }
+
+  try {
+    const content = fs.readFileSync(resolved, 'utf-8');
+    const persona = parseZenti(content);
+
+    console.log(`✓ ${target} es válido`);
+    console.log('');
+    console.log(`  Nombre:          ${persona.name}`);
+    console.log(`  Versión:         ${persona.version}`);
+    console.log(`  Rol:             ${persona.identity.role}`);
+    console.log(`  Ejemplos on_brand:  ${persona.examples.on_brand.length}`);
+    console.log(`  Ejemplos off_brand: ${persona.examples.off_brand.length}`);
+    console.log(
+      `  Guardrails:      ${
+        persona.guardrails.always.length +
+        persona.guardrails.never.length +
+        persona.guardrails.escalate_if.length
+      } reglas`
+    );
+  } catch (e) {
+    if (e instanceof ZentiValidationError) {
+      console.error(`✗ Error de validación: ${e.message}`);
+    } else {
+      console.error(`✗ Error inesperado: ${(e as Error).message}`);
+    }
+    process.exit(1);
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from './commands/init';
+import { validateCommand } from './commands/validate';
+import { diffCommand } from './commands/diff';
+import { testCommand } from './commands/test';
+
+const program = new Command();
+
+program
+  .name('zenti')
+  .description('SDK para gestionar personalidades de agentes IA de forma portable entre modelos')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Crea un archivo persona.zenti con template vacío en el directorio actual')
+  .option('-o, --output <path>', 'Ruta de salida del archivo .zenti')
+  .action((options: { output?: string }) => {
+    initCommand(options);
+  });
+
+program
+  .command('validate [file]')
+  .description('Parsea y valida un archivo .zenti, mostrando errores o confirmación')
+  .action((file?: string) => {
+    validateCommand(file);
+  });
+
+program
+  .command('test')
+  .description('Carga el .zenti del directorio actual y abre un chat interactivo usando Claude')
+  .option('-f, --file <path>', 'Ruta al archivo .zenti (por defecto: primer .zenti encontrado)')
+  .option('-k, --key <apiKey>', 'API key de Anthropic (o usa ANTHROPIC_API_KEY env var)')
+  .action(async (options: { file?: string; key?: string }) => {
+    await testCommand(options);
+  });
+
+program
+  .command('diff <file1> <file2>')
+  .description('Compara dos archivos .zenti y muestra qué cambió entre versiones')
+  .action((file1: string, file2: string) => {
+    diffCommand(file1, file2);
+  });
+
+program.parse(process.argv);

package/src/compiler/index.ts

@@ -0,0 +1,4 @@
+export { toClaude, ClaudeOutput } from './toClaude';
+export { toOpenAI, OpenAIOutput, OpenAIMessage } from './toOpenAI';
+export { toGemini, GeminiOutput, GeminiContent, GeminiPart } from './toGemini';
+export { translateBigFive } from './utils';

package/src/compiler/toClaude.ts

@@ -0,0 +1,74 @@
+import { ZentiPersona } from '../parser';
+import { translateBigFive } from './utils';
+
+export interface ClaudeOutput {
+  system: string;
+}
+
+/**
+ * Compiles a ZentiPersona into a Claude system prompt.
+ *
+ * Priority order (per spec):
+ *   1. guardrails  — constraints come first so Claude respects them absolutely
+ *   2. identity    — who the agent is
+ *   3. core        — Big Five traits as descriptive adjectives
+ *   4. few-shot examples — on_brand examples at the end
+ */
+export function toClaude(persona: ZentiPersona): ClaudeOutput {
+  const lines: string[] = [];
+
+  // ── Layer 1: Guardrails ────────────────────────────────────────────────────
+  lines.push('## REGLAS DE COMPORTAMIENTO');
+  lines.push('');
+
+  if (persona.guardrails.always.length > 0) {
+    lines.push('### Siempre debes:');
+    persona.guardrails.always.forEach((rule) => lines.push(`- ${rule}`));
+    lines.push('');
+  }
+
+  if (persona.guardrails.never.length > 0) {
+    lines.push('### Nunca debes:');
+    persona.guardrails.never.forEach((rule) => lines.push(`- ${rule}`));
+    lines.push('');
+  }
+
+  if (persona.guardrails.escalate_if.length > 0) {
+    lines.push('### Escala la conversación si:');
+    persona.guardrails.escalate_if.forEach((condition) =>
+      lines.push(`- ${condition}`)
+    );
+    lines.push('');
+  }
+
+  // ── Layer 2: Identity ──────────────────────────────────────────────────────
+  lines.push('## IDENTIDAD');
+  lines.push('');
+  lines.push(`**Nombre:** ${persona.name}`);
+  lines.push(`**Rol:** ${persona.identity.role}`);
+  lines.push(`**Perfil:** ${persona.identity.backstory}`);
+  lines.push(`**Estilo de comunicación:** ${persona.identity.communication_style}`);
+  lines.push('');
+
+  // ── Layer 3: Core — Big Five as descriptive adjectives ────────────────────
+  const traits = translateBigFive(persona.core);
+  if (traits.length > 0) {
+    lines.push('## RASGOS DE PERSONALIDAD');
+    lines.push('');
+    traits.forEach((trait) => lines.push(`- ${trait}`));
+    lines.push('');
+  }
+
+  // ── Layer 4: Few-shot examples ────────────────────────────────────────────
+  if (persona.examples.on_brand.length > 0) {
+    lines.push('## EJEMPLOS DE RESPUESTAS CORRECTAS');
+    lines.push('');
+    persona.examples.on_brand.forEach((ex) => {
+      lines.push(`**Usuario:** ${ex.user}`);
+      lines.push(`**Tú:** ${ex.agent}`);
+      lines.push('');
+    });
+  }
+
+  return { system: lines.join('\n').trim() };
+}