open-index/open-npm huggingface dataset:
npm package: @homunculus-live/core
Description: Biological agent framework core primitives.
Latest version: 0.1.0

# @homunculus-live/core

Core primitives for the homunculus biological agent framework: homunculus agents, signals, synapses, and the biosphere router.

## Install
```bash
pnpm add @homunculus-live/core
```

## Quick start
```ts
import { Biosphere, 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 biosphere = new Biosphere({ llm });

const producer = defineHomunculusAgent({
  id: 'producer',
  name: 'DataProducer',
  receptorField: {
    patterns: ['start', 'generate data'],
    threshold: 0.6,
  },
  systemPrompt: 'You generate random numbers when asked.',
  llm,
  async *emit() {
    yield `I generated a random number: ${Math.random()}`;
  },
});

const consumer = defineHomunculusAgent({
  id: 'consumer',
  name: 'DataConsumer',
  receptorField: {
    patterns: ['random number', 'generated data'],
    threshold: 0.6,
  },
  systemPrompt: 'You acknowledge receiving data.',
  llm,
});

await biosphere.birth(producer);
await biosphere.birth(consumer);

await biosphere.inject('please generate some data');

for await (const state of biosphere.live()) {
  console.log(`Tick ${state.tick}: ${state.signals.length} signals`);
  if (state.tick >= 3) break;
}
```

## Key ideas
- **Signal**: Natural language thought + `pheromone` embedding for routing.
- **HomunculusAgent**: Perceives signals and emits thoughts via LLM.
- **ReceptorField**: Natural language patterns an agent resonates with.
- **SignalSynapse**: Adaptive coupling that transforms signals across vocabularies.
- **Biosphere**: Embeds thoughts, routes via semantic resonance, and can spawn helpers.

## Exports
- `Biosphere`, `HomunculusAgent`, `defineHomunculusAgent`, `defineMetaObserver`
- `Signal`, `ReceptorField`, `createSignal`, `resonates`
- `SignalSynapse`, `createSignalSynapse`, `SynapticStrength`

## Notes
- ESM only; TypeScript declarations included.
- Pair with `@homunculus-live/semantic-engine` for embeddings and chat.
npm package: @homunculus-live/primitives
Description: Built-in primitive agents for homunculus (vision, memory, reasoning, action).
Latest version: 0.1.0

# @homunculus-live/primitives

Primitive building blocks for homunculus. This package currently ships a single agent: the signal intent analyzer.

## Agents

- **SignalIntentAnalyzer**: consumes raw signals (thought text) and emits a clarified natural-language intent summary.

## Usage

```ts
import { createSignalIntentAnalyzer } from '@homunculus-live/primitives';
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 analyzer = createSignalIntentAnalyzer({ llm, debug: false });
```

Wire it into a `Biosphere` and let synapses form automatically.

## Scripts
- `pnpm build`
- `pnpm test`

## Notes
- The analyzer expects thought text and responds with a short natural-language intent summary.
npm package: @homunculus-live/semantic-engine
Description: Semantic matching and LLM glue for homunculus.
Latest version: 0.1.0

# @homunculus-live/semantic-engine

Provider-agnostic LLM client + semantic distance utilities for homunculus.

## Install
```bash
pnpm add @homunculus-live/semantic-engine
```

## LLM Client
```ts
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!, // chat/transform model
  embeddingModel: process.env.LLM_EMBED_MODEL, // optional override
});

const vector = await llm.embed('hello world');
const reply = await llm.chat([{ role: 'user', content: 'Say hi' }]);
const transformed = await llm.transform('Reformat JSON', { foo: 'bar' });
```

## Semantic Distance
```ts
import { calculateSemanticDistance } from '@homunculus-live/semantic-engine';
import { createEmitter, createReceptor } from '@homunculus-live/core';

const emitter = createEmitter({ intent: 'numbers', tags: ['data'] });
const receptor = createReceptor({ desire: 'numbers', tags: ['data'] });
const distance = await calculateSemanticDistance(emitter, receptor, llm, {
  tagWeight: 0.4,
  skipEmbeddings: true,
});
```

### Behavior
- Combines tag overlap and cosine similarity of embeddings.
- Embeddings are fetched lazily via `LLMClient.embed` and cached on signatures.
- `skipEmbeddings` forces tag-only distance (recommended for low-cost matching).
- Weighted blend defaults: tagWeight=0.4, embeddingWeight=0.6.

## Notes
- ESM only, TypeScript declarations included.
- OpenAI api compatible endpoints
npm package: @homunculuslabs/plugin-zai
Description: z.ai provider plugin for elizaOS.
Latest version: 2.0.0-alpha.1

# @homunculuslabs/plugin-zai

z.ai provider plugin for elizaOS.

This plugin targets **z.ai’s Anthropic-compatible API** and supports:
- `TEXT_SMALL`, `TEXT_LARGE`
- `OBJECT_SMALL`, `OBJECT_LARGE`

## Install

```bash
npm install @homunculuslabs/plugin-zai
# or
bun add @homunculuslabs/plugin-zai
```

## Configuration

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `ZAI_API_KEY` | Yes | – | z.ai API key |
| `ZAI_BASE_URL` | No | `https://api.z.ai/api/anthropic/v1` | Anthropic-compatible base URL (should end in `/v1`) |
| `ZAI_SMALL_MODEL` | No | `claude-sonnet-4-20250514` | Small model id |
| `ZAI_LARGE_MODEL` | No | `claude-sonnet-4-20250514` | Large model id |

## Quick start

```ts
import { AgentRuntime, ModelType } from "@elizaos/core";
import zaiPlugin from "@homunculuslabs/plugin-zai";

const runtime = new AgentRuntime({ plugins: [zaiPlugin] });

const text = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Write a haiku about local-first AI.",
});

console.log(text);
```