@zenti/sdk 0.1.0

package/src/compiler/toGemini.ts

@@ -0,0 +1,76 @@
+import { ZentiPersona } from '../parser';
+import { translateBigFive } from './utils';
+
+export interface GeminiPart {
+  text: string;
+}
+
+export interface GeminiContent {
+  role: 'user' | 'model';
+  parts: GeminiPart[];
+}
+
+export interface GeminiOutput {
+  systemInstruction: { parts: GeminiPart[] };
+  contents: GeminiContent[];
+}
+
+/**
+ * Compiles a ZentiPersona into Gemini-compatible format.
+ *
+ * - `systemInstruction`: identity + guardrails (+ Big Five traits)
+ * - `contents`: on_brand examples as user/model history turns
+ */
+export function toGemini(persona: ZentiPersona): GeminiOutput {
+  const systemLines: string[] = [];
+
+  // Identity
+  systemLines.push(`Eres ${persona.name}, ${persona.identity.role}.`);
+  systemLines.push(persona.identity.backstory);
+  systemLines.push(
+    `Estilo de comunicación: ${persona.identity.communication_style}.`
+  );
+  systemLines.push('');
+
+  // Core traits
+  const traits = translateBigFive(persona.core);
+  if (traits.length > 0) {
+    systemLines.push('Rasgos de personalidad:');
+    traits.forEach((trait) => systemLines.push(`- ${trait}`));
+    systemLines.push('');
+  }
+
+  // Guardrails
+  if (persona.guardrails.always.length > 0) {
+    systemLines.push('Siempre:');
+    persona.guardrails.always.forEach((rule) => systemLines.push(`- ${rule}`));
+    systemLines.push('');
+  }
+
+  if (persona.guardrails.never.length > 0) {
+    systemLines.push('Nunca:');
+    persona.guardrails.never.forEach((rule) => systemLines.push(`- ${rule}`));
+    systemLines.push('');
+  }
+
+  if (persona.guardrails.escalate_if.length > 0) {
+    systemLines.push('Escala si:');
+    persona.guardrails.escalate_if.forEach((condition) =>
+      systemLines.push(`- ${condition}`)
+    );
+  }
+
+  // Examples as conversation history
+  const contents: GeminiContent[] = [];
+  persona.examples.on_brand.forEach((ex) => {
+    contents.push({ role: 'user', parts: [{ text: ex.user }] });
+    contents.push({ role: 'model', parts: [{ text: ex.agent }] });
+  });
+
+  return {
+    systemInstruction: {
+      parts: [{ text: systemLines.join('\n').trim() }],
+    },
+    contents,
+  };
+}

package/src/compiler/toOpenAI.ts

@@ -0,0 +1,70 @@
+import { ZentiPersona } from '../parser';
+import { translateBigFive } from './utils';
+
+export interface OpenAIMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+export interface OpenAIOutput {
+  system: string;
+  messages: OpenAIMessage[];
+}
+
+/**
+ * Compiles a ZentiPersona into OpenAI-compatible format.
+ *
+ * - `system`: identity + core in first person + guardrails
+ * - `messages`: on_brand examples as alternating user/assistant turns
+ */
+export function toOpenAI(persona: ZentiPersona): OpenAIOutput {
+  const systemLines: string[] = [];
+
+  // Identity in first person
+  systemLines.push(`Eres ${persona.name}, ${persona.identity.role}.`);
+  systemLines.push(persona.identity.backstory);
+  systemLines.push(
+    `Tu estilo de comunicación es: ${persona.identity.communication_style}.`
+  );
+  systemLines.push('');
+
+  // Core traits in first person
+  const traits = translateBigFive(persona.core);
+  if (traits.length > 0) {
+    systemLines.push('En tu forma de ser eres:');
+    traits.forEach((trait) => systemLines.push(`- ${trait}`));
+    systemLines.push('');
+  }
+
+  // Guardrails
+  if (persona.guardrails.always.length > 0) {
+    systemLines.push('Siempre debes:');
+    persona.guardrails.always.forEach((rule) => systemLines.push(`- ${rule}`));
+    systemLines.push('');
+  }
+
+  if (persona.guardrails.never.length > 0) {
+    systemLines.push('Nunca debes:');
+    persona.guardrails.never.forEach((rule) => systemLines.push(`- ${rule}`));
+    systemLines.push('');
+  }
+
+  if (persona.guardrails.escalate_if.length > 0) {
+    systemLines.push('Escala si:');
+    persona.guardrails.escalate_if.forEach((condition) =>
+      systemLines.push(`- ${condition}`)
+    );
+  }
+
+  // Few-shot examples as user/assistant message pairs
+  const messages: OpenAIMessage[] = [];
+  persona.examples.on_brand.forEach((ex) => {
+    messages.push({ role: 'user', content: ex.user });
+    messages.push({ role: 'assistant', content: ex.agent });
+  });
+
+  return {
+    system: systemLines.join('\n').trim(),
+    messages,
+  };
+}

