API Reference

All public exports from minions-sdk. The library is framework-agnostic, storage-agnostic, and has zero runtime dependencies.

TypeScript

import {
  // Types
  type FieldType, type FieldValidation, type FieldDefinition,
  type RelationType, type MinionStatus, type MinionPriority,
  type Minion, type MinionType, type Relation,
  type CreateMinionInput, type UpdateMinionInput, type CreateRelationInput,
  type ExecutionResult, type Executable,
  type ValidationError, type ValidationResult,

  // Validation
  validateField, validateFields,

  // Schemas
  noteType, linkType, fileType, contactType,
  agentType, teamType, thoughtType, promptTemplateType, testCaseType, taskType,
  builtinTypes,

  // Registry
  TypeRegistry,

  // Relations
  RelationGraph,

  // Client
  Minions,

  // Middleware
  type MinionMiddleware, type MinionContext, type MinionOperation,
  runMiddleware,

  // Lifecycle
  createMinion, updateMinion, softDelete, hardDelete, restoreMinion,

  // Evolution
  migrateMinion,

  // Storage
  type StorageAdapter, type StorageFilter, type StorageHooks,
  MemoryStorageAdapter, JsonFileStorageAdapter,
  withHooks,

  // Utilities
  generateId, now, SPEC_VERSION,
} from 'minions-sdk';

Python

from minions import (
    # Types (also available from minions.types)
    Minion, MinionType, Relation, FieldDefinition, FieldValidation,
    CreateMinionInput, UpdateMinionInput, CreateRelationInput,
    ExecutionResult, Executable,
    # Validation
    ValidationError, ValidationResult, validate_field, validate_fields,
    # Schemas
    note_type, link_type, file_type, contact_type,
    agent_type, team_type, thought_type, prompt_template_type,
    test_case_type, task_type, builtin_types,
    # Registry
    TypeRegistry,
    # Relations
    RelationGraph,
    # Client
    Minions, MinionWrapper, MinionPlugin,
    # Middleware
    MinionMiddleware, MinionContext, MinionOperation, run_middleware,
    # Lifecycle
    create_minion, update_minion, soft_delete, hard_delete, restore_minion,
    # Evolution
    migrate_minion,
    # Storage
    StorageAdapter, StorageFilter, MemoryStorageAdapter, JsonFileStorageAdapter,
    with_hooks, StorageHooks,
    # Utilities
    generate_id, now, SPEC_VERSION,
)

---

Validation

validateField / validate_field

Validate a single field value against its FieldDefinition.

TypeScript

function validateField(value: unknown, field: FieldDefinition): ValidationError[]

Python

def validate_field(value: Any, field_def: FieldDefinition) -> list[ValidationError]

Returns a list of ValidationError objects. Empty list means valid.

Rules:

• If required is true and the value is undefined | null | "", validation fails immediately.
• If the value is absent and not required, no further checks are performed.
• Otherwise, type-specific validation is applied (see Field Types).

validateFields / validate_fields

Validate all fields of a minion against a MinionType schema.

TypeScript

function validateFields(
  fields: Record<string, unknown>,
  schema: FieldDefinition[]
): ValidationResult

Python

def validate_fields(
    fields: dict[str, Any],
    schema: list[FieldDefinition],
) -> ValidationResult

Returns { valid: boolean, errors: ValidationError[] } (TS) or a ValidationResult object (Python).

---

Schemas

Built-in Type Constants

Pre-defined MinionType objects for all built-in types:

TypeScript	Python	Slug	Layer
noteType	note_type	note	—
linkType	link_type	link	—
fileType	file_type	file	—
contactType	contact_type	contact	—
agentType	agent_type	agent	Definition
teamType	team_type	team	Organization
thoughtType	thought_type	thought	Memory
promptTemplateType	prompt_template_type	prompt-template	Interface
testCaseType	test_case_type	test-case	Evaluation
taskType	task_type	task	Execution

builtinTypes / builtin_types

Array/list containing all 10 built-in types.

---

TypeRegistry

An in-memory registry for MinionType objects. Pre-loaded with all built-in types by default.

TypeScript

const registry = new TypeRegistry(loadBuiltins?: boolean);

registry.register(type: MinionType): void;       // throws on duplicate
registry.getById(id: string): MinionType | undefined;
registry.getBySlug(slug: string): MinionType | undefined;
registry.list(): MinionType[];
registry.has(id: string): boolean;
registry.remove(id: string): boolean;

