Metadata-Version: 2.4
Name: piazza
Version: 0.2.2
Summary: Agent messaging hub for multi-agent collaboration.
Author-email: Oaklight <oaklight@gmx.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/Oaklight/piazza
Project-URL: Issues, https://github.com/Oaklight/piazza/issues
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff==0.15.20; extra == "dev"
Requires-Dist: ty==0.0.54; extra == "dev"
Requires-Dist: complexipy==5.6.1; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Provides-Extra: irc
Requires-Dist: irc>=20.0; extra == "irc"
Dynamic: license-file

# Piazza

[![CI](https://github.com/Oaklight/piazza/actions/workflows/ci.yml/badge.svg)](https://github.com/Oaklight/piazza/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/piazza?color=%23800020&label=PyPI)](https://pypi.org/project/piazza/)
[![Release](https://img.shields.io/github/v/release/Oaklight/piazza?color=%23800020&label=Release)](https://github.com/Oaklight/piazza/releases/latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

English Version | [中文版](README_zh.md)

A lightweight message bus for multi-agent AI collaboration — the town square (广场) where agents meet.

## Overview

Piazza provides structured, persistent communication channels for AI agents. Instead of point-to-point RPC or shared memory, agents interact through named channels with pub/sub semantics, cursor-based polling, and built-in identity management.

```
Backend (storage)  →  Bus (routing)  →  Client SDK (agent API)
   SQLite / Memory       pub/sub           identity, cursors,
                         channels           DMs, notes, memory
```

## Features

- **Channel-based messaging** — named channels with pub/sub, cursor-tracked polling, and message ordering via monotonic UUIDs
- **Pluggable storage** — `SQLiteBackend` (persistent, WAL mode) and `MemoryBackend` (ephemeral, testing); protocol-based, easy to extend
- **Client SDK** — `PiazzaClient` with agent identity, cursor persistence across sessions, and authentication (register/reconnect/secret hashing)
- **Semantic APIs** — DMs, broadcast channels, notes (with tags), thoughts (chain-of-thought logging), memory (store/recall), notifications
- **Admin panel** — built-in HTTP dashboard with REST API for stats, channel browsing, message inspection, and throughput monitoring; modular `admin/routes/` subpackage with dict-based dispatch
- **Flexible connection** — connect via Bus object, file path (SQLite), or `:memory:` string; URL schemes (`http://`, `redis://`) reserved for future transports
- **Zero runtime dependencies** — pure Python, stdlib only

## Quick Start

```python
from piazza import PiazzaClient

# In-memory bus (for testing)
with PiazzaClient(":memory:", "agent-alpha") as alice:
    alice.channel_send("general", "hello everyone!")
    alice.note_write("remember to check logs", tags=["ops"])
    alice.thought_record("planning", "next steps", "need to coordinate with bob")

# SQLite-backed (persistent)
with PiazzaClient("/tmp/piazza.db", "agent-alpha") as alice:
    alice.dm_send("agent-beta", "ready to sync?")

# Multi-agent collaboration
from piazza import Bus, MemoryBackend

bus = Bus(backend=MemoryBackend())

alice = PiazzaClient(bus, "agent-alice")
bob = PiazzaClient(bus, "agent-bob")

alice.dm_send("agent-bob", "PR is ready for review")
messages = bob.dm_read("agent-alice")  # ["PR is ready for review"]

alice.close()
bob.close()
bus.close()
```

## Architecture

Piazza follows a layered architecture inspired by messaging middleware, adapted for AI agent workflows:

| Layer | Component | Role |
|-------|-----------|------|
| **Storage** | `Backend` protocol | Persistent or ephemeral message storage (`SQLiteBackend`, `MemoryBackend`) |
| **Routing** | `Bus` | Channel management, pub/sub dispatch, UUID generation |
| **Transport** | `Transport` protocol | Abstraction for local vs. remote bus access (`LocalTransport`) |
| **Agent API** | `PiazzaClient` | Identity, cursors, auth, semantic messaging APIs |
| **Frontend** | `Frontend` protocol | 🔄 Network-facing servers (REST + SSE) binding to Bus (`HttpFrontend`, `PiazzaServer`) |
| **Admin** | `AdminServer` | HTTP dashboard + REST API for monitoring |

For detailed design rationale, see [DESIGN_EN.md](docs/DESIGN_EN.md).

## Installation

Requires **Python >= 3.10**.

```bash
pip install piazza
```

Or from source:

```bash
git clone https://github.com/Oaklight/piazza.git
cd piazza
pip install -e ".[dev]"
```

## Client SDK API

### Core Operations

| Method | Description |
|--------|-------------|
| `channel_send(channel, content)` | Send message to a channel |
| `channel_read(channel)` | Read messages (no cursor advance) |
| `channel_poll(channel)` | Poll new messages (advances cursor) |
| `channel_list()` | List all channels |

### Semantic APIs

| Method | Description |
|--------|-------------|
| `dm_send(target, content)` | Send direct message |
| `dm_read(peer)` | Read DM conversation |
| `note_write(content, tags=)` | Write a note with optional tags |
| `note_read(tags=)` | Read notes, optionally filtered by tags |
| `thought_record(mode, focus, content)` | Record chain-of-thought |
| `thought_read()` | Read thought history |
| `memory_store(content)` | Store a memory |
| `memory_recall(query)` | Recall memories by keyword |
| `broadcast_list()` / `broadcast_read(topic)` | Browse broadcast channels |
| `notification_check()` | Poll notifications |

### Authentication

```python
# Register new agent (returns client + secret)
client, secret = PiazzaClient.register(bus, "agent-id")

# Reconnect with secret
client = PiazzaClient(bus, "agent-id", secret=saved_secret)
```

### Admin Panel

```python
from piazza import SQLiteBus

bus = SQLiteBus("piazza.db")
info = bus.start_admin(port=8741)
print(f"Dashboard: {info.url}")
# Visit http://localhost:8741 for the web UI
```

## Roadmap

- [ ] **RemoteTransport** — 🔄 In Progress (`dev/agent-bus`): `HttpFrontend`, `PiazzaServer`, `HttpTransport` implemented; pending merge
- [ ] **IRC Frontend** — planned additional Frontend implementation
- [ ] **Message TTL** — automatic expiry and cleanup
- [ ] **Semantic memory recall** — vector embedding search
- [ ] **Channel ACL** — per-channel access control
- [ ] **Redis/AMQP backends** — distributed storage
- [ ] **Async API** — native async/await support
- [ ] **Federation** — cross-instance communication ([#4](https://github.com/Oaklight/piazza/issues/4))

## Academic Context

Piazza is the reference implementation for Chapter 9 of a dissertation on enabling agentic AI at scale through decoupled abstractions. The design emphasizes protocol-based interfaces, pluggable components, and a clear separation between transport, storage, and agent-level semantics.

## License

MIT — see [LICENSE](LICENSE) for details.
