keeper-beacon

Fleet discovery and registry — agents appear on radar, get tracked and routed.

The lighthouse keeper needs to know where every agent is. Keeper Beacon provides fleet discovery, registration, and proximity tracking.

What It Does

• Discovery — Agents register with the beacon on startup
• Registry — Central directory of active fleet members
• Proximity — Track which agents are near each other (same task, same room)
• Matcher — Route agents to tasks based on capabilities and proximity

The Lighthouse Metaphor

The Cocapn brand IS the architecture. The lighthouse (keeper) monitors agent proximity. Radar rings represent fleet discovery. Each ring is an agent appearing on the radar, being tracked, authenticated, and routed.

Installation

pip install keeper-beacon

Usage

Agent Registry

Register fleet agents, track heartbeats, and monitor status.

from keeper_beacon import AgentRegistry, AgentRecord, AgentStatus

registry = AgentRegistry(stale_threshold=300.0)

# Register an agent
oracle = AgentRecord(
    agent_id="oracle1",
    name="Oracle1",
    capabilities=["reading", "synthesis", "coding"],
    endpoint="keeper:8900",
    trust_score=0.9,
    load=0.3,
)
registry.register(oracle)

# Heartbeat to keep agent active
registry.heartbeat("oracle1")

# List active agents
print(registry.active_agents)  # Only agents with ACTIVE status

# Get fleet stats
print(registry.stats())
# {"total": 1, "by_status": {"active": 1}}

Capability Matching

Find the best agents for a task based on required capabilities, load, and trust.

from keeper_beacon import CapabilityMatcher

matcher = CapabilityMatcher()

# Find all agents that have ALL required capabilities
required = ["python", "rust"]
results = matcher.fully_capable(registry.active_agents, required)

# Get best match with scoring
best = matcher.best_match(registry.active_agents, required)
if best:
    print(f"Agent: {best.agent.name}, Score: {best.score}")
    print(f"Matched capabilities: {best.matched_capabilities}")
    print(f"Missing: {best.missing_capabilities}")

Proximity Scoring

Score agents by capability overlap, latency, and trust for task routing.

from keeper_beacon import ProximityScorer

scorer = ProximityScorer(
    latency_weight=0.3,
    overlap_weight=0.4,
    trust_weight=0.3,
)

# Score and rank agents for a task
ranked = scorer.score_agents(
    registry.active_agents,
    required_capabilities=["python", "vision"],
)
for agent, score in ranked:
    print(f"{agent.name}: {score:.2f}")

Beacon Discovery

Broadcast and receive agent presence signals.

from keeper_beacon import BeaconDiscovery, BeaconSignal

discovery = BeaconDiscovery(ttl=120.0)

# Receive a beacon signal
signal = BeaconSignal(
    agent_id="scout1",
    name="Scout",
    capabilities=["vision", "navigation"],
    endpoint="scout:9100",
    ttl=60.0,
)
discovery.receive(signal)

# Find agents by capability
coders = discovery.discover(capability="navigation")
print(f"Found {len(coders)} agents with navigation")

# Prune expired signals
discovery.prune()

print(f"Active signals: {discovery.active_count}")

Part of the Cocapn Fleet

Powers the Keeper service on port 8900.

Architecture

                    ┌─────────────┐
                    │   Keeper    │
                    │  (port 8900)│
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │     Keeper Beacon      │
              │   (keeper_beacon)       │
              ├─────┬──────┬──────┬─────┤
              │ Disc│Reg   │Prox  │Match│
              │ overy│istry │imity │er   │
              └──┬──┴──┬──┴──┬───┴──┬──┘
                 │     │     │      │
           ┌─────┘  ┌──┘  ┌──┘   ┌──┘
           ▼        ▼     ▼      ▼
        Agent   Agent  Agent   Agent

Changelog

0.2.3 (current)

• Fixed license metadata on PyPI (setuptools 59.x compat)
• Added CONTRIBUTING.md with development setup, code style, and testing guidance
• Added code examples to README (AgentRegistry, CapabilityMatcher, ProximityScorer)
• Added architecture diagram to README

0.2.2

• Improved README with code examples and architecture diagram
• Added CONTRIBUTING.md
• Fixed license format for setuptools compat

0.2.1

• Minor fixes and improvements

0.2.0

• Expanded README with usage examples and architecture docs
• Added CI workflow (test + publish to PyPI)
• Added MIT license and PyPI badges
• Fixed long description rendering on PyPI

0.1.0

• Initial release: fleet discovery, registry, capability matching, proximity scoring
• 14/14 tests passing

License

MIT