sbp-client 0.1.0__tar.gz

sbp_client-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build outputs
+build/
+*.pyc
+*.pyo
+*.so
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Environment
+.env
+.env.local
+*.local
+
+# Logs
+*.log
+npm-debug.log*
+
+# Test coverage
+coverage/
+htmlcov/
+.coverage
+
+# Package locks (keep package-lock.json for npm)
+# poetry.lock

sbp_client-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: sbp-client
+Version: 0.1.0
+Summary: Stigmergic Blackboard Protocol - Python Client SDK
+Project-URL: Homepage, https://github.com/sbp-protocol/sbp
+Project-URL: Documentation, https://sbp.dev
+Project-URL: Repository, https://github.com/sbp-protocol/sbp
+Author: SBP Contributors
+License: MIT
+Keywords: blackboard,coordination,multi-agent,sbp,stigmergy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: pydantic>=2.5.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SBP Python Client
+
+Python SDK for the Stigmergic Blackboard Protocol.
+
+## Installation
+
+```bash
+pip install sbp-client
+```
+
+## Quick Start
+
+```python
+from sbp import SbpClient, ThresholdCondition
+
+# Connect to the blackboard
+with SbpClient("http://localhost:3000") as client:
+    # Emit a pheromone
+    client.emit(
+        trail="market.signals",
+        type="volatility",
+        intensity=0.8,
+        payload={"symbol": "BTC-USD", "vix": 45.2},
+    )
+
+    # Sniff the environment
+    result = client.sniff(trails=["market.signals"])
+    for p in result.pheromones:
+        print(f"{p.trail}/{p.type}: {p.current_intensity:.2f}")
+```
+
+## Local Mode (No Server Required)
+
+You can run SBP entirely in-memory within a single process. This is useful for testing, simulations, or simple multi-agent scripts where you don't want to manage a separate server process.
+
+```python
+from sbp import SbpClient, SbpAgent
+
+# Client in local mode
+with SbpClient(local=True) as client:
+    client.emit("local.test", "signal", 0.9)
+
+# Agent in local mode
+# Note: In a single process, all local=True instances share the same blackboard state.
+agent = SbpAgent("my-agent", local=True)
+
+@agent.when("local.test", "signal", value=0.5)
+async def handle(trigger):
+    print("Received signal locally!")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from sbp import AsyncSbpClient, ThresholdCondition
+
+async def main():
+    async with AsyncSbpClient() as client:
+        # Emit
+        await client.emit("signals", "event", 0.7)
+
+        # Register a scent (trigger condition)
+        await client.register_scent(
+            "my-scent",
+            condition=ThresholdCondition(
+                trail="signals",
+                signal_type="event",
+                aggregation="max",
+                operator=">=",
+                value=0.5,
+            ),
+        )
+
+        # Subscribe to triggers via WebSocket
+        async def on_trigger(trigger):
+            print(f"Triggered! {trigger.scent_id}")
+
+        await client.subscribe("my-scent", on_trigger)
+
+asyncio.run(main())
+```
+
+## Declarative Agent Framework
+
+```python
+from sbp import SbpAgent, TriggerPayload, run_agent
+
+agent = SbpAgent("my-agent", "http://localhost:3000")
+
+@agent.when("tasks", "new_task", operator=">=", value=0.5)
+async def handle_task(trigger: TriggerPayload):
+    print(f"Got task: {trigger.context_pheromones}")
+    await agent.emit("tasks", "completed", 1.0)
+
+run_agent(agent)
+```
+
+## API Reference
+
+### SbpClient / AsyncSbpClient
+
+| Method | Description |
+|--------|-------------|
+| `emit(trail, type, intensity, ...)` | Deposit a pheromone |
+| `sniff(trails, types, ...)` | Read environment state |
+| `register_scent(scent_id, condition, ...)` | Register a trigger |
+| `deregister_scent(scent_id)` | Remove a trigger |
+| `subscribe(scent_id, handler)` | Listen for triggers (async only) |
+| `inspect(include)` | Get blackboard metadata |
+| `evaporate(...)` | Force cleanup |
+
+### Condition Types
+
+```python
+# Simple threshold
+ThresholdCondition(
+    trail="market.signals",
+    signal_type="volatility",
+    aggregation="max",  # sum, max, avg, count, any
+    operator=">=",      # >=, >, <=, <, ==, !=
+    value=0.7,
+)
+
+# Composite (AND/OR/NOT)
+CompositeCondition(
+    operator="and",
+    conditions=[condition1, condition2],
+)
+
+# Rate-based
+RateCondition(
+    trail="events",
+    signal_type="click",
+    metric="emissions_per_second",
+    window_ms=10000,
+    operator=">=",
+    value=5.0,
+)
+```
+
+### Decay Models
+
+```python
+from sbp.types import exponential_decay, linear_decay, immortal
+
+# Exponential (default) - half-life in milliseconds
+decay = exponential_decay(half_life_ms=300000)  # 5 minutes
+
+# Linear - rate per millisecond
+decay = linear_decay(rate_per_ms=0.0001)
+
+# Immortal - never decays
+decay = immortal()
+```
+
+## License
+
+MIT

