Metadata-Version: 2.4
Name: blackboard-core
Version: 1.0.0
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.9
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.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"
Dynamic: license-file

# Blackboard-Core

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

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

## 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

- **Centralized State** - All agents share a typed Pydantic state model
- **LLM Orchestration** - A supervisor LLM decides which worker runs next
- **Async-First** - Built for high-performance async/await patterns
- **Middleware System** - Budget tracking, logging, human approval, auto-summarization
- **Tool Calling** - Native support for OpenAI-style function calling
- **Persistence** - Save/resume sessions with optimistic locking
- **Memory System** - Vector memory with pluggable embeddings
- **Parallel Execution** - Run independent workers concurrently

## Installation

```bash
pip install blackboard-core
```

## Quick Start

```python
import asyncio
from blackboard import Orchestrator, Worker, WorkerOutput, Artifact, Blackboard

# 1. Define your workers
class Writer(Worker):
    name = "Writer"
    description = "Generates text content based on the goal"
    
    async def run(self, state: Blackboard, inputs=None) -> WorkerOutput:
        # Your LLM call here
        content = f"Generated content for: {state.goal}"
        return WorkerOutput(
            artifact=Artifact(type="text", content=content, creator=self.name)
        )

class Critic(Worker):
    name = "Critic"
    description = "Reviews content and provides feedback"
    
    async def run(self, state: Blackboard, inputs=None) -> WorkerOutput:
        artifact = state.get_last_artifact()
        # Your review logic here
        return WorkerOutput(
            feedback=Feedback(
                source=self.name,
                critique="Looks good!",
                passed=True,
                artifact_id=artifact.id
            )
        )

# 2. Create an LLM client (implement the LLMClient protocol)
class MyLLM:
    async def generate(self, prompt: str) -> str:
        # Your LLM API call (OpenAI, Anthropic, etc.)
        return '{"action": "call", "worker": "Writer", "reasoning": "Start writing"}'

# 3. Run the orchestrator
async def main():
    orchestrator = Orchestrator(
        llm=MyLLM(),
        workers=[Writer(), Critic()],
        verbose=True
    )
    
    result = await orchestrator.run(
        goal="Write a haiku about programming",
        max_steps=10
    )
    
    print(f"Final status: {result.status}")
    print(f"Artifacts: {[a.content for a in result.artifacts]}")

asyncio.run(main())
```

## 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 |

## Advanced Features

### Middleware

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

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

### Tool Calling (OpenAI-style)

```python
from blackboard.tools import ToolCallingLLMClient

class MyToolLLM(ToolCallingLLMClient):
    async def generate_with_tools(self, prompt, tools):
        # Use OpenAI function calling
        ...
```

### Memory System

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

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

### Persistence

```python
# Save session
result.save_to_json("session.json")

# Resume later
state = Blackboard.load_from_json("session.json")
await orchestrator.run(state=state)
```

## Documentation

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

## License

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