langchain-ceramic 0.1.0__tar.gz

langchain_ceramic-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: langchain-ceramic
+Version: 0.1.0
+Summary: An integration package connecting Ceramic and LangChain
+License: MIT
+Author: Ceramic Team
+Author-email: info@ceramic.ai
+Requires-Python: >=3.10,<4.0
+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
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ceramic-ai (>=0.1.0)
+Requires-Dist: langchain-core (>=0.3.0,<1.0.0)
+Project-URL: Repository, https://github.com/CeramicTeam/langchain-ceramic
+Description-Content-Type: text/markdown
+
+# LangChain Ceramic
+
+LangChain integration for [Ceramic](https://ceramic.ai) — a web search API built for LLMs.
+
+## Installation
+
+```bash
+pip install langchain-ceramic
+```
+
+## Setup
+
+Generate an API key at [platform.ceramic.ai/keys](https://platform.ceramic.ai/keys), then export it:
+
+```bash
+export CERAMIC_API_KEY="your-api-key"
+```
+
+Or pass it directly when constructing the retriever or tool.
+
+## Usage
+
+### CeramicRetriever in a RAG chain
+
+```python
+from langchain_ceramic import CeramicRetriever
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.runnables import RunnablePassthrough
+from langchain_openai import ChatOpenAI
+
+retriever = CeramicRetriever(k=5)  # reads CERAMIC_API_KEY from env
+
+prompt = ChatPromptTemplate.from_template(
+    "Answer the question based only on the following context:\n\n{context}\n\nQuestion: {question}"
+)
+
+chain = (
+    {"context": retriever, "question": RunnablePassthrough()}
+    | prompt
+    | ChatOpenAI(model="gpt-5.5")
+    | StrOutputParser()
+)
+
+answer = chain.invoke("What are the latest AI chip export restrictions?")
+print(answer)
+```
+
+Each retrieved `Document` has:
+- `page_content`: the result description
+- `metadata["title"]`: page title
+- `metadata["url"]`: source URL
+
+### CeramicSearch in an agent
+
+```python
+from langchain_ceramic import CeramicSearch
+from langchain_openai import ChatOpenAI
+from langchain.agents import create_agent
+
+tools = [CeramicSearch(max_results=5)]
+agent = create_agent(ChatOpenAI(model="gpt-5.5"), tools=tools)
+
+result = agent.invoke({"messages": [{"role": "user", "content": "Find recent news about GLP-1 drugs"}]})
+print(result["messages"][-1].content)
+```
+
+### Async usage
+
+Both `CeramicRetriever` and `CeramicSearch` support async:
+
+```python
+docs = await retriever.ainvoke("California rental laws")
+```
+
+## API reference
+
+### `CeramicRetriever`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str \| None` | `None` | Ceramic API key (falls back to `CERAMIC_API_KEY` env var) |
+| `k` | `int` | `10` | Maximum number of results to return |
+
+### `CeramicSearch`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str \| None` | `None` | Ceramic API key (falls back to `CERAMIC_API_KEY` env var) |
+| `max_results` | `int` | `5` | Maximum number of results to include in the response string |
+

langchain_ceramic-0.1.0/README.md

@@ -0,0 +1,90 @@
+# LangChain Ceramic
+
+LangChain integration for [Ceramic](https://ceramic.ai) — a web search API built for LLMs.
+
+## Installation
+
+```bash
+pip install langchain-ceramic
+```
+
+## Setup
+
+Generate an API key at [platform.ceramic.ai/keys](https://platform.ceramic.ai/keys), then export it:
+
+```bash
+export CERAMIC_API_KEY="your-api-key"
+```
+
+Or pass it directly when constructing the retriever or tool.
+
+## Usage
+
+### CeramicRetriever in a RAG chain
+
+```python
+from langchain_ceramic import CeramicRetriever
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.runnables import RunnablePassthrough
+from langchain_openai import ChatOpenAI
+
+retriever = CeramicRetriever(k=5)  # reads CERAMIC_API_KEY from env
+
+prompt = ChatPromptTemplate.from_template(
+    "Answer the question based only on the following context:\n\n{context}\n\nQuestion: {question}"
+)
+
+chain = (
+    {"context": retriever, "question": RunnablePassthrough()}
+    | prompt
+    | ChatOpenAI(model="gpt-5.5")
+    | StrOutputParser()
+)
+
+answer = chain.invoke("What are the latest AI chip export restrictions?")
+print(answer)
+```
+
+Each retrieved `Document` has:
+- `page_content`: the result description
+- `metadata["title"]`: page title
+- `metadata["url"]`: source URL
+
+### CeramicSearch in an agent
+
+```python
+from langchain_ceramic import CeramicSearch
+from langchain_openai import ChatOpenAI
+from langchain.agents import create_agent
+
+tools = [CeramicSearch(max_results=5)]
+agent = create_agent(ChatOpenAI(model="gpt-5.5"), tools=tools)
+
+result = agent.invoke({"messages": [{"role": "user", "content": "Find recent news about GLP-1 drugs"}]})
+print(result["messages"][-1].content)
+```
+
+### Async usage
+
+Both `CeramicRetriever` and `CeramicSearch` support async:
+
+```python
+docs = await retriever.ainvoke("California rental laws")
+```
+
+## API reference
+
+### `CeramicRetriever`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str \| None` | `None` | Ceramic API key (falls back to `CERAMIC_API_KEY` env var) |
+| `k` | `int` | `10` | Maximum number of results to return |
+
+### `CeramicSearch`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str \| None` | `None` | Ceramic API key (falls back to `CERAMIC_API_KEY` env var) |
+| `max_results` | `int` | `5` | Maximum number of results to include in the response string |

langchain_ceramic-0.1.0/langchain_ceramic/__init__.py

@@ -0,0 +1,4 @@
+from langchain_ceramic.retrievers import CeramicRetriever
+from langchain_ceramic.tools import CeramicSearch
+
+__all__ = ["CeramicRetriever", "CeramicSearch"]

langchain_ceramic-0.1.0/langchain_ceramic/retrievers.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForRetrieverRun,
+    CallbackManagerForRetrieverRun,
+)
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import ConfigDict, PrivateAttr, model_validator
+
+from ceramic_ai import AsyncCeramic, Ceramic
+
+
+class CeramicRetriever(BaseRetriever):
+    """Retriever that uses Ceramic's web search API.
+
+    Setup:
+        Install the package and set your API key:
+
+        .. code-block:: bash
+
+            pip install langchain-ceramic
+            export CERAMIC_API_KEY="your-api-key"
+
+    Example:
+        .. code-block:: python
+
+            from langchain_ceramic import CeramicRetriever
+
+            retriever = CeramicRetriever(k=5)
+            docs = retriever.invoke("latest AI chip export restrictions")
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    api_key: Optional[str] = None
+    k: int = 10
+
+    _client: Ceramic = PrivateAttr(default=None)
+    _async_client: AsyncCeramic = PrivateAttr(default=None)
+
+    @model_validator(mode="after")
+    def validate_api_key(self) -> "CeramicRetriever":
+        key = self.api_key or os.environ.get("CERAMIC_API_KEY")
+        if not key:
+            raise ValueError(
+                "Ceramic API key required. Pass api_key= or set CERAMIC_API_KEY."
+            )
+        self._client = Ceramic(api_key=key)
+        self._async_client = AsyncCeramic(api_key=key)
+        return self
+
+    def _get_relevant_documents(
+        self, query: str, *, run_manager: CallbackManagerForRetrieverRun
+    ) -> list[Document]:
+        response = self._client.search(query=query)
+        return [
+            Document(
+                page_content=result.description or "",
+                metadata={"title": result.title, "url": result.url},
+            )
+            for result in response.result.results[: self.k]
+        ]
+
+    async def _aget_relevant_documents(
+        self, query: str, *, run_manager: AsyncCallbackManagerForRetrieverRun
+    ) -> list[Document]:
+        response = await self._async_client.search(query=query)
+        return [
+            Document(
+                page_content=result.description or "",
+                metadata={"title": result.title, "url": result.url},
+            )
+            for result in response.result.results[: self.k]
+        ]

langchain_ceramic-0.1.0/langchain_ceramic/tools.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import os
+from typing import Optional, Type
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, model_validator
+
+from ceramic_ai import AsyncCeramic, Ceramic
+
+
+class CeramicSearchInput(BaseModel):
+    query: str = Field(description="Search query to look up on the web.")
+
+
+class CeramicSearch(BaseTool):
+    """Tool that queries the Ceramic web search API.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install langchain-ceramic
+            export CERAMIC_API_KEY="your-api-key"
+
+    Example:
+        .. code-block:: python
+
+            from langchain_ceramic import CeramicSearch
+
+            tool = CeramicSearch(max_results=5)
+            tool.invoke("latest developments in GLP-1 drugs")
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str = "ceramic_search"
+    description: str = (
+        "A web search tool powered by Ceramic. "
+        "Use this to find current information from the web. "
+        "Input should be a search query string."
+    )
+    args_schema: Type[BaseModel] = CeramicSearchInput
+
+    api_key: Optional[str] = None
+    max_results: int = 5
+
+    _client: Ceramic = PrivateAttr(default=None)
+    _async_client: AsyncCeramic = PrivateAttr(default=None)
+
+    @model_validator(mode="after")
+    def validate_api_key(self) -> "CeramicSearch":
+        key = self.api_key or os.environ.get("CERAMIC_API_KEY")
+        if not key:
+            raise ValueError(
+                "Ceramic API key required. Pass api_key= or set CERAMIC_API_KEY."
+            )
+        self._client = Ceramic(api_key=key)
+        self._async_client = AsyncCeramic(api_key=key)
+        return self
+
+    def _run(self, query: str) -> str:
+        response = self._client.search(query=query)
+        results = response.result.results[: self.max_results]
+        return "\n\n".join(
+            f"**{r.title}**\n{r.description}\nSource: {r.url}" for r in results
+        )
+
+    async def _arun(self, query: str) -> str:
+        response = await self._async_client.search(query=query)
+        results = response.result.results[: self.max_results]
+        return "\n\n".join(
+            f"**{r.title}**\n{r.description}\nSource: {r.url}" for r in results
+        )

langchain_ceramic-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[tool.poetry]
+name = "langchain-ceramic"
+version = "0.1.0"
+description = "An integration package connecting Ceramic and LangChain"
+authors = ["Ceramic Team <info@ceramic.ai>"]
+readme = "README.md"
+repository = "https://github.com/CeramicTeam/langchain-ceramic"
+license = "MIT"
+include = ["langchain_ceramic/py.typed"]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+langchain-core = ">=0.3.0,<1.0.0"
+ceramic-ai = ">=0.1.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-asyncio = "^0.21.0"
+langchain = ">=0.3.0"
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config --durations=5"
+asyncio_mode = "auto"
+markers = [
+    "integration: marks tests as integration tests (require CERAMIC_API_KEY)",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"