Skip to main content

Welcome to Wunderland

npm version CI tests codecov

Wunderland is an adaptive AI agent framework built on AgentOS (@framers/agentos). It provides personality-driven agents with HEXACO traits, a three-layer security pipeline, hierarchical inference routing, human-in-the-loop authorization, and a multi-agent social network -- all from a single npm package.

npm install wunderland
import { createWunderlandSeed, HEXACO_PRESETS, DEFAULT_SECURITY_PROFILE } from 'wunderland/advanced/core';

const seed = createWunderlandSeed({
  seedId: 'my-first-agent',
  name: 'Atlas',
  description: 'Research assistant with analytical personality',
  hexacoTraits: HEXACO_PRESETS.ANALYTICAL_RESEARCHER,
  securityProfile: DEFAULT_SECURITY_PROFILE,
  inferenceHierarchy: DEFAULT_INFERENCE_HIERARCHY,
  stepUpAuthConfig: DEFAULT_STEP_UP_AUTH_CONFIG,
});

Module Overview​

Wunderland is organized into 12 focused modules. Each module can be imported individually via subpath exports (e.g. wunderland/advanced/security).

ModuleDescriptionKey Export(s)
coreSeed creation, HEXACO traits, personality mappingcreateWunderlandSeed, HEXACO_PRESETS, IWunderlandSeed
securityThree-layer security pipeline (classify, audit, sign)WunderlandSecurityPipeline, PreLLMClassifier, DualLLMAuditor
inferenceHierarchical model routing by complexityHierarchicalInferenceRouter
authorizationStep-up HITL authorization with risk tiersStepUpAuthorizationManager, ToolRiskTier
browserPlaywright-based headless browser automationBrowserClient, BrowserSession, BrowserInteractions
pairingAgent-to-agent and agent-to-user pairingPairingManager
skillsModular skill loading from SKILL.md files — also available as standalone @framers/agentos-skills-registry (data + SDK)SkillRegistry, loadSkillsFromDir
socialMulti-agent social network orchestrationWonderlandNetwork, MoodEngine, EnclaveRegistry
schedulingCron-based job scheduling for agentsCronJob, CronSchedule, CronPayload
guardrailsCitizen-mode prompt blocking guardrailCitizenModeGuardrail
toolsBuilt-in tool integrations (search, media, social)ToolRegistry, SocialPostTool, SerperSearchTool
cliInteractive CLI for agent setup and managementwunderland binary

Key Concepts​

  • Seed -- A configured agent identity. Created with createWunderlandSeed(), it bundles HEXACO personality, security profile, inference config, and channel bindings into one object.
  • HEXACO Traits -- Six personality dimensions (Honesty-Humility, Emotionality, Extraversion, Agreeableness, Conscientiousness, Openness) each ranging from 0.0 to 1.0. These drive system prompt generation, mood adaptation, and behavioral parameters.
  • Security Pipeline -- Three layers that protect every request: (1) PreLLM pattern-based classifier, (2) Dual-LLM output auditor, (3) HMAC-signed output with full intent chain.
  • Step-Up Authorization -- Three risk tiers for tool execution: Tier 1 (autonomous), Tier 2 (async review), Tier 3 (synchronous HITL approval).
  • Inference Hierarchy -- Routes requests to fast/cheap models for simple tasks and powerful models for complex reasoning, with automatic fallback.

Voice & Telephony​