Metadata-Version: 2.4
Name: ipfs_kit_py
Version: 0.3.0
Summary: Python toolkit for IPFS with high-level API, cluster management, tiered storage, and AI/ML integration
Home-page: https://github.com/endomorphosis/ipfs_kit_py/
Author: Benjamin Barber
Author-email: Benjamin Barber <starworks5@gmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/endomorphosis/ipfs_kit_py/
Project-URL: Documentation, https://github.com/endomorphosis/ipfs_kit_py/blob/main/README.md
Project-URL: Source, https://github.com/endomorphosis/ipfs_kit_py/
Project-URL: Issues, https://github.com/endomorphosis/ipfs_kit_py/issues
Project-URL: Changelog, https://github.com/endomorphosis/ipfs_kit_py/blob/main/CHANGELOG.md
Keywords: ipfs,distributed,storage,content-addressed,cluster,arrow,fsspec,ai,ml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: base58>=2.1.1
Requires-Dist: multiaddr>=0.0.9
Requires-Dist: importlib-metadata>=4.12.0; python_version < "3.10"
Requires-Dist: python-magic>=0.4.27
Requires-Dist: anyio>=3.7.0
Requires-Dist: trio>=0.22.0
Requires-Dist: cryptography>=38.0.0
Provides-Extra: transformers
Requires-Dist: transformers>=4.20.0; extra == "transformers"
Requires-Dist: huggingface-hub>=0.10.0; extra == "transformers"
Provides-Extra: fsspec
Requires-Dist: fsspec>=2023.3.0; extra == "fsspec"
Requires-Dist: requests-unixsocket>=0.3.0; extra == "fsspec"
Provides-Extra: arrow
Requires-Dist: pyarrow>=11.0.0; extra == "arrow"
Requires-Dist: pandas>=1.3.0; extra == "arrow"
Provides-Extra: libp2p
Requires-Dist: libp2p>=0.1.5; extra == "libp2p"
Requires-Dist: multiaddr>=0.0.9; extra == "libp2p"
Requires-Dist: multiformats>=0.2.0; extra == "libp2p"
Requires-Dist: base58>=2.1.1; extra == "libp2p"
Requires-Dist: cryptography>=38.0.0; extra == "libp2p"
Requires-Dist: google-protobuf>=4.21.0; extra == "libp2p"
Requires-Dist: eth-hash>=0.3.3; extra == "libp2p"
Requires-Dist: eth-keys>=0.4.0; extra == "libp2p"
Provides-Extra: ai-ml
Requires-Dist: torch>=2.0.0; extra == "ai-ml"
Requires-Dist: numpy>=1.20.0; extra == "ai-ml"
Requires-Dist: scikit-learn>=1.0.0; extra == "ai-ml"
Requires-Dist: mmh3>=0.7.1; extra == "ai-ml"
Provides-Extra: huggingface
Requires-Dist: huggingface_hub>=0.19.0; extra == "huggingface"
Provides-Extra: ipld
Requires-Dist: py-ipld-car>=0.1.0; extra == "ipld"
Requires-Dist: py-ipld-dag-pb>=0.1.0; extra == "ipld"
Requires-Dist: py-ipld-unixfs>=0.1.0; extra == "ipld"
Provides-Extra: api
Requires-Dist: fastapi>=0.100.0; extra == "api"
Requires-Dist: uvicorn>=0.22.0; extra == "api"
Requires-Dist: python-multipart>=0.0.6; extra == "api"
Provides-Extra: webrtc
Requires-Dist: aiortc>=1.5.0; extra == "webrtc"
Requires-Dist: av>=10.0.0; extra == "webrtc"
Requires-Dist: opencv-python>=4.7.0.72; extra == "webrtc"
Requires-Dist: websockets>=10.4; extra == "webrtc"
Provides-Extra: graphql
Requires-Dist: graphene>=3.4.0; extra == "graphql"
Provides-Extra: s3
Requires-Dist: boto3>=1.26.0; extra == "s3"
Provides-Extra: performance
Requires-Dist: matplotlib>=3.5.0; extra == "performance"
Requires-Dist: numpy>=1.20.0; extra == "performance"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.3.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.3.0; extra == "dev"
Requires-Dist: pylint>=2.17.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.2; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Provides-Extra: full
Requires-Dist: fsspec>=2023.3.0; extra == "full"
Requires-Dist: requests-unixsocket>=0.3.0; extra == "full"
Requires-Dist: pyarrow>=11.0.0; extra == "full"
Requires-Dist: pandas>=1.3.0; extra == "full"
Requires-Dist: multiformats>=0.2.0; extra == "full"
Requires-Dist: multiaddr>=0.0.9; extra == "full"
Requires-Dist: aiohttp>=3.8.4; extra == "full"
Requires-Dist: pyyaml>=6.0; extra == "full"
Requires-Dist: numpy>=1.20.0; extra == "full"
Requires-Dist: scikit-learn>=1.0.0; extra == "full"
Requires-Dist: fastapi>=0.100.0; extra == "full"
Requires-Dist: uvicorn>=0.22.0; extra == "full"
Requires-Dist: python-multipart>=0.0.6; extra == "full"
Requires-Dist: graphene>=3.4.0; extra == "full"
Requires-Dist: faiss-cpu>=1.7.4; extra == "full"
Requires-Dist: networkx>=3.0; extra == "full"
Requires-Dist: matplotlib>=3.5.0; extra == "full"
Requires-Dist: boto3>=1.26.0; extra == "full"
Requires-Dist: huggingface_hub>=0.19.0; extra == "full"
Requires-Dist: aiortc>=1.5.0; extra == "full"
Requires-Dist: av>=10.0.0; extra == "full"
Requires-Dist: opencv-python>=4.7.0.72; extra == "full"
Requires-Dist: websockets>=10.4; extra == "full"
Requires-Dist: py-ipld-car>=0.1.0; extra == "full"
Requires-Dist: py-ipld-dag-pb>=0.1.0; extra == "full"
Requires-Dist: py-ipld-unixfs>=0.1.0; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# IPFS Kit Python - Production Ready MCP Server