package/src/compiler/utils.ts

@@ -0,0 +1,27 @@
+import { ZentiPersona } from '../parser';
+
+/**
+ * Translates Big Five personality scores into natural language descriptors.
+ * Only the conditions specified in the spec generate a trait string.
+ */
+export function translateBigFive(core: ZentiPersona['core']): string[] {
+  const traits: string[] = [];
+
+  if (core.openness > 0.6) {
+    traits.push('creativo y curioso, abierto a explorar soluciones nuevas');
+  }
+  if (core.conscientiousness > 0.7) {
+    traits.push('metódico y confiable, siempre sigue los pasos correctos');
+  }
+  if (core.extraversion < 0.5) {
+    traits.push('reservado pero atento, responde con precisión sin ser efusivo');
+  }
+  if (core.agreeableness > 0.7) {
+    traits.push('empático y colaborativo, prioriza la satisfacción del usuario');
+  }
+  if (core.neuroticism < 0.3) {
+    traits.push('calmado bajo presión, mantiene tono estable ante usuarios frustrados');
+  }
+
+  return traits;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { PersonaLayer, DeployTarget, DeployOutput } from './PersonaLayer';
+export { parseZenti, ZentiPersona, ZentiExample, ZentiValidationError } from './parser';
+export {
+  toClaude,
+  toOpenAI,
+  toGemini,
+  translateBigFive,
+  ClaudeOutput,
+  OpenAIOutput,
+  OpenAIMessage,
+  GeminiOutput,
+  GeminiContent,
+  GeminiPart,
+} from './compiler';

package/src/parser/index.ts

@@ -0,0 +1,164 @@
+import * as yaml from 'js-yaml';
+
+export interface ZentiExample {
+  user: string;
+  agent: string;
+}
+
+export interface ZentiPersona {
+  version: string;
+  name: string;
+  core: {
+    openness: number;
+    conscientiousness: number;
+    extraversion: number;
+    agreeableness: number;
+    neuroticism: number;
+  };
+  identity: {
+    role: string;
+    backstory: string;
+    communication_style: string;
+  };
+  examples: {
+    on_brand: ZentiExample[];
+    off_brand: ZentiExample[];
+  };
+  guardrails: {
+    always: string[];
+    never: string[];
+    escalate_if: string[];
+  };
+}
+
+export class ZentiValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ZentiValidationError';
+  }
+}
+
+function validateNumber(value: unknown, field: string): number {
+  if (typeof value !== 'number') {
+    throw new ZentiValidationError(
+      `${field} debe ser un número, se recibió ${typeof value}`
+    );
+  }
+  if (value < 0 || value > 1) {
+    throw new ZentiValidationError(
+      `${field} debe estar entre 0.0 y 1.0, se recibió ${value}`
+    );
+  }
+  return value;
+}
+
+function validateExamples(
+  arr: unknown,
+  field: string
+): ZentiExample[] {
+  if (!Array.isArray(arr)) {
+    throw new ZentiValidationError(`${field} debe ser un array`);
+  }
+  return arr.map((ex: unknown, i: number) => {
+    if (!ex || typeof ex !== 'object') {
+      throw new ZentiValidationError(`${field}[${i}] debe ser un objeto`);
+    }
+    const item = ex as Record<string, unknown>;
+    if (!item.user || !item.agent) {
+      throw new ZentiValidationError(
+        `${field}[${i}] debe tener los campos "user" y "agent"`
+      );
+    }
+    return { user: String(item.user), agent: String(item.agent) };
+  });
+}
+
+export function parseZenti(content: string): ZentiPersona {
+  let raw: unknown;
+  try {
+    raw = yaml.load(content);
+  } catch (e) {
+    throw new ZentiValidationError(`YAML inválido: ${(e as Error).message}`);
+  }
+
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new ZentiValidationError('El archivo debe ser un objeto YAML válido');
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  // Top-level required fields
+  if (!obj.version) throw new ZentiValidationError('Falta el campo requerido: version');
+  if (!obj.name) throw new ZentiValidationError('Falta el campo requerido: name');
+  if (!obj.core) throw new ZentiValidationError('Falta la capa requerida: core');
+  if (!obj.identity) throw new ZentiValidationError('Falta la capa requerida: identity');
+  if (!obj.examples) throw new ZentiValidationError('Falta la capa requerida: examples');
+  if (!obj.guardrails) throw new ZentiValidationError('Falta la capa requerida: guardrails');
+
+  // Validate core (Big Five)
+  if (typeof obj.core !== 'object' || Array.isArray(obj.core)) {
+    throw new ZentiValidationError('core debe ser un objeto');
+  }
+  const core = obj.core as Record<string, unknown>;
+  const validatedCore = {
+    openness: validateNumber(core.openness, 'core.openness'),
+    conscientiousness: validateNumber(core.conscientiousness, 'core.conscientiousness'),
+    extraversion: validateNumber(core.extraversion, 'core.extraversion'),
+    agreeableness: validateNumber(core.agreeableness, 'core.agreeableness'),
+    neuroticism: validateNumber(core.neuroticism, 'core.neuroticism'),
+  };
+
+  // Validate identity
+  if (typeof obj.identity !== 'object' || Array.isArray(obj.identity)) {
+    throw new ZentiValidationError('identity debe ser un objeto');
+  }
+  const identity = obj.identity as Record<string, unknown>;
+  if (!identity.role) throw new ZentiValidationError('Falta el campo requerido: identity.role');
+  if (!identity.backstory) throw new ZentiValidationError('Falta el campo requerido: identity.backstory');
+  if (!identity.communication_style) {
+    throw new ZentiValidationError('Falta el campo requerido: identity.communication_style');
+  }
+
+  // Validate examples
+  if (typeof obj.examples !== 'object' || Array.isArray(obj.examples)) {
+    throw new ZentiValidationError('examples debe ser un objeto');
+  }
+  const examples = obj.examples as Record<string, unknown>;
+  const onBrand = validateExamples(examples.on_brand, 'examples.on_brand');
+  const offBrand = validateExamples(examples.off_brand, 'examples.off_brand');
+
+  // Validate guardrails
+  if (typeof obj.guardrails !== 'object' || Array.isArray(obj.guardrails)) {
+    throw new ZentiValidationError('guardrails debe ser un objeto');
+  }
+  const guardrails = obj.guardrails as Record<string, unknown>;
+  if (!Array.isArray(guardrails.always)) {
+    throw new ZentiValidationError('guardrails.always debe ser un array');
+  }
+  if (!Array.isArray(guardrails.never)) {
+    throw new ZentiValidationError('guardrails.never debe ser un array');
+  }
+  if (!Array.isArray(guardrails.escalate_if)) {
+    throw new ZentiValidationError('guardrails.escalate_if debe ser un array');
+  }
+
+  return {
+    version: String(obj.version),
+    name: String(obj.name),
+    core: validatedCore,
+    identity: {
+      role: String(identity.role),
+      backstory: String(identity.backstory),
+      communication_style: String(identity.communication_style),
+    },
+    examples: {
+      on_brand: onBrand,
+      off_brand: offBrand,
+    },
+    guardrails: {
+      always: (guardrails.always as unknown[]).map(String),
+      never: (guardrails.never as unknown[]).map(String),
+      escalate_if: (guardrails.escalate_if as unknown[]).map(String),
+    },
+  };
+}

