Metadata-Version: 2.4
Name: blackboard-core
Version: 1.8.1
Summary: A Python SDK implementing the Blackboard Pattern for LLM-powered multi-agent systems
Author: Hemant Singh
License: MIT License
        
        Copyright (c) 2025 Hemant Singh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/hemantsingh443/blackboard-core
Project-URL: Documentation, https://github.com/hemantsingh443/blackboard-core#readme
Project-URL: Repository, https://github.com/hemantsingh443/blackboard-core
Keywords: agents,multi-agent,blackboard,orchestration,llm,ai
Classifier: Development Status :: 5 - Production/Stable
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
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: litellm>=1.40.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: jinja2>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: chroma
Requires-Dist: chromadb>=0.4.0; extra == "chroma"
Provides-Extra: hybrid
Requires-Dist: rank-bm25>=0.2.2; extra == "hybrid"
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.19.0; extra == "sqlite"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Provides-Extra: tui
Requires-Dist: rich>=13.0.0; extra == "tui"
Provides-Extra: textual-tui
Requires-Dist: textual>=0.90.0; extra == "textual-tui"
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0.0; extra == "mcp"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "telemetry"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.14.0; extra == "llamaindex"
Provides-Extra: all
Requires-Dist: redis>=5.0.0; extra == "all"
Requires-Dist: chromadb>=0.4.0; extra == "all"
Requires-Dist: rank-bm25>=0.2.2; extra == "all"
Requires-Dist: aiosqlite>=0.19.0; extra == "all"
Requires-Dist: asyncpg>=0.29.0; extra == "all"
Requires-Dist: rich>=13.0.0; extra == "all"
Requires-Dist: textual>=0.90.0; extra == "all"
Requires-Dist: mcp[cli]>=1.0.0; extra == "all"
Requires-Dist: networkx>=3.0.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "all"
Requires-Dist: langchain-core>=0.3.0; extra == "all"
Requires-Dist: llama-index-core>=0.14.0; extra == "all"
Requires-Dist: fastapi>=0.104.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "all"
Requires-Dist: sse-starlette>=1.8.0; extra == "all"
Requires-Dist: playwright>=1.40.0; extra == "all"
Requires-Dist: httpx>=0.25.0; extra == "all"
Requires-Dist: streamlit>=1.28.0; extra == "all"
Provides-Extra: serve
Requires-Dist: fastapi>=0.104.0; extra == "serve"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "serve"
Requires-Dist: sse-starlette>=1.8.0; extra == "serve"
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == "browser"
Provides-Extra: stdlib
Requires-Dist: httpx>=0.25.0; extra == "stdlib"
Provides-Extra: graph
Requires-Dist: networkx>=3.0.0; extra == "graph"
Provides-Extra: ui
Requires-Dist: streamlit>=1.28.0; extra == "ui"
Requires-Dist: httpx>=0.25.0; extra == "ui"
Dynamic: license-file

# Blackboard-Core

