@homunculus-live/introspection

Phase 3 utilities for planning agent societies and detecting when a society has reached equilibrium. This package currently focuses on signal-based planning and a goal-satisfaction detector inspired by Minsky's difference engine.

Features

• Signal society planner: emits a JSON plan describing agents to spawn for a given goal.
• Signal agent factory: materializes homunculus agents from a plan signal.
• Equilibrium detector: measures goal tension, momentum, coherence, and decision clarity to decide when thinking has converged.

Exports

• createSignalSocietyPlanner
• createSignalAgentFactory
• EquilibriumDetector

Usage

Plan a signal society

import { createSignalSocietyPlanner } from '@homunculus-live/introspection';
import { LLMClient } from '@homunculus-live/semantic-engine';

const llm = new LLMClient({
  baseURL: process.env.LLM_BASE_URL ?? '',
  apiKey: process.env.LLM_API_KEY ?? '',
  model: process.env.LLM_MODEL ?? '',
});

const planner = createSignalSocietyPlanner({
  llm,
  maxAgents: 5,
  debug: true,
});

for await (const planSignal of planner.emit({
  id: 'goal-1',
  thought: 'Design an onboarding flow for a new developer tool.',
  emittedBy: 'user',
  timestamp: Date.now(),
})) {
  console.log(planSignal);
}

Spawn agents from a plan

import { createSignalAgentFactory } from '@homunculus-live/introspection';
import { defineHomunculusAgent } from '@homunculus-live/core';
import { LLMClient } from '@homunculus-live/semantic-engine';

const llm = new LLMClient({
  baseURL: process.env.LLM_BASE_URL ?? '',
  apiKey: process.env.LLM_API_KEY ?? '',
  model: process.env.LLM_MODEL ?? '',
});

const birth = (agent: ReturnType<typeof defineHomunculusAgent>) => {
  // Register the agent in your biosphere.
  console.log('Born:', agent.id);
};

const factory = createSignalAgentFactory({ llm, birth, debug: true });

for await (const resultSignal of factory.emit({
  id: 'plan-1',
  thought: JSON.stringify({
    version: 'v1-signal',
    goal: 'Design an onboarding flow for a new developer tool.',
    agents: [
      {
        id: 'copy-guide',
        name: 'Copy Guide',
        receptor_patterns: ['copy', 'voice', 'microcopy'],
        threshold: 0.6,
        voice: 'Write crisp onboarding microcopy.',
      },
    ],
  }),
  emittedBy: 'planner',
  timestamp: Date.now(),
})) {
  console.log(resultSignal);
}

Detect equilibrium

import { EquilibriumDetector } from '@homunculus-live/introspection';

const detector = new EquilibriumDetector({
  llm: {
    embed: async text => [],
    chat: async messages => 'A clear decision has been reached.',
  },
});

const state = await detector.detect('Decide launch plan', signals, agents);
console.log(state.atEquilibrium, state.reasoning);

Notes

• The planner and factory are signal-first: they operate on Signal.thought strings and emit JSON payloads as signals.
• The equilibrium detector relies on LLM embeddings and chat to extract an ideal end state and compare it to recent signals.