sbp_client-0.1.0/README.md

@@ -0,0 +1,159 @@
+# SBP Python Client
+
+Python SDK for the Stigmergic Blackboard Protocol.
+
+## Installation
+
+```bash
+pip install sbp-client
+```
+
+## Quick Start
+
+```python
+from sbp import SbpClient, ThresholdCondition
+
+# Connect to the blackboard
+with SbpClient("http://localhost:3000") as client:
+    # Emit a pheromone
+    client.emit(
+        trail="market.signals",
+        type="volatility",
+        intensity=0.8,
+        payload={"symbol": "BTC-USD", "vix": 45.2},
+    )
+
+    # Sniff the environment
+    result = client.sniff(trails=["market.signals"])
+    for p in result.pheromones:
+        print(f"{p.trail}/{p.type}: {p.current_intensity:.2f}")
+```
+
+## Local Mode (No Server Required)
+
+You can run SBP entirely in-memory within a single process. This is useful for testing, simulations, or simple multi-agent scripts where you don't want to manage a separate server process.
+
+```python
+from sbp import SbpClient, SbpAgent
+
+# Client in local mode
+with SbpClient(local=True) as client:
+    client.emit("local.test", "signal", 0.9)
+
+# Agent in local mode
+# Note: In a single process, all local=True instances share the same blackboard state.
+agent = SbpAgent("my-agent", local=True)
+
+@agent.when("local.test", "signal", value=0.5)
+async def handle(trigger):
+    print("Received signal locally!")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from sbp import AsyncSbpClient, ThresholdCondition
+
+async def main():
+    async with AsyncSbpClient() as client:
+        # Emit
+        await client.emit("signals", "event", 0.7)
+
+        # Register a scent (trigger condition)
+        await client.register_scent(
+            "my-scent",
+            condition=ThresholdCondition(
+                trail="signals",
+                signal_type="event",
+                aggregation="max",
+                operator=">=",
+                value=0.5,
+            ),
+        )
+
+        # Subscribe to triggers via WebSocket
+        async def on_trigger(trigger):
+            print(f"Triggered! {trigger.scent_id}")
+
+        await client.subscribe("my-scent", on_trigger)
+
+asyncio.run(main())
+```
+
+## Declarative Agent Framework
+
+```python
+from sbp import SbpAgent, TriggerPayload, run_agent
+
+agent = SbpAgent("my-agent", "http://localhost:3000")
+
+@agent.when("tasks", "new_task", operator=">=", value=0.5)
+async def handle_task(trigger: TriggerPayload):
+    print(f"Got task: {trigger.context_pheromones}")
+    await agent.emit("tasks", "completed", 1.0)
+
+run_agent(agent)
+```
+
+## API Reference
+
+### SbpClient / AsyncSbpClient
+
+| Method | Description |
+|--------|-------------|
+| `emit(trail, type, intensity, ...)` | Deposit a pheromone |
+| `sniff(trails, types, ...)` | Read environment state |
+| `register_scent(scent_id, condition, ...)` | Register a trigger |
+| `deregister_scent(scent_id)` | Remove a trigger |
+| `subscribe(scent_id, handler)` | Listen for triggers (async only) |
+| `inspect(include)` | Get blackboard metadata |
+| `evaporate(...)` | Force cleanup |
+
+### Condition Types
+
+```python
+# Simple threshold
+ThresholdCondition(
+    trail="market.signals",
+    signal_type="volatility",
+    aggregation="max",  # sum, max, avg, count, any
+    operator=">=",      # >=, >, <=, <, ==, !=
+    value=0.7,
+)
+
+# Composite (AND/OR/NOT)
+CompositeCondition(
+    operator="and",
+    conditions=[condition1, condition2],
+)
+
+# Rate-based
+RateCondition(
+    trail="events",
+    signal_type="click",
+    metric="emissions_per_second",
+    window_ms=10000,
+    operator=">=",
+    value=5.0,
+)
+```
+
+### Decay Models
+
+```python
+from sbp.types import exponential_decay, linear_decay, immortal
+
+# Exponential (default) - half-life in milliseconds
+decay = exponential_decay(half_life_ms=300000)  # 5 minutes
+
+# Linear - rate per millisecond
+decay = linear_decay(rate_per_ms=0.0001)
+
+# Immortal - never decays
+decay = immortal()
+```
+
+## License
+
+MIT

