Python API

Reference for the ants Python package.

Installation

pip install -e .  # From repo root

Core Imports

# Agent castes
from ants import Scout, Harvester, Relay, Hybrid

# TypeDB client
from ants.knowledge import TypeDBClient

# Hunters (for Hunt BTC)
from ants.actors.hunter import TameHunter, WildHunter

# ONE Ontology
from ants.groups import (
    Actor, AIAgent, Human,
    Group, GroupType, GroupMembership,
    Role, Capability, Constraint,
    ONEPermissionGuard, Action,
)

# Security
from ants.groups.security import SecurityGuard, get_security_guard

TypeDBClient

from ants.knowledge import TypeDBClient

# Create client
client = TypeDBClient()

# Connect (uses env vars)
await client.connect()

# Query
results = await client.query("match $a isa ant; select $a;")

# Insert
await client.insert("""
    insert $a isa ant,
        has id "ant-001",
        has caste "scout";
""")

# Disconnect
await client.disconnect()

Methods

Agent Classes

Scout

from ants import Scout

scout = Scout("scout-001", typedb)
scout.pheromone_sensitivity = 0.3  # Low (explore)

# Run the stigmergic loop
await scout.run(max_iterations=1000)

# Or step manually
perception = await scout.perceive()
decision = await scout.decide(perception)
result = await scout.act(decision)
await scout.evaluate(result)

Harvester

from ants import Harvester

harvester = Harvester("harv-001", typedb)
harvester.pheromone_sensitivity = 0.9  # High (exploit)
await harvester.run()

Relay

from ants import Relay

relay = Relay("relay-001", typedb)
relay.pheromone_sensitivity = 0.5  # Medium
await relay.run()

Hybrid

from ants import Hybrid

hybrid = Hybrid("hybrid-001", typedb)
# Sensitivity adapts based on environment
await hybrid.run()

Agent Properties

Agent Methods

Hunters

TameHunter

from ants.actors.hunter import TameHunter

tame = TameHunter("tame-001", typedb)

# Configure
tame.distinguished_bits = 20  # Rarer points
tame.jump_table = [2**i for i in range(256)]

# Run
await tame.run()

WildHunter

from ants.actors.hunter import WildHunter

wild = WildHunter("wild-001", typedb)
await wild.run()

ONE Ontology

Creating Actors

from ants.groups import AIAgent, Role, Capability, AgentSubtype

agent = AIAgent(
    id="scout-001",
    username="scout-001",
    display_name="Scout Agent",
    agent_subtype=AgentSubtype.SCOUT,
    role=Role.WORKER,
    capabilities=[
        Capability.EXECUTE_SEARCH,
        Capability.MODIFY_PHEROMONES,
    ],
)

# Check capability
if agent.can(Capability.EXECUTE_SEARCH):
    print("Can search")

# Check constraint
if agent.blocked_by(Constraint.CANNOT_DELETE_AUDIT):
    print("Cannot delete audit")

Creating Groups

from ants.groups import Group, GroupType

colony = Group(
    id="ants-at-work-genesis",
    slug="ants-at-work",
    name="Ants at Work Genesis",
    group_type=GroupType.COLONY,
)

mission = Group(
    id="hunt-btc",
    slug="hunt-btc",
    name="Hunt BTC",
    group_type=GroupType.MISSION,
    parent_group_id=colony.id,
)

Permission Checking

from ants.groups import ONEPermissionGuard, Action

guard = ONEPermissionGuard()

result = await guard.check_actor_permission(
    actor=scout,
    action=Action.SPAWN_ANTS,
    target_group=colony,
)

if result.allowed:
    print("Permission granted")
else:
    print(f"Denied: {result.reason}")

Security

SecurityGuard

from ants.groups.security import get_security_guard

guard = await get_security_guard()

# Check if spawn is allowed
allowed, reason = await guard.can_spawn_ants(100)
if not allowed:
    print(f"BLOCKED: {reason}")

# Check current gate
gate = await guard.current_gate()
print(f"Gate {gate.level}: {gate.max_ants} ants allowed")

# Trigger kill switch (emergency)
await guard.emergency_stop("Reason for stop")

Growth Gates

Spawning

from ants.groups import spawn_ants

# Spawn with security checks
result = await spawn_ants(
    caste="scout",
    count=10,
    mission_id="hunt-btc",
)

print(f"Spawned: {result.spawned}")
print(f"Failed: {result.failed}")

Analytics

from ants.knowledge.analytics import ColonyAnalytics

analytics = ColonyAnalytics(typedb)

# Get metrics
metrics = await analytics.get_metrics()
print(f"Total actors: {metrics.total_actors}")
print(f"Total pheromone: {metrics.total_pheromone}")
print(f"Superhighways: {metrics.superhighway_count}")

# Export
await analytics.export_json("metrics.json")

Crypto Utilities

from ants.skills.crypto import (
    secp256k1,
    point_add,
    point_multiply,
    pubkey_to_address,
    is_distinguished,
)

# Point operations
G = secp256k1.G  # Generator point
P = point_multiply(G, 12345)  # 12345 * G

# Address derivation
address = pubkey_to_address(P)

# Distinguished point check
is_dp = is_distinguished(hash(P), bits=20)