Metadata-Version: 2.4
Name: keeper-beacon
Version: 0.2.3
Summary: Keeper Beacon — fleet discovery and registry for Cocapn agents, with health tracking, capability matching, and proximity scoring
License: MIT
Project-URL: Homepage, https://github.com/SuperInstance/keeper-beacon
Keywords: beacon,discovery,registry,fleet,cocapn
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# keeper-beacon

[![PyPI](https://img.shields.io/pypi/v/keeper-beacon)](https://pypi.org/project/keeper-beacon/) [![Python](https://img.shields.io/pypi/pyversions/keeper-beacon)](https://pypi.org/project/keeper-beacon/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)


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

```bash
pip install keeper-beacon
```

## Usage

### Agent Registry
Register fleet agents, track heartbeats, and monitor status.

```python
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.

```python
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.

```python
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.

```python
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
