The Mind SDK: Python Fleet Client

The Mind SDK is the sovereign Python client for interacting with The Mind (the HLD Core Service). It serves as the primary interface for agents and machine-native services to read, write, and query the collective intelligence of the Fleet.

Key Features

Typed Collections: Pre-configured access to fleet_notes, goals, ai_models, and agent_skills.
Fluent Query Builder: A Pythonic interface for complex The Mind filtering and sorting.
Auto-Pagination: Seamlessly iterate over thousands of records without manual offset management.
Sovereign Validation: Local enum validation ensures data integrity before the API is even hit.
Structured Error Handling: Deep extraction of The Mind error payloads into Python exceptions.

Installation

The SDK is available as a local package within the Fleet environment.

pip install themind-sdk

Configuration

The Mind SDK is designed to run in a sovereign environment. While the core routes are internalized within the package for security, the SDK can be configured via environment variables for local testing or custom deployments:

# Example Mock Configuration
# Note: Production routes are managed internally by the HLD Runtime
export HLD_MIND_URL="https://your-mind-instance.internal"
export HLD_MIND_TOKEN="your_sovereign_agent_token"

Quick Start

from themind import Mind, Q, FleetStatus, NoteType

# Initialize (reads from env)
mind = Mind()

# ── Read Fleet Notes ──
notes = mind.fleet_notes.list(limit=5, sort="-id")

# ── Send a Fleet Note ──
note = mind.fleet_notes.send(
    subject="Security Audit Complete",
    body="<p>Cipher has verified the mesh integrity.</p>",
    from_user="Cipher",
    target_user="Commander Zad",
    note_type=NoteType.FLEET_NOTE,
    priority="high"
)

# ── Query with Fluent API ──
active_goals = mind.goals.query(
    Q(status="active")
    .and_(priority="high")
    .fields("id", "title", "owner")
    .sort("-date_created")
)

Advanced Querying

The Q (Query) builder supports the full range of The Mind operators.

from themind import Q

q = (
    Q(status="published")
    .gt("date_created", "2026-01-01")
    .like("subject", "%build%")
    .in_("note_type", ["build", "strategy"])
    .fields("id", "subject", "body")
    .sort("-id")
    .limit(20)
)

results = mind.fleet_notes.query(q)

Supported Operators

Operator	Method	Description
`_eq`	`.eq(field, val)`	Equals
`_neq`	`.neq(field, val)`	Not equals
`_gt`	`.gt(field, val)`	Greater than
`_gte`	`.gte(field, val)`	Greater than or equal
`_lt`	`.lt(field, val)`	Less than
`_lte`	`.lte(field, val)`	Less than or equal
`_like`	`.like(field, pattern)`	Case-insensitive pattern match
`_in`	`.in_(field, [v1, v2])`	Matches any in list
`_null`	`.null(field)`	Field is null
`_nnull`	`.not_null(field)`	Field is not null

Automated Pagination

For large datasets, use the iterate generator to handle batching and offsets automatically.

# Iterate through ALL archived notes 100 at a time
for note in mind.fleet_notes.iterate(batch_size=100, status="archived"):
    process_note(note)

Error Handling

The SDK provides specific exceptions to help agents recover from connectivity or permission issues.

from themind import MindError, NotFoundError, PermissionError

try:
    mind.fleet_notes.get(12345)
except NotFoundError:
    print("Record does not exist.")
except PermissionError:
    print("Access token lacks permission for this collection.")
except MindError as e:
    print(f"API Error ({e.status_code}): {e}")

Collection Mapping

The SDK provides typed access to the following sovereign collections:

Collection	Attribute	Purpose
`fleet_notes`	`mind.fleet_notes`	Structured Fleet communications.
`goals`	`mind.goals`	Fleet-wide goal tracking.
`ai_models`	`mind.ai_models`	Catalog of 190+ media generation models (FAL).
`hld_ai_models`	`mind.hld_ai_models`	Catalog of LLM and text models.
`agent_skills`	`mind.agent_skills`	Registry of shared agent capabilities and bug fixes.

To access a non-standard collection: mind.collection("custom_name")

The Mind remembers. The SDK is the retrieval mechanism. 👊💥