API_REFERENCE.md

📚 API_REFERENCE.md — Public Functions & Types

Descripción: Todas las funciones públicas que puede usar un agente entrante.

---

🎯 HEARTBEAT.ts — El Loop Principal

Archivo: src/omega/heartbeat.ts
Propósito: Main loop autónomo que ejecuta cada ciclo

Función Principal

export async function runHeartbeat(
  context: HeartbeatContext,
  options?: HeartbeatOptions
): Promise<HeartbeatResult>

Parámetros:

• context: HeartbeatContext — Estado actual del sistema
• options?: HeartbeatOptions — Configuración optional

Retorna:

{
  cycleId: string;
  decisions: Decision[];
  executed: number;
  tension_before: number;
  tension_after: number;
  logs: LogEntry[];
}

Ejemplo:

const result = await runHeartbeat({
  current_state: {...},
  memory: episodicRecall
}, { verbose: true });

console.log(`Decisiones ejecutadas: ${result.executed}`);

Sub-funciones (internas, pero accesibles)

// Detecta señales de tensión
async function checkTensionSignals(state): Promise<TensionSignal[]>

// Evalúa qué hacer (elige motor)
async function evaluateDrives(state, signals): Promise<Decision>

// Ejecuta decisión en el mundo
async function executeDecision(decision): Promise<ExecutionResult>

---

🧠 NEURAL_LOGIC_ENGINE.ts — Razonamiento sin LLM

Archivo: src/omega/neural-logic-engine.ts
Propósito: Inference lógico/simbólico sin llamadas al LLM

Clase Principal

export class NeuralLogicEngine {
  constructor(rules?: Rule[], embeddings?: Embedding[])
  
  // Razona sobre un contexto
  async reason(
    context: ReasoningContext,
    state: AgentState
  ): Promise<LogicalConclusion>
  
  // Aprende de una experiencia
  async learn(episode: Episode): Promise<void>
  
  // Obtiene reglas aplicables
  getRules(context: ReasoningContext): Rule[]
}

Ejemplo:

const engine = new NeuralLogicEngine();

const conclusion = await engine.reason({
  query: "¿Debería resetear la conexión?",
  available_actions: ["reset", "retry", "abort"]
}, agentState);

// conclusion.action = "reset"
// conclusion.confidence = 0.95

Reglas internas: ~64 reglas aprendidas (en latent space)

---

💾 EPISODIC_RECALL.ts — Memoria Consolidada

Archivo: src/omega/episodic-recall.ts
Propósito: Almacenar y recuperar episodios aprendidos

Clase Principal

export class EpisodicRecall {
  constructor()
  
  // Almacena un episodio
  async store(episode: Episode): Promise<void>
  
  // Recupera similares
  async retrieve(query: RetrievalQuery): Promise<Episode[]>
  
  // Consolida episodios múltiples
  async consolidate(): Promise<void>
}

Estructura de Episode:

interface Episode {
  id: string;
  timestamp: Date;
  state: AgentState;
  action: Decision;
  outcome: Outcome;
  lesson?: string;
  embedding?: number[];  // Embedding semántico
}

Ejemplo:

const recall = new EpisodicRecall();

// Guardar un episodio
await recall.store({
  state: {...},
  action: decision,
  outcome: { success: true, time_ms: 150 }
});

// Recuperar aprendizajes similares
const similar = await recall.retrieve({
  query: "¿Qué pasó cuando intenté conexión remota?",
  limit: 5
});

---

⚡ OLLAMA_STREAM.ts — Inferencia

Archivo: src/agents/ollama-stream.ts
Propósito: Llamadas a modelos de lenguaje (cloud + local)

Función Principal

async function createOllamaStreamResponse(
  prompt: string,
  model: string,
  options?: InferenceOptions
): Promise<string>

Parámetros:

• prompt: string — Lo que preguntar
• model: string — 'kimi-k2.5:cloud' o 'qwen3.5:latest'
• options.temperature?: number — [0.1, 1.0]
• options.timeout?: number — ms (default: 60000)

Retorna: Texto de respuesta completa

Ejemplo:

const response = await createOllamaStreamResponse(
  "¿Cuál es el siguiente paso?",
  "kimi-k2.5:cloud",
  { timeout: 60000 }
);

POC-1 Integration (interno)

// Automático: temperature se ajusta según modelo
// qwen3.5:latest → T=0.3 (reducido por POC-1)
// kimi-k2.5:cloud → T=0.7 (sin cambio)