sbp_client-0.1.0/examples/market_crisis.py

@@ -0,0 +1,202 @@
+"""
+SBP Example: Market Volatility Crisis Detection
+
+This example demonstrates multi-agent coordination using SBP.
+Three agents work together without direct communication:
+
+1. Market Analyzer - Emits volatility signals based on market data
+2. Order Monitor - Emits signals about large orders
+3. Crisis Handler - Wakes up when volatility AND large orders exceed thresholds
+
+Run:
+    # Terminal 1: Start the SBP server
+    cd packages/server && npm run dev
+
+    # Terminal 2: Run this example
+    cd packages/client-python && python -m examples.market_crisis
+"""
+
+import asyncio
+import random
+from sbp import (
+    AsyncSbpClient,
+    ThresholdCondition,
+    CompositeCondition,
+    TriggerPayload,
+    exponential_decay,
+)
+
+
+async def market_analyzer(client: AsyncSbpClient) -> None:
+    """Simulates a market analyzer that emits volatility signals"""
+    print("[Market Analyzer] Starting...")
+
+    while True:
+        # Simulate market volatility (random for demo)
+        volatility = random.uniform(0.2, 0.95)
+
+        await client.emit(
+            trail="market.signals",
+            type="volatility",
+            intensity=volatility,
+            decay=exponential_decay(half_life_ms=30000),  # 30 second half-life
+            payload={
+                "symbol": "BTC-USD",
+                "vix_equivalent": volatility * 100,
+                "timestamp": asyncio.get_event_loop().time(),
+            },
+            tags=["crypto", "realtime"],
+        )
+
+        print(f"[Market Analyzer] Emitted volatility: {volatility:.2f}")
+        await asyncio.sleep(2)
+
+
+async def order_monitor(client: AsyncSbpClient) -> None:
+    """Simulates an order monitor that emits large order signals"""
+    print("[Order Monitor] Starting...")
+
+    while True:
+        # Simulate detecting large orders (random for demo)
+        if random.random() > 0.5:
+            size = random.randint(500000, 5000000)
+            side = random.choice(["buy", "sell"])
+
+            await client.emit(
+                trail="market.orders",
+                type="large_order",
+                intensity=min(1.0, size / 5000000),  # Normalize by max size
+                decay=exponential_decay(half_life_ms=60000),  # 1 minute half-life
+                payload={
+                    "symbol": "BTC-USD",
+                    "size_usd": size,
+                    "side": side,
+                },
+                tags=["crypto", "whale"],
+            )
+
+            print(f"[Order Monitor] Detected {side} order: ${size:,}")
+
+        await asyncio.sleep(3)
+
+
+async def crisis_handler(client: AsyncSbpClient) -> None:
+    """Agent that triggers when crisis conditions are met"""
+    print("[Crisis Handler] Registering scent...")
+
+    # Define the crisis condition:
+    # High volatility AND multiple large orders
+    condition = CompositeCondition(
+        operator="and",
+        conditions=[
+            ThresholdCondition(
+                trail="market.signals",
+                signal_type="volatility",
+                aggregation="max",
+                operator=">=",
+                value=0.7,  # 70% volatility threshold
+            ),
+            ThresholdCondition(
+                trail="market.orders",
+                signal_type="large_order",
+                aggregation="count",
+                operator=">=",
+                value=2,  # At least 2 large orders
+            ),
+        ],
+    )
+
+    # Register the scent
+    await client.register_scent(
+        scent_id="crisis-detector",
+        condition=condition,
+        cooldown_ms=10000,  # 10 second cooldown between triggers
+        activation_payload={"severity": "high"},
+        context_trails=["market.signals", "market.orders"],
+    )
+
+    # Subscribe to triggers
+    async def on_crisis(trigger: TriggerPayload) -> None:
+        print("\n" + "=" * 60)
+        print("🚨 CRISIS DETECTED!")
+        print(f"   Triggered at: {trigger.triggered_at}")
+        print(f"   Context pheromones: {len(trigger.context_pheromones)}")
+
+        for p in trigger.context_pheromones:
+            print(f"   - {p.trail}/{p.type}: {p.current_intensity:.2f}")
+            print(f"     Payload: {p.payload}")
+
+        # Crisis handler could emit its own response
+        await client.emit(
+            trail="system.alerts",
+            type="crisis_response",
+            intensity=1.0,
+            payload={
+                "action": "reduce_exposure",
+                "triggered_by": trigger.scent_id,
+            },
+        )
+        print("   ✓ Emitted crisis response signal")
+        print("=" * 60 + "\n")
+
+    await client.subscribe("crisis-detector", on_crisis)
+    print("[Crisis Handler] Listening for crisis conditions...")
+
+    # Keep running
+    while True:
+        await asyncio.sleep(1)
+
+
+async def environment_monitor(client: AsyncSbpClient) -> None:
+    """Periodically displays environment state"""
+    while True:
+        await asyncio.sleep(5)
+
+        result = await client.sniff(
+            trails=["market.signals", "market.orders", "system.alerts"],
+            min_intensity=0.1,
+        )
+
+        print("\n--- Environment State ---")
+        for key, agg in result.aggregates.items():
+            print(f"  {key}: count={agg.count}, max={agg.max_intensity:.2f}")
+        print("-------------------------\n")
+
+
+async def main() -> None:
+    """Run all agents concurrently"""
+    print("=" * 60)
+    print("SBP Market Crisis Detection Demo")
+    print("=" * 60)
+    print()
+
+    # Create clients for each agent
+    analyzer_client = AsyncSbpClient(agent_id="market-analyzer")
+    order_client = AsyncSbpClient(agent_id="order-monitor")
+    crisis_client = AsyncSbpClient(agent_id="crisis-handler")
+    monitor_client = AsyncSbpClient(agent_id="env-monitor")
+
+    await analyzer_client.connect()
+    await order_client.connect()
+    await crisis_client.connect()
+    await monitor_client.connect()
+
+    try:
+        # Run all agents concurrently
+        await asyncio.gather(
+            market_analyzer(analyzer_client),
+            order_monitor(order_client),
+            crisis_handler(crisis_client),
+            environment_monitor(monitor_client),
+        )
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    finally:
+        await analyzer_client.close()
+        await order_client.close()
+        await crisis_client.close()
+        await monitor_client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sbp_client-0.1.0/examples/simple_agent.py