[![Production Ready](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)](https://github.com/your-repo/ipfs_kit_py)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-blue)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue)](https://www.docker.com/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-orange)](https://modelcontextprotocol.io/)
[![Files Organized](https://img.shields.io/badge/Files-88%25%20Reduced-green)](./FINAL_PRODUCTION_STATUS.md)

**IPFS Kit** is a comprehensive, production-ready Python toolkit for working with IPFS (InterPlanetary File System) technologies. It provides a unified Model Context Protocol (MCP) server for IPFS operations, cluster management, tiered storage, and AI/ML integration.

> 🎉 **Now Production Ready!** This project has been transformed from 700+ cluttered files to a clean, organized structure with comprehensive documentation. See [FINAL_PRODUCTION_STATUS.md](./FINAL_PRODUCTION_STATUS.md) for complete details.

## 🚀 Quick Start

### Production MCP Server

Start the production MCP server in seconds:

```bash
# Direct execution
python3 final_mcp_server_enhanced.py --host 0.0.0.0 --port 9998

# Docker deployment
docker-compose up -d

# Development mode with debug logging
python3 final_mcp_server_enhanced.py --debug
```

### Installation

```bash
# Development installation
git clone https://github.com/your-repo/ipfs_kit_py.git
cd ipfs_kit_py
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Package installation (when published)
pip install ipfs_kit_py[full]
```

## 🌟 Key Features

### Production MCP Server
- **FastAPI-based REST API** with comprehensive IPFS operations
- **JSON-RPC 2.0 protocol** support for Model Context Protocol compatibility
- **Mock IPFS implementation** for reliable testing and development
- **Health monitoring** with `/health` endpoint and metrics
- **Comprehensive logging** with structured output and debug modes
- **Docker deployment** with optimized containers and compose configuration

### IPFS Operations
- **Content Management**: Add, retrieve, pin, and list IPFS content
- **Mock Storage**: Realistic IPFS behavior for testing without requiring IPFS daemon
- **CID Generation**: Proper content addressing with SHA-256 based CIDs
- **Error Handling**: Robust error handling with detailed error messages

### Developer Experience
- **Command-line Interface**: Easy-to-use CLI with configurable options
- **Auto-generated Documentation**: Interactive API docs at `/docs` endpoint
- **Validation Tools**: Built-in server validation and testing utilities
- **Hot Reload**: Development mode with automatic code reloading

## 📋 API Endpoints

The MCP server provides the following endpoints:

### Health & Status
- `GET /health` - Health check and server status
- `GET /metrics` - Server metrics and statistics
- `GET /docs` - Interactive API documentation

### JSON-RPC Interface
- `POST /jsonrpc` - MCP protocol endpoint for tool execution

### IPFS Operations (via JSON-RPC)
- `ipfs_add` - Add content to IPFS storage
- `ipfs_cat` - Retrieve content by CID
- `ipfs_pin_add` - Pin content for persistence
- `ipfs_pin_ls` - List pinned content
- `ipfs_refs` - List references and links

## 🐳 Docker Deployment

### Using Docker Compose (Recommended)
```bash
# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down
```

### Manual Docker Build
```bash
# Build the image
docker build -t ipfs-kit-mcp .

# Run the container
docker run -p 9998:9998 ipfs-kit-mcp
```

## 🔧 Configuration

### Environment Variables
- `IPFS_KIT_HOST` - Server host (default: 127.0.0.1)
- `IPFS_KIT_PORT` - Server port (default: 9998)
- `IPFS_KIT_DEBUG` - Enable debug mode (default: false)
- `PYTHONUNBUFFERED` - Ensure unbuffered output for Docker

### Command Line Options
```bash
python3 final_mcp_server_enhanced.py --help
```

Options:
- `--host HOST` - Host to bind to (default: 127.0.0.1)
- `--port PORT` - Port to bind to (default: 9998)
- `--debug` - Enable debug mode with detailed logging

## Examples

For practical examples of using IPFS Kit, see the [examples directory](../examples/README.md), which includes:

- Basic usage examples
- FSSpec integration examples
- Cluster management examples
- Performance profiling examples
- Filesystem journal examples
- Journal monitoring and visualization examples
- AI/ML integration examples
- AI/ML visualization examples
- Data science workflow examples
- High-level API usage examples
- Tiered cache performance examples
- Probabilistic data structures examples
- Practical integration examples

## Contributing to Documentation

We welcome contributions to improve the documentation! If you find errors, have suggestions, or want to add examples, please submit a pull request or open an issue.

When contributing to documentation:

1. Follow the existing style and formatting
2. Provide practical examples where appropriate
3. Explain concepts clearly with diagrams when appropriate
4. Link related documentation
5. Test examples before submitting

## Getting Help

If you need help with IPFS Kit:

- Check the [README.md](../README.md) for quick start guides
- Search the documentation for specific topics
- Look at the examples in the [examples directory](../examples/)
- Open an issue on GitHub if you find a bug or have a feature request