A Python SDK for building **LLM-powered multi-agent systems** using the Blackboard Pattern.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/blackboard-core.svg)](https://pypi.org/project/blackboard-core/)

![Blackboard TUI Demo](public/demo.gif)`

## What is Blackboard-Core?

Blackboard-Core provides a **centralized state architecture** for multi-agent AI systems. Instead of agents messaging each other directly, all agents read from and write to a shared **Blackboard** (state), while a **Supervisor LLM** orchestrates which agent runs next.

```
┌─────────────────────────────────────────────────────────────┐
│                       ORCHESTRATOR                          │
│  ┌─────────────┐    ┌──────────────────────────────────┐    │
│  │  Supervisor │──▶│          BLACKBOARD              │    │
│  │    (LLM)    │    │  • Goal      • Artifacts         │    │
│  └─────────────┘    │  • Status    • Feedback          │    │
│         │           │  • History   • Metadata          │    │
│         ▼           └──────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                       WORKERS                       │    │
│  │  [Writer]  [Critic]  [Refiner]  [Researcher]  ...   │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

## Features

**Core**

- **Centralized State** - All agents share a typed Pydantic state model
- **LLM Orchestration** - A supervisor LLM decides which worker runs next
- **Magic Decorators** - Define workers with simple typed functions
- **Async-First** - Built for high-performance async/await patterns

**Orchestration**

- **Chain-of-Thought** - Pluggable reasoning strategies
- **Fractal Agents** - Nest agents as workers with recursion limits
- **Squad Patterns** - Pre-configured agent factories
- **Blueprints** - Constrain execution to specific workflows

**Persistence & Memory**

- **SQLite/Postgres** - Production-grade persistence
- **Time-Travel Debugging** - Fork sessions at any checkpoint
- **Vector Memory** - Semantic search with pluggable embedders

**Swarm Intelligence (v1.8.0)**

- **Delta Protocol** - Incremental artifact patching with search-replace
- **Map-Reduce** - Parallel sub-agent execution with conflict resolution
- **Branch-Merge** - Fork states, work in isolation, merge results

**Developer Experience**

- **Interactive TUI** - Textual-based Mission Control dashboard
- **CLI Tools** - Project scaffolding and optimization
- **Session Replay** - Record and replay for debugging

**Production**

- **Runtime Security** - Explicit acknowledgment for code execution
- **Cost Control** - Budget middleware with LiteLLM pricing
- **OpenTelemetry** - Distributed tracing

**Ecosystem**

- **LiteLLM Integration** - 100+ LLM providers
- **LangChain Adapter** - Wrap LangChain tools as Workers
- **LlamaIndex Adapter** - Wrap QueryEngines as Workers
- **FastAPI Dependencies** - Easy API integration
- **Model Context Protocol** - Connect to MCP servers

## Installation

```bash
pip install blackboard-core

# Optional extras
pip install blackboard-core[mcp]        # Model Context Protocol
pip install blackboard-core[telemetry]  # OpenTelemetry
pip install blackboard-core[chroma]     # ChromaDB for memory
pip install blackboard-core[serve]      # FastAPI server
pip install blackboard-core[all]        # Everything
```

## Quick Start

```python
from blackboard import Orchestrator, worker


class SimpleLLM:
    def __init__(self):
        self.calls = 0

    def generate(self, prompt: str) -> str:
        self.calls += 1
        if self.calls == 1:
            return '{"action": "call", "worker": "Write", "inputs": {"topic": "AI safety"}, "reasoning": "Draft the article"}'
        return '{"action": "done", "reasoning": "Article complete"}'

@worker
def write(topic: str) -> str:
    """Writes content about a topic."""
    return f"Article about {topic}"

orchestrator = Orchestrator(llm=SimpleLLM(), workers=[write])
result = orchestrator.run_sync(goal="Write about AI safety")
print(result.artifacts[-1].content)
```

Swap `SimpleLLM` for your real provider in production, for example `LiteLLMClient(model="gpt-4o")`.

## Core Concepts

| Concept          | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| **Blackboard**   | Shared state containing goal, artifacts, feedback, and metadata |
| **Worker**       | An agent that reads state and produces artifacts or feedback    |
| **Orchestrator** | Manages the control loop and calls the supervisor LLM           |
| **Supervisor**   | The LLM that decides which worker to call next                  |
| **Artifact**     | Versioned output produced by a worker                           |
| **Feedback**     | Review/critique of an artifact                                  |

## The Magic Decorator

Define workers with just type hints - no boilerplate:

```python
from blackboard import worker
from blackboard.state import Blackboard

# Simple function - schema auto-generated
@worker
def calculate(a: int, b: int, operation: str = "add") -> str:
    """Performs math operations."""
    if operation == "add":
        return str(a + b)
    return str(a - b)

# With state access
@worker
def summarize(state: Blackboard) -> str:
    """Summarizes current progress."""
    return f"Goal: {state.goal}, Artifacts: {len(state.artifacts)}"

# Async support
@worker
async def research(topic: str) -> str:
    """Researches a topic online."""
    # ... async HTTP calls
    return f"Research on {topic}"
```

## Chain-of-Thought Reasoning

Enable smarter decision-making with CoT:

```python
from blackboard import Orchestrator, BlackboardConfig
from blackboard.reasoning import ChainOfThoughtStrategy

# Enable Chain-of-Thought via config
config = BlackboardConfig(reasoning_strategy="cot")
orchestrator = Orchestrator(llm=llm, workers=workers, config=config)

# Or use the strategy directly
from blackboard.reasoning import ChainOfThoughtStrategy

strategy = ChainOfThoughtStrategy()
# The LLM will now output <thinking>...</thinking> before deciding
```

## State Persistence

Persist after every step and on terminal exit:

```python
from blackboard import Blackboard
from blackboard.persistence import SQLitePersistence

persistence = SQLitePersistence("./blackboard.db")
await persistence.initialize()
orchestrator.set_persistence(persistence)

state = Blackboard(goal="Write about AI safety")
state.metadata["session_id"] = "session-123"

# Saves the latest state on every step and again on DONE / FAILED / PAUSED
result = await orchestrator.run(state=state, max_steps=10)

# Resume later
restored = await persistence.load("session-123")
```

If you also set `auto_save_path`, the same final state is written to JSON alongside your persistence backend. Checkpoint-capable backends also snapshot terminal states automatically.

## Advanced Features

### Middleware

```python
from blackboard.middleware import BudgetMiddleware, HumanApprovalMiddleware

orchestrator = Orchestrator(
    llm=my_llm,
    workers=[...],
    middleware=[
        BudgetMiddleware(max_tokens=100000, max_cost_usd=5.0),
        HumanApprovalMiddleware(require_approval_for=["Deployer"])
    ]
)
```

### Memory System

```python
from blackboard.memory import SimpleVectorMemory, MemoryWorker
from blackboard.embeddings import OpenAIEmbedder

memory = SimpleVectorMemory(embedder=OpenAIEmbedder())
worker = MemoryWorker(memory=memory)
```

### Model Context Protocol

```python
from blackboard.mcp import MCPServerWorker

# Local via stdio
fs_server = await MCPServerWorker.create(
    name="Filesystem",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-fs", "/tmp"]
)

# Remote via SSE
remote = await MCPServerWorker.create(
    name="RemoteAPI",
    url="http://mcp-server:8080/sse"
)

# Each MCP tool becomes a worker
workers = fs_server.expand_to_workers()
```

### Blueprints (Workflow Patterns)

```python
from blackboard.flow import SequentialPipeline

pipeline = SequentialPipeline([research, draft])

# The final phase auto-completes the run after the last successful worker call
result = await orchestrator.run(goal="Research and draft", blueprint=pipeline)
```

Set `allow_skip_to_done=False` on a custom `Blueprint` when you want to forbid early `done` decisions until every phase is complete.

## Behavior Guarantees

- Blueprint steps advance after one successful worker call or one successful `call_independent` batch unless you define a custom `exit_condition`.
- When `allow_skip_to_done=False`, early `done` decisions are rejected and the supervisor is re-asked once with a correction.
- With `auto_save_path` and/or `set_persistence(...)`, Blackboard persists after each non-terminal step and again on terminal `done`, `failed`, or `paused` exit paths.
- `state.metadata["last_usage"]` is the canonical per-call usage record with `input_tokens`, `output_tokens`, `model`, and `context`. Auto-summarization contributes to budget tracking too.
- Tool calling only exposes workers allowed in the current blueprint phase, and JSON fallback preserves the same blueprint restrictions.

## Configuration

Use environment variables or direct config:

```bash
export BLACKBOARD_MAX_STEPS=50
export BLACKBOARD_REASONING_STRATEGY=cot
export BLACKBOARD_VERBOSE=true
```

```python
from blackboard import BlackboardConfig

config = BlackboardConfig.from_env()
# Or direct:
config = BlackboardConfig(
    max_steps=50,
    reasoning_strategy="cot",
    enable_parallel=True
)
```

## Documentation

See [DOCS.md](DOCS.md) for the complete API reference and advanced usage guide.

## License

MIT License - see [LICENSE](LICENSE) for details.
