Metadata-Version: 2.4
Name: py-ipfs-lite
Version: 0.1.0
Summary: Embeddable lightweight IPFS peer for Python (bootstrap phase)
Author: py-ipfs-lite contributors
License: Apache-2.0 OR MIT
Project-URL: Homepage, https://github.com/IPFS-Meshkit/py-ipfs-lite
Project-URL: Repository, https://github.com/IPFS-Meshkit/py-ipfs-lite
Keywords: ipfs,libp2p,bitswap,unixfs,ipld
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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: Programming Language :: Python :: 3.13
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.137.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: hypercorn>=0.18.0
Requires-Dist: libp2p>=0.7.0
Requires-Dist: prometheus-client>=0.25.0
Requires-Dist: python-multipart>=0.0.32
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mdformat>=0.7.22; extra == "dev"
Requires-Dist: mdformat-gfm; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=5.0.0; extra == "test"
Requires-Dist: pytest-trio>=0.8.0; extra == "test"
Requires-Dist: pytest-xdist>=3.5.0; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"

# py-ipfs-lite

**py-ipfs-lite** is a lightweight, embeddable Python IPFS peer built on top of `py-libp2p`.
It provides the core features of IPFS (Blockstore, Bitswap, DHT, IPNI, IPNS, and IPLD DAGs) without the overhead of a heavy Kubo daemon.

It is designed to be highly interoperable with standard IPFS implementations like Kubo and go-ipfs-lite, natively supporting `dag-cbor`, CARv1 file import/export, Bitswap streaming, and more.

## Features

- **Embedded IPFS Node:** Run a complete IPFS node purely in Python using `trio` or standard async.
- **Bitswap Protocol:** Interoperate and exchange blocks directly with Kubo daemons.
- **KadDHT & IPNI Routing:** Local block lookups with lightning-fast routing via the KadDHT network and Delegated HTTP IPNI (`cid.contact`).
- **IPLD DAG Support:** Fully supports `dag-pb`, `dag-cbor`, and `dag-json` for building decentralized knowledge graphs, versioned datasets, and agent memory chains.
- **Offline Data Bundles (CAR):** Export and import full or partial DAGs as Content Addressable aRchives (`.car`).
- **IPNS Mutable Pointers:** Publish and resolve cryptographically signed mutable pointers (IPNS).
- **FastAPI HTTP Daemon:** A drop-in, Kubo-compatible HTTP API exposing `/api/v0` endpoints for adding files, fetching DAGs, and pinning.
- **Prometheus Metrics:** Integrated observability for garbage collection, block sizes, and Bitswap traffic.

## Installation

py-ipfs-lite uses `uv` for dependency management.

```bash
# Clone the repository
git clone https://github.com/IPFS-Meshkit/py-ipfs-lite.git
cd py-ipfs-lite

# Install dependencies using uv
uv sync
```

## Quickstart

### 1. The Python SDK (Embedded Peer)

You can run an IPFS peer directly inside your Python application using `trio`:

```python
import trio
from py_ipfs_lite.peer import Peer
from py_ipfs_lite.config import Config

async def main():
    # Start an ephemeral in-memory peer
    peer = Peer(Config(blockstore_type="memory"), listen_addrs=["/ip4/127.0.0.1/tcp/0"])
    await peer.start()

    # Add a file
    cid = await peer.add_file("/path/to/my/file.txt")
    print(f"Added file with CID: {cid}")

    # Build an IPLD DAG
    node_cid = await peer.add_node({"title": "Hello World", "author": "py-ipfs-lite"}, codec="dag-cbor")
    print(f"Added DAG node with CID: {node_cid}")

    # Publish to IPNS
    ipns_name = await peer.publish_name(f"/ipfs/{node_cid}")
    print(f"Published to IPNS: {ipns_name}")

    await peer.close()

if __name__ == "__main__":
    trio.run(main)
```

### 2. The CLI Daemon & HTTP API

You can spin up `py-ipfs-lite` as a standalone daemon that provides a Kubo-compatible HTTP API.

```bash
# Run the daemon on port 4001, exposing the HTTP API on port 5001
uv run py-ipfs-lite daemon --api --api-port 5001
```

Then you can use the standard HTTP API to interact with it:

```bash
# Add a file
curl -X POST -F file=@test.txt http://127.0.0.1:5001/api/v0/add

# Fetch an IPLD node
curl -X POST "http://127.0.0.1:5001/api/v0/dag/get?arg=bafy..."
```

## What's Next

| I want to…                                                      | Go to…                                                                         |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Understand how `py-ipfs-lite` is structured internally          | [docs/architecture.md](docs/architecture.md)                                   |
| Build verifiable AI agent memory / RAG pipelines                | [docs/guides/ai-agents-and-rag.md](docs/guides/ai-agents-and-rag.md)           |
| Export a DAG as a CAR file for Filecoin storage                 | [docs/guides/car-files-and-filecoin.md](docs/guides/car-files-and-filecoin.md) |
| Use IPNS mutable pointers and understand the trust model        | [docs/guides/ipns.md](docs/guides/ipns.md)                                     |
| Interoperate with a live Kubo daemon over Bitswap               | [docs/guides/interop-with-kubo.md](docs/guides/interop-with-kubo.md)           |
| See the full list of all 21 examples with one-line descriptions | [docs/reference/examples-index.md](docs/reference/examples-index.md)           |
| Browse all documentation                                        | [docs/index.md](docs/index.md)                                                 |

## License

MIT License