@@ -0,0 +1,112 @@
+"""
+SBP Example: Simple Agent using the Declarative Framework
+
+This example shows how to build an agent using the @agent.when decorator.
+
+Run:
+    # Terminal 1: Start the SBP server
+    cd packages/server && npm run dev
+
+    # Terminal 2: Run this agent
+    cd packages/client-python && python -m examples.simple_agent
+
+    # Terminal 3: Emit test signals
+    curl -X POST http://localhost:3000/emit \
+      -H "Content-Type: application/json" \
+      -d '{"trail": "tasks", "type": "new_task", "intensity": 0.8, "payload": {"name": "Process data"}}'
+"""
+
+import asyncio
+from sbp import SbpAgent, TriggerPayload, ThresholdCondition, run_agent
+
+
+# Create the agent
+agent = SbpAgent("task-worker", "http://localhost:3000")
+
+
+# Simple threshold trigger using @when decorator
+@agent.when("tasks", "new_task", operator=">=", value=0.5, cooldown_ms=5000)
+async def handle_new_task(trigger: TriggerPayload) -> None:
+    """Handle new task signals"""
+    print(f"\n📋 New task received!")
+
+    for p in trigger.context_pheromones:
+        task_name = p.payload.get("name", "Unknown")
+        print(f"   Task: {task_name}")
+        print(f"   Intensity: {p.current_intensity:.2f}")
+
+    # Emit a "processing" signal
+    await agent.emit(
+        "tasks",
+        "processing",
+        intensity=0.7,
+        payload={"worker": agent.agent_id},
+    )
+    print("   ✓ Emitted processing signal")
+
+    # Simulate work
+    await asyncio.sleep(2)
+
+    # Emit completion signal
+    await agent.emit(
+        "tasks",
+        "completed",
+        intensity=1.0,
+        payload={
+            "worker": agent.agent_id,
+            "original_task": trigger.context_pheromones[0].payload if trigger.context_pheromones else {},
+        },
+    )
+    print("   ✓ Task completed!")
+
+
+# More complex condition using @on_scent decorator
+@agent.on_scent(
+    "high-load-detector",
+    condition=ThresholdCondition(
+        trail="tasks",
+        signal_type="new_task",
+        aggregation="count",
+        operator=">=",
+        value=5,
+    ),
+    cooldown_ms=30000,  # Only trigger once per 30 seconds
+    context_trails=["tasks"],
+)
+async def handle_high_load(trigger: TriggerPayload) -> None:
+    """Triggered when task queue is getting backed up"""
+    pending_count = len([
+        p for p in trigger.context_pheromones
+        if p.type == "new_task"
+    ])
+
+    print(f"\n⚠️  High load detected! {pending_count} tasks pending")
+
+    # Emit alert
+    await agent.emit(
+        "system.alerts",
+        "high_load",
+        intensity=0.9,
+        payload={
+            "pending_tasks": pending_count,
+            "worker": agent.agent_id,
+        },
+    )
+
+
+if __name__ == "__main__":
+    print("=" * 50)
+    print("SBP Task Worker Agent")
+    print("=" * 50)
+    print()
+    print("Listening for task signals...")
+    print("Send a task with:")
+    print()
+    print('  curl -X POST http://localhost:3000/emit \\')
+    print('    -H "Content-Type: application/json" \\')
+    print("    -d '{\"trail\": \"tasks\", \"type\": \"new_task\", \"intensity\": 0.8}'")
+    print()
+    print("Press Ctrl+C to stop")
+    print()
+
+    run_agent(agent)