---

🛡️ LYAPUNOV_CONTROLLER.ts — Homeostasis

Archivo: src/omega/lyapunov-controller.ts
Propósito: Detecta y mitiga divergencia/estrés

Clase Principal

export class LyapunovController {
  constructor(options?: ControllerOptions)
  
  // Calcula divergencia actual
  calculateDivergence(
    state_current: State,
    state_previous: State,
    prediction: Prediction
  ): number  // [0.0, 1.0]
  
  // Aplica control (damping)
  applyControl(
    state: State,
    divergence: number
  ): ControlSignal
}

Señales de Control:

enum ControlZone {
  VERDE = "divergence < 0.3",      // OK
  AMARILLO = "0.3 <= d < 0.6",     // Reduce temperature
  ROJO = "d >= 0.6"                // Fallback a rules
}

Ejemplo:

const controller = new LyapunovController();

const div = controller.calculateDivergence(
  currentState,
  previousState,
  nextStatePrediction
);

if (div > 0.6) {
  const signal = controller.applyControl(currentState, div);
  // signal.action = "use_rules_only"  // Evitar LLM
}

---

🌀 ENTROPY_MINIMIZATION_LOOP.ts — Homeostasis

Archivo: src/omega/entropy-minimization-loop.ts
Propósito: Reduce desorden interno

Función Principal

export async function minimizeEntropy(
  system_state: SystemState
): Promise<EntropySummary>

Acciones:

• Detecta contradicciones
• Consolida episodios similares
• Actualiza reglas si es necesario
• Limpia log temporal

Retorna:

{
  entropy_before: number;
  entropy_after: number;
  changes_made: number;
  time_ms: number;
}

---

📊 TYPES.ts — Estructuras Clave

Archivo: src/omega/types.ts
Propósito: Tipos compartidos

// Estado del agente
interface AgentState {
  id: string;
  cycle: number;
  tension: number;           // [0.0, 1.0]
  autonomy_level: number;    // [0.0, 1.0]
  memory: EpisodicRecall;
  rules: Rule[];
}

// Decisión que tomar
interface Decision {
  action: string;
  confidence: number;
  reasoning: string;
  estimated_time_ms: number;
}

// Resultado de ejecución
interface ExecutionResult {
  success: boolean;
  output?: string;
  error?: string;
  time_ms: number;
}

---

🎯 ENTRY POINTS PARA AGENTES

Si necesitas RAZONAR (sin LLM)

→ NeuralLogicEngine.reason()

Si necesitas APRENDER

→ EpisodicRecall.store() + .consolidate()

Si necesitas PREGUNTAR AL LLM

→ createOllamaStreamResponse()

Si necesitas DETECTAR ESTRÉS

→ LyapunovController.calculateDivergence()

Si necesitas ENTENDER ESTADO

→ runHeartbeat() retorna HeartbeatResult

---

⚠️ LO QUE NO HAGAS

❌ No llamar directamente a temperatura hardcoded
   → Usa createOllamaStreamResponse() (incluye POC-1)

❌ No ignorar LyapunovController si divergence > 0.6
   → Significa que algo está mal

❌ No almacenar estado en memoria volátil
   → Usa EpisodicRecall o session logs

❌ No ejecutar heartbeat sin verificar CURRENT_STATE.md
   → Puede haber problemas conocidos

---

🔍 Ejemplo Completo: Un Ciclo

// 1. En heartbeat.ts:
const result = await runHeartbeat(context);

// 2. Internamente, eso llama:
const signals = await checkTensionSignals(state);  // Detecta problema

// 3. Elige qué hacer:
const decision = await evaluateDrives(state, signals);
// decision.action = "query_llm"

// 4. Ejecuta:
if (decision.action === "query_llm") {
  const response = await createOllamaStreamResponse(
    decision.prompt,
    "kimi-k2.5:cloud"
    // POC-1 automáticamente ajusta temp si es qwen
  );
}

// 5. Aprende del resultado:
const episode: Episode = {
  state: state,
  action: decision,
  outcome: { success: true, ... }
};
await episodicRecall.store(episode);

// 6. Log:
await logState(result);

---

Para más detalles: Lee el código fuente directamente.
Para entender decisiones: Ver ARCHITECTURE_DECISIONS.md.
Para verificar estado: Ver CURRENT_STATE.md.