Python

registry = TypeRegistry(load_builtins: bool = True)

registry.register(type: MinionType) -> None       # raises ValueError on duplicate
registry.get_by_id(id: str) -> MinionType | None
registry.get_by_slug(slug: str) -> MinionType | None
registry.list() -> list[MinionType]
registry.has(id: str) -> bool
registry.remove(id: str) -> bool

---

RelationGraph

In-memory relation graph manager. Provides utilities to add, remove, query, and traverse typed relations between minions.

TypeScript

const graph = new RelationGraph();

graph.add(input: CreateRelationInput): Relation;
graph.remove(id: string): boolean;
graph.removeByMinionId(minionId: string): number;
graph.get(id: string): Relation | undefined;
graph.list(): Relation[];
graph.getFromSource(sourceId: string, type?: RelationType): Relation[];
graph.getToTarget(targetId: string, type?: RelationType): Relation[];
graph.getChildren(parentId: string): string[];
graph.getParents(childId: string): string[];
graph.getTree(rootId: string): string[];      // depth-first, handles cycles
graph.getNetwork(minionId: string): string[];

Python

graph = RelationGraph()

graph.add(input: dict) -> Relation
graph.remove(id: str) -> bool
graph.remove_by_minion_id(minion_id: str) -> int
graph.get(id: str) -> Relation | None
graph.list() -> list[Relation]
graph.get_from_source(source_id: str, type: str | None = None) -> list[Relation]
graph.get_to_target(target_id: str, type: str | None = None) -> list[Relation]
graph.get_children(parent_id: str) -> list[str]
graph.get_parents(child_id: str) -> list[str]
graph.get_tree(root_id: str) -> list[str]     # depth-first, handles cycles
graph.get_network(minion_id: str) -> list[str]

---

Lifecycle

TypeScript

// Create — generates id, timestamps, validates, applies defaults
const { minion, validation } = createMinion(input, type);

// Update — merges fields, re-validates, strips undefined
const { minion: updated } = updateMinion(minion, input, type);

// Soft delete — sets deletedAt/deletedBy
const deleted = softDelete(minion, 'user-123');

// Hard delete — removes all relations from the graph
hardDelete(minion, graph);

// Restore — clears deletedAt/deletedBy
const restored = restoreMinion(deleted);

Python

# Create — generates id, timestamps, validates, applies defaults
minion, validation = create_minion(input_dict, type)

# Update — merges fields, re-validates, strips None
updated, validation = update_minion(minion, input_dict, type)

# Soft delete — sets deleted_at/deleted_by
deleted = soft_delete(minion, "user-123")

# Hard delete — removes all relations from the graph
hard_delete(minion, graph)

# Restore — clears deleted_at/deleted_by
restored = restore_minion(deleted)

Note: hardDelete / hard_delete handles relation cleanup only (this is intentional — Minions is storage-agnostic). After calling it, you must also remove the minion object from your storage layer (array, database, etc.).

---

Minions Client

The central facade for the Minions ecosystem. Orchestrates TypeRegistry, RelationGraph, and supports optional middleware and storage.

TypeScript

const minions = new Minions({
  storage?: StorageAdapter,
  middleware?: MinionMiddleware[],
  plugins?: MinionPlugin[],
});

// All lifecycle methods are async
await minions.create(typeSlug, input);     // → MinionWrapper
await minions.update(minion, input);       // → MinionWrapper
await minions.softDelete(minion);          // → MinionWrapper
await minions.hardDelete(minion);          // → void
await minions.restore(minion);             // → MinionWrapper

// Storage methods (requires storage adapter)
await minions.save(minion);               // → void
await minions.load(id);                   // → Minion | undefined
await minions.remove(minion);             // → void
await minions.listMinions(filter?);       // → Minion[]
await minions.searchMinions(query);       // → Minion[]

Python

minions = Minions(
    storage=None,          # Optional[StorageAdapter]
    middleware=None,       # Optional[list[MinionMiddleware]]
    plugins=None,          # Optional[list[MinionPlugin]]
)

# All lifecycle methods are async
await minions.create(type_slug, input_data)  # → MinionWrapper
await minions.update(minion, input_data)     # → MinionWrapper
await minions.soft_delete(minion)            # → MinionWrapper
await minions.hard_delete(minion)            # → None
await minions.restore(minion)                # → MinionWrapper