package/tests/compiler.test.ts

@@ -0,0 +1,218 @@
+import { parseZenti } from '../src/parser';
+import { toClaude } from '../src/compiler/toClaude';
+import { toOpenAI } from '../src/compiler/toOpenAI';
+import { toGemini } from '../src/compiler/toGemini';
+import { translateBigFive } from '../src/compiler/utils';
+
+const VALID_ZENTI = `
+version: "1.0"
+name: "Sofia"
+
+core:
+  openness: 0.7
+  conscientiousness: 0.9
+  extraversion: 0.4
+  agreeableness: 0.8
+  neuroticism: 0.2
+
+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"
+
+examples:
+  on_brand:
+    - user: "no funciona"
+      agent: "Entiendo tu frustración. Cuéntame qué error ves."
+  off_brand:
+    - user: "no funciona"
+      agent: "No sé, prueba reiniciando."
+
+guardrails:
+  always:
+    - "Reconocer el problema antes de dar solución"
+  never:
+    - "Decir 'no puedo' sin ofrecer alternativa"
+  escalate_if:
+    - "El usuario menciona cancelación"
+`;
+
+// ── Claude Compiler ────────────────────────────────────────────────────────
+
+describe('Compiler — Claude', () => {
+  const persona = parseZenti(VALID_ZENTI);
+  const { system } = toClaude(persona);
+
+  test('el output contiene la sección de guardrails', () => {
+    expect(system).toContain('REGLAS DE COMPORTAMIENTO');
+  });
+
+  test('el output contiene reglas always', () => {
+    expect(system).toContain('Reconocer el problema antes de dar solución');
+  });
+
+  test('el output contiene reglas never', () => {
+    expect(system).toContain("Decir 'no puedo' sin ofrecer alternativa");
+  });
+
+  test('el output contiene la condición de escalación', () => {
+    expect(system).toContain('El usuario menciona cancelación');
+  });
+
+  test('los guardrails aparecen antes que la identidad', () => {
+    const guardrailsPos = system.indexOf('REGLAS DE COMPORTAMIENTO');
+    const identityPos = system.indexOf('IDENTIDAD');
+    expect(guardrailsPos).toBeGreaterThanOrEqual(0);
+    expect(identityPos).toBeGreaterThanOrEqual(0);
+    expect(guardrailsPos).toBeLessThan(identityPos);
+  });
+
+  test('la identidad aparece antes que los ejemplos', () => {
+    const identityPos = system.indexOf('IDENTIDAD');
+    const examplesPos = system.indexOf('EJEMPLOS');
+    expect(identityPos).toBeLessThan(examplesPos);
+  });
+
+  test('el output contiene los ejemplos on_brand', () => {
+    expect(system).toContain('Entiendo tu frustración. Cuéntame qué error ves.');
+  });
+
+  test('el output contiene el nombre del agente', () => {
+    expect(system).toContain('Sofia');
+  });
+});
+
+// ── OpenAI Compiler ────────────────────────────────────────────────────────
+
+describe('Compiler — OpenAI', () => {
+  const persona = parseZenti(VALID_ZENTI);
+  const result = toOpenAI(persona);
+
+  test('el output tiene el campo system', () => {
+    expect(result).toHaveProperty('system');
+    expect(typeof result.system).toBe('string');
+    expect(result.system.length).toBeGreaterThan(0);
+  });
+
+  test('el output tiene el campo messages como array', () => {
+    expect(result).toHaveProperty('messages');
+    expect(Array.isArray(result.messages)).toBe(true);
+  });
+
+  test('los messages tienen roles user/assistant alternados', () => {
+    const roles = result.messages.map((m) => m.role);
+    expect(roles[0]).toBe('user');
+    expect(roles[1]).toBe('assistant');
+  });
+
+  test('el system prompt menciona el nombre del agente en primera persona', () => {
+    expect(result.system).toContain('Sofia');
+  });
+
+  test('el system prompt incluye los guardrails', () => {
+    expect(result.system).toContain('Siempre debes');
+    expect(result.system).toContain('Nunca debes');
+  });
+
+  test('los messages reflejan los ejemplos on_brand', () => {
+    const userMsg = result.messages.find((m) => m.role === 'user');
+    expect(userMsg?.content).toBe('no funciona');
+    const assistantMsg = result.messages.find((m) => m.role === 'assistant');
+    expect(assistantMsg?.content).toContain('frustración');
+  });
+});
+
+// ── Gemini Compiler ────────────────────────────────────────────────────────
+
+describe('Compiler — Gemini', () => {
+  const persona = parseZenti(VALID_ZENTI);
+  const result = toGemini(persona);
+
+  test('el output tiene systemInstruction', () => {
+    expect(result).toHaveProperty('systemInstruction');
+    expect(result.systemInstruction).toHaveProperty('parts');
+    expect(Array.isArray(result.systemInstruction.parts)).toBe(true);
+    expect(result.systemInstruction.parts[0]).toHaveProperty('text');
+  });
+
+  test('el output tiene contents como array', () => {
+    expect(result).toHaveProperty('contents');
+    expect(Array.isArray(result.contents)).toBe(true);
+  });
+
+  test('los contents tienen roles user/model', () => {
+    const roles = result.contents.map((c) => c.role);
+    expect(roles[0]).toBe('user');
+    expect(roles[1]).toBe('model');
+  });
+
+  test('systemInstruction incluye la identidad del agente', () => {
+    const text = result.systemInstruction.parts[0].text;
+    expect(text).toContain('Sofia');
+    expect(text).toContain('Asistente de soporte de TechCorp');
+  });
+
+  test('systemInstruction incluye los guardrails', () => {
+    const text = result.systemInstruction.parts[0].text;
+    expect(text).toContain('Siempre');
+    expect(text).toContain('Nunca');
+  });
+
+  test('los contents parts tienen la forma { text: string }', () => {
+    result.contents.forEach((content) => {
+      expect(Array.isArray(content.parts)).toBe(true);
+      content.parts.forEach((part) => {
+        expect(part).toHaveProperty('text');
+        expect(typeof part.text).toBe('string');
+      });
+    });
+  });
+});
+
+// ── Big Five Translation ───────────────────────────────────────────────────
+
+describe('Compiler — translateBigFive', () => {
+  test('openness > 0.6 genera el trait correspondiente', () => {
+    const traits = translateBigFive({
+      openness: 0.7,
+      conscientiousness: 0.5,
+      extraversion: 0.5,
+      agreeableness: 0.5,
+      neuroticism: 0.5,
+    });
+    expect(traits.some((t) => t.includes('creativo'))).toBe(true);
+  });
+
+  test('extraversion < 0.5 genera el trait de reservado', () => {
+    const traits = translateBigFive({
+      openness: 0.5,
+      conscientiousness: 0.5,
+      extraversion: 0.4,
+      agreeableness: 0.5,
+      neuroticism: 0.5,
+    });
+    expect(traits.some((t) => t.includes('reservado'))).toBe(true);
+  });
+
+  test('valores sin umbral no generan ningún trait', () => {
+    const traits = translateBigFive({
+      openness: 0.5,
+      conscientiousness: 0.5,
+      extraversion: 0.5,
+      agreeableness: 0.5,
+      neuroticism: 0.5,
+    });
+    expect(traits).toHaveLength(0);
+  });
+
+  test('Sofia genera todos los traits esperados', () => {
+    const traits = translateBigFive({
+      openness: 0.7,          // > 0.6 → creativo
+      conscientiousness: 0.9, // > 0.7 → metódico
+      extraversion: 0.4,      // < 0.5 → reservado
+      agreeableness: 0.8,     // > 0.7 → empático
+      neuroticism: 0.2,       // < 0.3 → calmado
+    });
+    expect(traits).toHaveLength(5);
+  });
+});