Core Primitives

Everything in Minions is built from three primitives:

Minion

A Minion is a structured object instance — the fundamental unit of the system. Every minion has a type, a title, and a set of validated fields.

{
  "id": "abc-123",
  "title": "Research Assistant",
  "minionTypeId": "builtin-agent",
  "fields": {
    "role": "researcher",
    "model": "gpt-4"
  },
  "status": "active",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

Type Definition

TypeScript

interface Minion {
  id: string;
  title: string;
  minionTypeId: string;
  fields: Record<string, unknown>;
  status?: MinionStatus;
  createdAt: string;
  updatedAt: string;
}

Python

@dataclass
class Minion:
    id: str
    title: str
    minion_type_id: str
    fields: dict[str, Any]
    status: MinionStatus | None = "active"
    created_at: str = ""
    updated_at: str = ""

Required Fields

Field	Description
id	UUID v4 identifier
title	Human-readable name
minionTypeId	Reference to the type
fields	Dynamic field values
createdAt	Creation timestamp
updatedAt	Last update timestamp

Optional Fields

Status (active, todo, in_progress, completed, cancelled), priority (low, medium, high, urgent), description, tags, dueDate, and more.

MinionType

A MinionType defines the schema for a kind of minion. It specifies what fields are available, their types, and validation rules.

TypeScript

const agentType = {
  id: 'builtin-agent',
  name: 'Agent',
  slug: 'agent',
  schema: [
    { name: 'role', type: 'string', label: 'Role' },
    { name: 'model', type: 'string', label: 'Model' },
    { name: 'tools', type: 'tags', label: 'Tools' },
  ],
};

Python

from minions.schemas import agent_type

# agent_type.id       == "builtin-agent"
# agent_type.slug     == "agent"
# agent_type.schema   == [FieldDefinition(...), ...]

Built-in types include: note, link, file, contact, agent, team, thought, prompt-template, test-case, task.

Relation

A Relation is a typed, directional link between two minions. Relations create structure — hierarchies, dependencies, sequences.

TypeScript

graph.add({
  sourceId: 'agent-001',
  targetId: 'skill-001',
  type: 'parent_of',
});

Python

graph.add({
    "source_id": "agent-001",
    "target_id": "skill-001",
    "type": "parent_of",
})

Supported types: parent_of, depends_on, implements, relates_to, inspired_by, triggers, references, blocks, alternative_to, part_of, follows, integration_link.