Metadata-Version: 2.4
Name: foundation-protocol
Version: 0.1.0
Summary: Foundation Protocol (FP) reference Python runtime
Project-URL: Homepage, https://github.com/FoundationAgents/foundation-protocol
Project-URL: Documentation, https://foundationagents.github.io/foundation-protocol/
Project-URL: Issues, https://github.com/FoundationAgents/foundation-protocol/issues
Project-URL: Repository, https://github.com/FoundationAgents/foundation-protocol
Author: FP Contributors
License: MIT
License-File: LICENSE
Keywords: agent,fp,governance,protocol,runtime
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 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: cryptography>=45.0.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pydantic>=2.11.0
Provides-Extra: dev
Requires-Dist: jsonschema>=4.20; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Description-Content-Type: text/markdown

# Foundation Protocol

English | [中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [Español](README.es.md) | [Tiếng Việt](README.vi.md)

[![GitHub Stars](https://img.shields.io/github/stars/FoundationAgents/foundation-protocol)](https://github.com/FoundationAgents/foundation-protocol) [![License](https://img.shields.io/github/license/FoundationAgents/foundation-protocol)](LICENSE) [![Docs](https://img.shields.io/badge/docs-online-5b3fb6?logo=materialformkdocs&logoColor=white)](https://foundationagents.github.io/foundation-protocol/) [![arXiv](https://img.shields.io/badge/arXiv-2605.23218-b31b1b?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2605.23218) [![HuggingFace](https://img.shields.io/badge/🤗-Paper-yellow)](https://huggingface.co/papers/2605.23218)

A Python runtime for multi-entity AI collaboration — agents, humans, and tools on a shared protocol layer.

> [AI-Link-Net](https://github.com/FoundationAgents/ai-link-net) is a full-stack application built on this protocol.

## Features

- **Unified entity model** — agents, humans, tools, and services share a common identity and addressing system
- **Multi-party sessions** — structured collaboration with strict lifecycle enforcement and event replay
- **Policy & governance** — checkpoint hooks with provenance recording for trust and access control
- **Trade & payment** — contracts, escrow, settlement, and dispute resolution via state machines
- **Federation** — local and remote entity routing across distributed host nodes

## Manifesto

https://github.com/user-attachments/assets/ceab2515-b8f2-47ec-8d7f-10452759c32a

## Installation

Recommended: install the stable release from PyPI:

```bash
pip install foundation-protocol
```

Developers can install the latest source from GitHub:

```bash
pip install "foundation-protocol @ git+https://github.com/FoundationAgents/foundation-protocol.git"
```

## Usage

```python
import asyncio
from fp import EntityKind, Host, Message, MessageKind

async def main():
    host = Host(name="LocalHost")

    alice = host.register_entity(name="Alice", kind=EntityKind.HUMAN)
    bot = host.register_entity(name="Bot", kind=EntityKind.AGENT)

    await alice.send_message(
        to=bot.entity_card,
        message=Message(kind=MessageKind.INVOKE, payload={"text": "Hello!"}),
    )

asyncio.run(main())
```

See the [`example/`](example/) directory for more scenarios including cross-host messaging, MCP tool integration, and trade workflows.

## Documentation

Full documentation is published at [foundationagents.github.io/foundation-protocol](https://foundationagents.github.io/foundation-protocol/). Quick links:

- [Quickstart](docs/develop/quickstart.md) — install and run a two-entity exchange
- [Checkpoint Pipeline](docs/learn/checkpoint.md) — the trust and governance seam
- [Trade & Trust](docs/trade-and-trust/index.md) — contracts, arbitration, reputation
- [Security Notes](docs/security/index.md) — known boundaries and risks

## License

MIT
