ANIMA Plugin SDK

Build plugins that remember, dream, and learn. This documentation covers everything you need to extend ANIMA with your own plugins.

What is ANIMA?

ANIMA is an AI platform with two jobs:

The core engine is compiled in Rust (exposed to Python via PyO3). Plugins are pure Python — drop a folder in plugins/ and it loads automatically.

Quick Start

Create a plugin in three files:

1. Plugin code

# my_plugin/plugin.py
from core.plugin_loader import AnimaPlugin

class MyPlugin(AnimaPlugin):
    def on_start(self, engine):
        """Called when ANIMA starts this plugin."""
        print(f"Started! {engine.get_belief_count()} beliefs in graph.")

    def get_prompts(self):
        """Custom extraction prompts for this plugin's domain."""
        return {
            "extraction_prompt": "Read this document and extract...",
            "system_prompt": "You are a domain expert in...",
        }

    def on_cycle_complete(self, engine, cycle_number, stats):
        """Called after each ANIMA cycle completes."""
        beliefs = stats.get("beliefs", 0)
        edges = stats.get("edges", 0)
        print(f"Cycle {cycle_number}: {beliefs} beliefs, {edges} edges")

2. Manifest

# my_plugin/plugin.toml
[plugin]
name = "my-plugin"
version = "0.1.0"
description = "My first ANIMA plugin"
author = "Your Name"
license = "free"
port = 8905

3. Install and run

$ cp -r my_plugin/ ~/anima/plugins/
$ ./anima start
# Dashboard at http://localhost:8900

Your plugin loads automatically. ANIMA discovers it by scanning the plugins/ directory on startup.

Core Concepts

Beliefs

Persistent knowledge units extracted from documents and conversations. CRUD operations, search, deprecation.

Knowledge Graph

Links between beliefs form a graph. Components, bridges, domain diversity, and integration metrics.

Dreams

Cross-domain synthesis that finds connections between distant beliefs. Consolidation scheduling and quality gates.

Router

Blocking load balancer with capability scoring, health monitoring, reservation-based dispatch, and async queuing.

Curiosity

Knowledge gap detection with priority-based questions, decay cycles, and automatic dissolution.

Security

Per-plugin encrypted vault, license management, and permission enforcement.

Docs Sync

Local checklist and checker for keeping API, settings, release stats, and public-safe examples aligned with source.

Requirements