synapse-filecoin-sdk 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

pynapse/_version.py

@@ -1 +1 @@
-__version__ = "0.1.1"
+__version__ = "0.2.0"

pynapse/integrations/__init__.py

@@ -0,0 +1,4 @@
+"""Pynapse integrations with third-party libraries."""
+
+# LangChain integration is optional - import directly from langchain module
+# from pynapse.integrations.langchain import FilecoinDocumentLoader, FilecoinStorageTool

pynapse/integrations/langchain.py

@@ -0,0 +1,214 @@
+"""
+LangChain integration for pynapse.
+
+This module provides LangChain-compatible components for storing and loading
+documents on Filecoin via the Synapse SDK.
+
+Installation:
+    pip install synapse-filecoin-sdk[langchain]
+
+Usage:
+    from pynapse.integrations.langchain import FilecoinDocumentLoader, FilecoinStorageTool
+    
+    # Load documents from Filecoin
+    loader = FilecoinDocumentLoader(
+        rpc_url="https://api.node.glif.io/rpc/v1",
+        chain="mainnet",
+        private_key=PRIVATE_KEY
+    )
+    docs = await loader.aload(piece_cid="baga6ea4seaq...")
+    
+    # Store documents on Filecoin (as a LangChain tool for agents)
+    tool = FilecoinStorageTool(
+        rpc_url="https://api.node.glif.io/rpc/v1",
+        chain="mainnet",
+        private_key=PRIVATE_KEY
+    )
+    result = await tool._arun(content="Hello, Filecoin!")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional, Type
+
+try:
+    from langchain_core.documents import Document
+    from langchain_core.document_loaders import BaseLoader
+    from langchain_core.tools import BaseTool
+    from pydantic import BaseModel, Field
+except ImportError as e:
+    raise ImportError(
+        "LangChain dependencies not installed. "
+        "Install with: pip install synapse-filecoin-sdk[langchain]"
+    ) from e
+
+from pynapse import AsyncSynapse
+
+
+class FilecoinDocumentLoader(BaseLoader):
+    """Load documents from Filecoin using pynapse.
+    
+    This loader retrieves data stored on Filecoin by Piece CID and converts
+    it into LangChain Document objects.
+    
+    Example:
+        loader = FilecoinDocumentLoader(
+            rpc_url="https://api.node.glif.io/rpc/v1",
+            chain="mainnet",
+            private_key="0x..."
+        )
+        docs = await loader.aload(piece_cid="baga6ea4seaq...")
+    """
+    
+    def __init__(
+        self,
+        rpc_url: str,
+        chain: str = "mainnet",
+        private_key: Optional[str] = None,
+    ):
+        """Initialize the Filecoin document loader.
+        
+        Args:
+            rpc_url: RPC URL for Filecoin node
+            chain: Network name ("mainnet" or "calibration")
+            private_key: Wallet private key (optional for read-only operations)
+        """
+        self.rpc_url = rpc_url
+        self.chain = chain
+        self.private_key = private_key
+        self._synapse: Optional[AsyncSynapse] = None
+    
+    async def _get_synapse(self) -> AsyncSynapse:
+        """Get or create AsyncSynapse instance."""
+        if self._synapse is None:
+            self._synapse = await AsyncSynapse.create(
+                rpc_url=self.rpc_url,
+                chain=self.chain,
+                private_key=self.private_key,
+            )
+        return self._synapse
+    
+    def load(self) -> List[Document]:
+        """Synchronous load - not supported, use aload instead."""
+        raise NotImplementedError(
+            "FilecoinDocumentLoader is async-only. Use aload() instead."
+        )
+    
+    async def aload(self, piece_cid: str) -> List[Document]:
+        """Load a document from Filecoin by Piece CID.
+        
+        Args:
+            piece_cid: The Piece CID of the stored data
+            
+        Returns:
+            List containing a single Document with the retrieved content
+        """
+        synapse = await self._get_synapse()
+        ctx = await synapse.storage.get_context()
+        
+        # Download the data
+        data = await ctx.download(piece_cid)
+        
+        # Try to decode as text, fall back to repr for binary
+        try:
+            content = data.decode("utf-8")
+        except UnicodeDecodeError:
+            content = repr(data)
+        
+        return [
+            Document(
+                page_content=content,
+                metadata={
+                    "source": f"filecoin://{piece_cid}",
+                    "piece_cid": piece_cid,
+                    "chain": self.chain,
+                    "size": len(data),
+                }
+            )
+        ]
+
+
+class FilecoinStorageInput(BaseModel):
+    """Input schema for FilecoinStorageTool."""
+    content: str = Field(description="The text content to store on Filecoin")
+
+
+class FilecoinStorageTool(BaseTool):
+    """LangChain tool for storing data on Filecoin.
+    
+    This tool allows LangChain agents to store arbitrary text content on
+    Filecoin and returns the Piece CID for later retrieval.
+    
+    Example:
+        tool = FilecoinStorageTool(
+            rpc_url="https://api.node.glif.io/rpc/v1",
+            chain="mainnet",
+            private_key="0x..."
+        )
+        # Use in an agent or call directly
+        result = await tool._arun(content="Store this on Filecoin!")
+    """
+    
+    name: str = "filecoin_storage"
+    description: str = (
+        "Store text content on Filecoin decentralized storage. "
+        "Returns the Piece CID which can be used to retrieve the content later. "
+        "Use this when you need to permanently store data on decentralized storage."
+    )
+    args_schema: Type[BaseModel] = FilecoinStorageInput
+    
+    rpc_url: str
+    chain: str = "mainnet"
+    private_key: str
+    _synapse: Optional[AsyncSynapse] = None
+    
+    class Config:
+        arbitrary_types_allowed = True
+    
+    async def _get_synapse(self) -> AsyncSynapse:
+        """Get or create AsyncSynapse instance."""
+        if self._synapse is None:
+            self._synapse = await AsyncSynapse.create(
+                rpc_url=self.rpc_url,
+                chain=self.chain,
+                private_key=self.private_key,
+            )
+        return self._synapse
+    
+    def _run(self, content: str) -> str:
+        """Synchronous run - wraps async implementation."""
+        return asyncio.run(self._arun(content=content))
+    
+    async def _arun(self, content: str) -> str:
+        """Store content on Filecoin and return the Piece CID.
+        
+        Args:
+            content: Text content to store
+            
+        Returns:
+            JSON string with piece_cid, size, and tx_hash
+        """
+        synapse = await self._get_synapse()
+        ctx = await synapse.storage.get_context()
+        
+        # Encode content and ensure minimum size (256 bytes)
+        data = content.encode("utf-8")
+        if len(data) < 256:
+            data = data + b'\x00' * (256 - len(data))
+        
+        # Upload to Filecoin
+        result = await ctx.upload(data)
+        
+        return (
+            f'{{"piece_cid": "{result.piece_cid}", '
+            f'"size": {result.size}, '
+            f'"tx_hash": "{result.tx_hash}"}}'
+        )
+
+
+__all__ = [
+    "FilecoinDocumentLoader",
+    "FilecoinStorageTool",
+    "FilecoinStorageInput",
+]

{synapse_filecoin_sdk-0.1.1.dist-info → synapse_filecoin_sdk-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synapse-filecoin-sdk
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python SDK for Filecoin Onchain Cloud (Synapse)
 Project-URL: Homepage, https://github.com/anjor/pynapse
 Project-URL: Repository, https://github.com/anjor/pynapse
@@ -18,6 +18,8 @@ Requires-Python: >=3.11
 Requires-Dist: httpx<0.28.0,>=0.25.0
 Requires-Dist: multiformats<0.4.0,>=0.3.1
 Requires-Dist: web3<7,>=6.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core<0.4,>=0.1.0; extra == 'langchain'
 Provides-Extra: test
 Requires-Dist: pytest-asyncio<0.24,>=0.23.0; extra == 'test'
 Requires-Dist: pytest<9,>=8.0.0; extra == 'test'
@@ -49,6 +51,30 @@ Python import: `pynapse`
 pip install synapse-filecoin-sdk
 ```
 
+## Supported Networks
+
+Both **Filecoin Mainnet** and **Calibration testnet** are supported:
+
+```python
+from pynapse import AsyncSynapse
+
+# Mainnet
+synapse = await AsyncSynapse.create(
+    rpc_url="https://api.node.glif.io/rpc/v1",
+    chain="mainnet",
+    private_key=PRIVATE_KEY
+)
+
+# Calibration testnet (for testing)
+synapse = await AsyncSynapse.create(
+    rpc_url="https://api.calibration.node.glif.io/rpc/v1",
+    chain="calibration",
+    private_key=PRIVATE_KEY
+)
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for a full tutorial using Calibration testnet.
+
 ## CommP / PieceCID
 
 `pynapse` uses `stream-commp` from `go-fil-commp-hashhash` for PieceCID calculation.
@@ -88,8 +114,8 @@ Publishing is automated via GitHub Actions in `.github/workflows/publish-pypi.ym
 3. Tag a release and push the tag:
 
 ```bash
-git tag v0.1.1
-git push origin v0.1.1
+git tag v0.2.0
+git push origin v0.2.0
 ```
 
 The workflow builds the package, runs `twine check`, and publishes to PyPI via OIDC (no API token required).

{synapse_filecoin_sdk-0.1.1.dist-info → synapse_filecoin_sdk-0.2.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 pynapse/__init__.py,sha256=EcNT2_edj2ICiSNlOjdiRTOsqSn4pK5-W0MCfMEHfEA,187
-pynapse/_version.py,sha256=rnObPjuBcEStqSO0S6gsdS_ot8ITOQjVj_-P1LUUYpg,22
+pynapse/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
 pynapse/synapse.py,sha256=crjmmtfFfQzRg4iZqwAOe9JOF-ddNi0PV432XQTyNNk,6582
 pynapse/contracts/__init__.py,sha256=8nz_zyobw86VKfzw7sZaoHrvf_YD8WrDuh89UdeEHLQ,757
 pynapse/contracts/abi_registry.py,sha256=PJQalwqabJWWdC65SUJUxIGz1f5zBxHbdyTQD3azckU,219
@@ -28,6 +28,8 @@ pynapse/evm/__init__.py,sha256=4lPmHfNArjp-QfYg-SpL6NzkoQ8JeSM3LsvjEMqgRkI,97
 pynapse/evm/client.py,sha256=OZY3MLq49KjjxTx3w25xgwoX9fWyvLfq1amFsHfzoLQ,608
 pynapse/filbeam/__init__.py,sha256=aY5abqgV5mJikOkn0IDNyjB8y9PsHwU8zWkUKL5dnGg,96
 pynapse/filbeam/service.py,sha256=2QcAakeDxiaNahAwX4O6KiEuUP3abXq_qyuPwsXaFQM,1311
+pynapse/integrations/__init__.py,sha256=cGYH_anpanboIpIOs1AOQKwMpN4cTMQNwvGeBmFPSwM,221
+pynapse/integrations/langchain.py,sha256=eQJBjZOWF9e7XoCCaONMi2Y125rPirhpBXt-nHChbZc,6684
 pynapse/payments/__init__.py,sha256=Hpwyec7OK8C1OVwrNgmxuH71pPzUBRsgwWXgZzKCt5c,302
 pynapse/payments/service.py,sha256=DFLhMgeuM7AWgZSe5dWtGEqa1amYDujbFr366BmfAkI,32121
 pynapse/pdp/__init__.py,sha256=cfS8u4nGQ7dKHZxy3fUCHSnwUTjkejNya9iGnOHCt9Q,490
@@ -58,7 +60,7 @@ pynapse/utils/metadata.py,sha256=-tEl9PAgPdBUhFqze0-ZRzn6_jIbiHTLDnlD3QM0FQ0,113
 pynapse/utils/piece_url.py,sha256=md27_fxtcCyBvREBLNBJquJMj1V1gSdobfHe9x3RmhU,513
 pynapse/warm_storage/__init__.py,sha256=WdUamV4veb7ZHyRWU12tQj8V5IVblbrgpNAyv5WSUE8,246
 pynapse/warm_storage/service.py,sha256=eRZEDkN0257cVSs665cRQYqZUlL-BDAxfAFD6GY344E,22770
-synapse_filecoin_sdk-0.1.1.dist-info/METADATA,sha256=UdcVnYG2xV_3RTiHy3nS7j4ZHGullFCqqdRwXKU3bVg,2618
-synapse_filecoin_sdk-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-synapse_filecoin_sdk-0.1.1.dist-info/licenses/LICENSE.md,sha256=AkqszG9dHKiuURbWTvtFVRX_X17biR28Tihp8Tt8xO0,12466
-synapse_filecoin_sdk-0.1.1.dist-info/RECORD,,
+synapse_filecoin_sdk-0.2.0.dist-info/METADATA,sha256=EdcnJylO0DxRPKbzBjkRXyLQZbNo7AdGWADg_1By2Fo,3266
+synapse_filecoin_sdk-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+synapse_filecoin_sdk-0.2.0.dist-info/licenses/LICENSE.md,sha256=AkqszG9dHKiuURbWTvtFVRX_X17biR28Tihp8Tt8xO0,12466
+synapse_filecoin_sdk-0.2.0.dist-info/RECORD,,