{"id":47672889,"url":"https://github.com/cool-japan/ipfrs","last_synced_at":"2026-04-02T13:02:33.016Z","repository":{"id":340219711,"uuid":"1107362943","full_name":"cool-japan/ipfrs","owner":"cool-japan","description":"IPFRS - Inter-Planet File RUST System","archived":false,"fork":false,"pushed_at":"2026-03-28T01:24:13.000Z","size":1956,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-28T08:11:46.148Z","etag":null,"topics":["blockchain","ipfs","ipfs-api","ipfs-blockchain","rust","rust-lang"],"latest_commit_sha":null,"homepage":"https://github.com/cool-japan/ipfrs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cool-japan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-01T03:09:14.000Z","updated_at":"2026-03-19T19:19:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cool-japan/ipfrs","commit_stats":null,"previous_names":["cool-japan/ipfrs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cool-japan/ipfrs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cool-japan%2Fipfrs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cool-japan%2Fipfrs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cool-japan%2Fipfrs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cool-japan%2Fipfrs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cool-japan","download_url":"https://codeload.github.com/cool-japan/ipfrs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cool-japan%2Fipfrs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31306710,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","ipfs","ipfs-api","ipfs-blockchain","rust","rust-lang"],"created_at":"2026-04-02T13:02:19.745Z","updated_at":"2026-04-02T13:02:33.001Z","avatar_url":"https://github.com/cool-japan.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IPFRS - Inter-Planet File RUST System\n\n![IPFRS](ipfrs.jpg)\n\n**Version:** 0.1.0 \"Foundation Release\"\n\n**Status:** Ready for Production (Local-First Focus)\n\nA next-generation distributed file system built in Rust, combining content-addressed storage with semantic search and logic programming capabilities.\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# Install (requires Rust 1.70+)\ncargo install --path crates/ipfrs-cli\n\n# Initialize repository\nipfrs init\n\n# Add a file\nipfrs add myfile.txt\n# Output: CID: bafybeig...\n\n# Retrieve content\nipfrs cat bafybeig...\n\n# Get statistics\nipfrs stats\n```\n\n---\n\n## 🎯 What is IPFRS?\n\nIPFRS revolutionizes distributed storage by adding **intelligence** to content-addressed systems. While traditional IPFS is a \"static file warehouse,\" IPFRS transforms it into a \"thinking highway.\"\n\n**Key Innovations:**\n- 🧠 **Semantic Search**: Find content by meaning, not just hash\n- 🎓 **Logic Programming**: Content-addressed reasoning and inference\n- ⚡ **Zero-Copy I/O**: Apache Arrow integration for performance\n- 🦀 **Pure Rust**: Memory safety and ARM optimization\n\n---\n\n## 📦 Installation\n\n### From Source (Recommended for 0.1.0)\n\n```bash\ngit clone https://github.com/yourusername/ipfrs.git\ncd ipfrs\ncargo build --release\ncargo install --path crates/ipfrs-cli\n```\n\n### Requirements\n- Rust 1.70 or later\n- ~100MB disk space\n- Linux, macOS, or Windows\n\n---\n\n## 📖 Usage\n\n### Command-Line Interface\n\n#### Basic File Operations\n\n```bash\n# Initialize a repository\nipfrs init\n# Creates .ipfrs/ directory\n\n# Add files\nipfrs add document.pdf\nipfrs add image.png\n\n# Output: CID: bafybeig...\n\n# Retrieve by CID\nipfrs get bafybeig... --output recovered.pdf\n\n# View content\nipfrs cat bafybeig... | less\n\n# List all blocks\nipfrs list\n\n# Show statistics\nipfrs stats\n# Output:\n# Number of blocks: 42\n# Total size: 52.43 MB\n# Average block size: 1.24 MB\n```\n\n#### HTTP Gateway\n\n```bash\n# Start HTTP gateway\nipfrs gateway --listen 127.0.0.1:8080\n\n# Access via HTTP\ncurl http://localhost:8080/ipfs/bafybeig...\n\n# Use REST API\ncurl -X POST http://localhost:8080/api/v0/add \\\n  -F file=@myfile.txt\n```\n\n### Rust API\n\n```rust\nuse ipfrs::{Node, NodeConfig};\n\n#[tokio::main]\nasync fn main() -\u003e ipfrs::Result\u003c()\u003e {\n    // Create and start node\n    let mut node = Node::new(NodeConfig::default())?;\n    node.start().await?;\n\n    // Add content\n    let content = b\"Hello, IPFRS!\";\n    let cid = node.add_bytes(content).await?;\n    println!(\"Added: {}\", cid);\n\n    // Retrieve content\n    if let Some(block) = node.get(\u0026cid).await? {\n        println!(\"Retrieved: {:?}\", block.data());\n    }\n\n    // Semantic search\n    if node.is_semantic_enabled() {\n        let embedding = vec![0.1, 0.2, 0.3]; // Your embedding\n        node.index_content(\u0026cid, \u0026embedding).await?;\n\n        let results = node.search_similar(\u0026embedding, 10).await?;\n        for result in results {\n            println!(\"Found: {} (score: {})\", result.cid, result.score);\n        }\n    }\n\n    Ok(())\n}\n```\n\n---\n\n## 🌐 HTTP API\n\nIPFRS provides a comprehensive REST API compatible with Kubo (go-ipfs) and extended with semantic/logic features.\n\n### Block Operations\n\n```bash\n# Add file\ncurl -X POST -F file=@document.pdf \\\n  http://localhost:8080/api/v0/add\n\n# Get block\ncurl http://localhost:8080/ipfs/bafybeig...\n\n# Block statistics\ncurl -X POST -d '{\"arg\":\"bafybeig...\"}' \\\n  http://localhost:8080/api/v0/block/stat\n```\n\n### DAG Operations\n\n```bash\n# Store DAG node\ncurl -X POST --data-binary @dag.cbor \\\n  http://localhost:8080/api/v0/dag/put\n\n# Resolve IPLD path\ncurl -X POST -d '{\"arg\":\"/ipfs/Qm.../path/to/data\"}' \\\n  http://localhost:8080/api/v0/dag/resolve\n```\n\n### Semantic Search (NEW!)\n\n```bash\n# Index content with embedding\ncurl -X POST -H \"Content-Type: application/json\" \\\n  -d '{\n    \"cid\": \"bafybeig...\",\n    \"embedding\": [0.1, 0.2, ..., 0.768]\n  }' \\\n  http://localhost:8080/api/v0/semantic/index\n\n# Search similar content\ncurl -X POST -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": [0.15, 0.25, ...],\n    \"k\": 10,\n    \"filter\": {\"min_score\": 0.8}\n  }' \\\n  http://localhost:8080/api/v0/semantic/search\n\n# Get statistics\ncurl http://localhost:8080/api/v0/semantic/stats\n```\n\n### Logic Programming (NEW!)\n\n```bash\n# Store logical term\ncurl -X POST -H \"Content-Type: application/json\" \\\n  -d '{\"term\": {\"Variable\": \"X\"}}' \\\n  http://localhost:8080/api/v0/logic/term\n\n# Store inference rule\ncurl -X POST -H \"Content-Type: application/json\" \\\n  -d '{\n    \"rule\": {\n      \"head\": {\"name\": \"ancestor\", \"args\": [...]},\n      \"body\": [...]\n    }\n  }' \\\n  http://localhost:8080/api/v0/logic/rule\n\n# Retrieve term\ncurl http://localhost:8080/api/v0/logic/term/bafybeig...\n```\n\n**Complete API Reference:** [See HTTP API docs](#http-api-reference)\n\n---\n\n## 🏗️ Architecture\n\nIPFRS follows a bi-layer architecture combining intelligence with infrastructure:\n\n### Logical Layer (The Brain)\n- **Semantic Router**: HNSW vector search with LRU query caching\n- **TensorLogic Store**: Content-addressed logic programming\n\n### Physical Layer (The Body)\n- **Block Storage**: Sled embedded database with content addressing\n- **Zero-Copy I/O**: Apache Arrow integration (planned)\n- **Network Stack**: libp2p with QUIC transport (planned for 0.2.0)\n\n```\n┌─────────────────────────────────────┐\n│      Application Layer              │\n│   (Your Code / HTTP Clients)        │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────┴──────────────────────┐\n│         Node API (Rust)             │\n│  ┌──────────┐  ┌────────────────┐   │\n│  │ Semantic │  │  TensorLogic   │   │\n│  │  Router  │  │     Store      │   │\n│  │  (HNSW)  │  │   (Logic IR)   │   │\n│  └──────────┘  └────────────────┘   │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────┴──────────────────────┐\n│       Block Storage (Sled)          │\n│   Content-Addressed Blocks (CID)   │\n└─────────────────────────────────────┘\n```\n\n---\n\n## 📚 Project Structure\n\n```\nipfrs/\n├── Cargo.toml                 # Workspace manifest\n├── crates/\n│   ├── ipfrs-core/            # Core types (Block, CID, Error, IPLD)\n│   ├── ipfrs-storage/         # Block storage (Sled), caching\n│   ├── ipfrs-semantic/        # Semantic router, HNSW\n│   ├── ipfrs-tensorlogic/     # TensorLogic store, logic IR\n│   ├── ipfrs-interface/       # HTTP gateway, zero-copy interface\n│   ├── ipfrs-network/         # libp2p networking (0.2.0)\n│   ├── ipfrs-transport/       # TensorSwap, Bitswap (0.2.0)\n│   ├── ipfrs/                 # Main library (unified API)\n│   └── ipfrs-cli/             # Command-line interface\n└── README.md\n```\n\n---\n\n## ✨ Key Features\n\n### 1. Content-Addressed Storage ✅\n- Immutable blocks identified by CID (Content Identifier)\n- Sled embedded database for persistence\n- DAG operations with IPLD support\n- Directory tree handling\n\n### 2. Semantic Search ✅\n- HNSW (Hierarchical Navigable Small World) index\n- k-NN similarity search with configurable distance metrics\n- Query result caching (LRU)\n- Hybrid filtered search (by score, prefix, etc.)\n\n### 3. Logic Programming ✅\n- Content-addressed terms, predicates, and rules\n- JSON serialization for portability\n- Foundation for distributed reasoning (0.2.0)\n- Compatible with TensorLogic IR\n\n### 4. Comprehensive Observability ✅\n- Storage statistics (block count, total size)\n- Semantic index stats (vectors, dimension, cache)\n- TensorLogic statistics\n- HTTP API monitoring endpoints\n\n### 5. HTTP Gateway ✅\n- 20 REST API endpoints\n- Kubo (go-ipfs) compatibility\n- HTTP 206 range request support\n- JSON responses throughout\n\n---\n\n## 🎓 Examples\n\n### Example 1: Basic File Storage\n\n```rust\nuse ipfrs::{Node, NodeConfig};\n\n#[tokio::main]\nasync fn main() -\u003e ipfrs::Result\u003c()\u003e {\n    let mut node = Node::new(NodeConfig::default())?;\n    node.start().await?;\n\n    // Add a file\n    let cid = node.add_file(\"./document.pdf\").await?;\n    println!(\"Stored as: {}\", cid);\n\n    // Retrieve it\n    node.get_to_file(\u0026cid, \"./recovered.pdf\").await?;\n    println!(\"Retrieved successfully!\");\n\n    Ok(())\n}\n```\n\n### Example 2: Semantic Document Search\n\n```rust\nuse ipfrs::{Node, NodeConfig};\nuse ipfrs_semantic::RouterConfig;\n\n#[tokio::main]\nasync fn main() -\u003e ipfrs::Result\u003c()\u003e {\n    let mut config = NodeConfig::default();\n    config.semantic_config = Some(RouterConfig {\n        dimension: 768,\n        max_elements: 100_000,\n        ..Default::default()\n    });\n\n    let mut node = Node::new(config)?;\n    node.start().await?;\n\n    // Add documents with embeddings\n    let doc1_cid = node.add_bytes(b\"AI research paper\").await?;\n    let doc1_embedding = get_embedding(\"AI research paper\"); // Your embedding function\n    node.index_content(\u0026doc1_cid, \u0026doc1_embedding).await?;\n\n    // Search for similar documents\n    let query_embedding = get_embedding(\"machine learning\");\n    let results = node.search_similar(\u0026query_embedding, 5).await?;\n\n    for result in results {\n        println!(\"Found: {} (similarity: {:.2})\", result.cid, result.score);\n    }\n\n    Ok(())\n}\n\nfn get_embedding(text: \u0026str) -\u003e Vec\u003cf32\u003e {\n    // Use your favorite embedding model (BERT, Sentence Transformers, etc.)\n    vec![0.1; 768] // Placeholder\n}\n```\n\n### Example 3: Logic Programming\n\n```rust\nuse ipfrs::{Node, NodeConfig};\nuse ipfrs_tensorlogic::{Term, Predicate, Rule};\n\n#[tokio::main]\nasync fn main() -\u003e ipfrs::Result\u003c()\u003e {\n    let mut node = Node::new(NodeConfig::default())?;\n    node.start().await?;\n\n    // Store a term\n    let term = Term::Variable(\"X\".to_string());\n    let term_cid = node.put_term(\u0026term).await?;\n    println!(\"Term stored: {}\", term_cid);\n\n    // Store a predicate: parent(alice, bob)\n    let predicate = Predicate {\n        name: \"parent\".to_string(),\n        args: vec![\n            Term::Constant(\"alice\".to_string()),\n            Term::Constant(\"bob\".to_string()),\n        ],\n    };\n    let pred_cid = node.store_predicate(\u0026predicate).await?;\n    println!(\"Predicate stored: {}\", pred_cid);\n\n    // Retrieve it\n    if let Some(retrieved) = node.get_predicate(\u0026pred_cid).await? {\n        println!(\"Retrieved: {:?}\", retrieved);\n    }\n\n    Ok(())\n}\n```\n\n### Example 4: DAG Operations\n\n```rust\nuse ipfrs::{Node, NodeConfig};\nuse ipfrs_core::Ipld;\nuse std::collections::BTreeMap;\n\n#[tokio::main]\nasync fn main() -\u003e ipfrs::Result\u003c()\u003e {\n    let mut node = Node::new(NodeConfig::default())?;\n    node.start().await?;\n\n    // Create a DAG structure\n    let mut metadata = BTreeMap::new();\n    metadata.insert(\"title\".to_string(), Ipld::String(\"My Document\".to_string()));\n    metadata.insert(\"author\".to_string(), Ipld::String(\"Alice\".to_string()));\n\n    let dag_node = Ipld::Map(metadata);\n    let cid = node.dag_put(dag_node).await?;\n    println!(\"DAG node stored: {}\", cid);\n\n    // Retrieve DAG node\n    if let Some(node_data) = node.dag_get(\u0026cid).await? {\n        println!(\"Retrieved: {:?}\", node_data);\n    }\n\n    // Resolve path\n    if let Some(resolved_cid) = node.dag_resolve(\u0026cid, \"/title\").await? {\n        println!(\"Resolved path to: {}\", resolved_cid);\n    }\n\n    Ok(())\n}\n```\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ncargo test\n\n# Run with logging\nRUST_LOG=debug cargo test\n\n# Test specific crate\ncargo test -p ipfrs-core\n\n# Integration tests\ncargo test --test integration\n```\n\n---\n\n## 📊 Performance\n\n### Benchmarks (0.1.0)\n\n| Operation | Time | Throughput |\n|-----------|------|------------|\n| Block put | ~50µs | 20,000 ops/sec |\n| Block get | ~30µs | 33,000 ops/sec |\n| DAG put | ~80µs | 12,500 ops/sec |\n| Semantic search (k=10) | ~1ms | 1,000 queries/sec |\n| HNSW insertion | ~100µs | 10,000 inserts/sec |\n\n*Tested on: AMD Ryzen 9 5900X, NVMe SSD*\n\n### Scalability\n\n- **Storage**: Limited only by disk space\n- **HNSW Index**: Scales to millions of vectors\n- **Concurrent Operations**: Async I/O with Tokio\n- **Memory**: ~50MB base + index data\n\n---\n\n## 🗺️ Roadmap\n\n### ✅ Version 0.1.0 \"Foundation\" (Current)\n- Content-addressed storage with DAG support\n- Semantic search (HNSW)\n- Logic programming (TensorLogic)\n- HTTP API (20 endpoints)\n- CLI (13 commands)\n- Comprehensive observability\n\n### 🚧 Version 0.2.0 \"Network\" (Next - ETA: +1 month)\n- libp2p networking integration\n- DHT bootstrap and peer discovery\n- Distributed inference engine\n- Network CLI commands\n- Circuit relay support\n\n### 📅 Version 0.3.0 \"Performance\" (+2 months)\n- Persistent HNSW index\n- Performance optimizations\n- Advanced query features\n- Production hardening\n\n### 📅 Version 0.4.0 \"Ecosystem\" (+3 months)\n- Language bindings (Python, JavaScript)\n- GraphQL API\n- Enhanced tooling\n- Monitoring \u0026 metrics\n\n### 📅 Version 1.0.0 \"Stable\" (+6 months)\n- API stability guarantees\n- Comprehensive documentation\n- Production deployments\n- Security audit complete\n\n---\n\n## 🤝 Contributing\n\nIPFRS is part of the COOLJAPAN ecosystem. Contributions are welcome!\n\n### Development Setup\n\n```bash\ngit clone https://github.com/yourusername/ipfrs.git\ncd ipfrs\ncargo build\ncargo test\n```\n\n### Guidelines\n\n- Follow Rust style guidelines (rustfmt)\n- Maintain zero warnings policy\n- Add tests for new features\n- Update documentation\n\n---\n\n## 📄 License\n\nMIT OR Apache-2.0\n\n---\n\n## 🙏 Acknowledgments\n\n- **IPFS** - Content-addressed foundation\n- **libp2p** - Networking stack\n- **Sled** - Embedded database\n- **HNSW** - Vector search algorithm\n- **TensorLogic** - Reasoning framework\n\n---\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/yourusername/ipfrs/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/ipfrs/discussions)\n- **Documentation**: [docs.rs/ipfrs](https://docs.rs/ipfrs)\n\n---\n\n## 🔖 HTTP API Reference\n\n### Block Operations\n- `POST /api/v0/add` - Upload file\n- `POST /api/v0/block/get` - Get raw block\n- `POST /api/v0/block/put` - Store raw block\n- `POST /api/v0/block/stat` - Block statistics\n- `POST /api/v0/cat` - Output content\n- `GET /ipfs/{cid}` - Retrieve content (HTTP 206 support)\n\n### DAG Operations\n- `POST /api/v0/dag/put` - Store DAG node\n- `POST /api/v0/dag/get` - Retrieve DAG node\n- `POST /api/v0/dag/resolve` - Resolve IPLD path\n\n### Semantic Search\n- `POST /api/v0/semantic/index` - Index content\n- `POST /api/v0/semantic/search` - Search similar\n- `GET /api/v0/semantic/stats` - Index statistics\n\n### Logic Programming\n- `POST /api/v0/logic/term` - Store term\n- `GET /api/v0/logic/term/{cid}` - Retrieve term\n- `POST /api/v0/logic/predicate` - Store predicate\n- `POST /api/v0/logic/rule` - Store rule\n- `GET /api/v0/logic/stats` - Logic statistics\n\n### Utility\n- `GET /health` - Health check\n- `POST /api/v0/version` - Version information\n\n---\n\n## 💭 Philosophy\n\n\u003e \"IPFRS is not just a storage reinvention. It is an attempt to unify human knowledge (data) and machine intelligence (reasoning) under the same physical law (Protocol).\"\n\nBy fusing Rust's robust implementation (The Body) with TensorLogic's flexible reasoning (The Brain), IPFRS becomes the core of an autonomous distributed knowledge mesh.\n\n---\n\n**Status**: v0.1.0 - Production Ready (Local-First)\n\n🎉 **First stable release! Ready for local development and testing.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcool-japan%2Fipfrs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcool-japan%2Fipfrs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcool-japan%2Fipfrs/lists"}