# Storage methods (requires storage adapter)
await minions.save(minion)                  # → None
await minions.load(id)                      # → Minion | None
await minions.remove(minion)                # → None
await minions.list_minions(filter)           # → list[Minion]
await minions.search_minions(query)          # → list[Minion]

---

Middleware

MinionMiddleware

A callable that intercepts any Minions client operation. Follows a Koa-style onion model.

TypeScript

type MinionMiddleware = (ctx: MinionContext, next: NextFn) => Promise<void>;

Python

MinionMiddleware = Callable[[MinionContext, NextFn], Awaitable[None]]

MinionContext

Property	Type	Description
operation	MinionOperation	The operation being intercepted
args	Record<string, any> / dict	Operation arguments
result	any	Set by the core operation after next()
metadata	Record<string, any> / dict	Free-form cross-middleware state

MinionOperation

"create" | "update" | "softDelete" | "hardDelete" | "restore" | "save" | "load" | "remove" | "list" | "search"

runMiddleware / run_middleware

Execute a middleware pipeline manually (used internally by the Minions client).

TypeScript

function runMiddleware(
  middlewares: MinionMiddleware[],
  ctx: MinionContext,
  core: () => Promise<void>,
): Promise<void>

Python

async def run_middleware(
    middlewares: list[MinionMiddleware],
    ctx: MinionContext,
    core: Callable[[], Awaitable[None]],
) -> None

---

Storage Hooks

withHooks / with_hooks

Wrap any StorageAdapter with before/after hooks.

TypeScript

function withHooks(adapter: StorageAdapter, hooks: StorageHooks): StorageAdapter

Python

def with_hooks(adapter: StorageAdapter, hooks: StorageHooks) -> StorageAdapter

StorageHooks

Hook	Signature	Notes
beforeGet	(id) → void
afterGet	(id, result?) → void
beforeSet	(minion) → Minion?	Can return a transformed minion
afterSet	(minion) → void
beforeDelete	(id) → void
afterDelete	(id) → void
beforeList	(filter?) → void
afterList	(results, filter?) → void
beforeSearch	(query) → void
afterSearch	(results, query) → void

---

Evolution

migrateMinion / migrate_minion

Migrates a minion when its type schema changes:

Change	Behavior
Field removed	Value moves to _legacy
Field type changed (incompatible)	Value moves to _legacy
Field added	Gets default value or remains absent
updatedAt	Always updated

---

Key Differences Between SDKs

Concept	TypeScript	Python
Field names	camelCase	snake_case
Return style	{ minion, validation }	(minion, validation) tuple
Relation input keys	sourceId, targetId	source_id, target_id
Method names	getBySlug()	get_by_slug()
Cross-SDK JSON	Native object	minion.to_dict() → camelCase
Error on duplicate	Throws Error	Raises ValueError

---

Utilities

generateId / generate_id

Returns a new UUID v4 string.

now

Returns the current time as an ISO 8601 string.

SPEC_VERSION

Current specification version ("0.1.0").

---

Types

Core Primitives

Type	Description
Minion	A structured object instance
MinionType	Schema/definition of a kind of minion
Relation	Typed directional link between two minions

Input Types

Type	Description
CreateMinionInput	Input for createMinion / create_minion
UpdateMinionInput	Input for updateMinion / update_minion (all fields optional)
CreateRelationInput	Input for RelationGraph.add

Enums

Type	Values
FieldType	string, number, boolean, date, select, multi-select, url, email, textarea, tags, json, array
RelationType	parent_of, depends_on, implements, relates_to, inspired_by, triggers, references, blocks, alternative_to, part_of, follows, integration_link
MinionStatus	active, todo, in_progress, completed, cancelled
MinionPriority	low, medium, high, urgent

Execution Contract

Type	Description
Executable	Interface / Protocol with execute(input) → ExecutionResult
ExecutionResult	{ output, status, startedAt, completedAt, error?, metadata? }

Validation

Type	Description
ValidationError	{ field: string, message: string, value?: unknown }
ValidationResult	{ valid: boolean, errors: ValidationError[] }
FieldValidation	{ minLength?, maxLength?, min?, max?, pattern? }
FieldDefinition	{ name, type, label?, description?, required?, defaultValue?, options?, validation? }