Metadata-Version: 2.4
Name: langchain-keiro
Version: 0.1.0
Summary: An integration package connecting Keiro and LangChain
Project-URL: Homepage, https://keirolabs.cloud
Project-URL: Repository, https://github.com/keirolabs/langchain-keiro
Project-URL: Source Code, https://github.com/keirolabs/langchain-keiro
Project-URL: Documentation, https://docs.keirolabs.cloud
Author-email: Keiro Labs <team@keirolabs.cloud>
License: MIT
License-File: LICENSE
Keywords: embeddings,keiro,langchain,rag,retriever,search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <4.0.0,>=3.10.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: langchain-core<1.0.0,>=0.3.29
Requires-Dist: pydantic<3.0.0,>=2.6.0
Provides-Extra: test
Requires-Dist: langchain-core; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: respx>=0.22.0; extra == 'test'
Description-Content-Type: text/markdown

# langchain-keiro

Official LangChain integration for the [Keiro](https://keirolabs.cloud) deep search API with embeddings.

All components use **deep mode** with **embeddings enabled** — no configuration needed. Every request returns full content plus 768-dimensional embedding vectors (configurable to 384/512/1024 via Matryoshka).

## Installation

```bash
pip install langchain-keiro
```

## Quick Start

### Retriever

Use Keiro as a LangChain retriever for RAG pipelines:

```python
from langchain_keiro.retrievers import KeiroRetriever

retriever = KeiroRetriever(
    keiro_api_key="keiro_...",
    max_results=3,
)

# Sync
docs = retriever.invoke("What is artificial intelligence?")

# Async
docs = await retriever.ainvoke("What is artificial intelligence?")

# Each doc includes embeddings in metadata:
# doc.metadata["query_embedding"]  — 768-dim vector for the query
# doc.metadata["chunk_embeddings"]  — per-chunk embeddings with text
# doc.metadata["tldr"], ["tags"], ["entities"], etc.

# Use in a RAG chain
from langchain_openai import ChatOpenAI
from langchain.chains import create_retrieval_chain

llm = ChatOpenAI(model="gpt-4")
chain = create_retrieval_chain(retriever, llm)
response = chain.invoke({"input": "What is AI?"})
```

### Embeddings

Generate embedding vectors directly:

```python
from langchain_keiro.embeddings import KeiroEmbeddings

embeddings = KeiroEmbeddings(
    keiro_api_key="keiro_...",
    dimensions=768,  # Matryoshka: 384, 512, 768, or 1024
)

# Single query
vec = embeddings.embed_query("What is AI?")
# vec is a list of 768 floats

# Batch documents
vecs = embeddings.embed_documents(["doc 1", "doc 2", "doc 3"])

# Async
vec = await embeddings.aembed_query("What is AI?")
vecs = await embeddings.aembed_documents(["doc 1", "doc 2"])
```

### Tool (for Agents)

Use Keiro as a tool in LangChain agents:

```python
from langchain_keiro.tools import KeiroSearchTool

tool = KeiroSearchTool(keiro_api_key="keiro_...")

# Direct invocation
result = tool.invoke({"query": "latest AI research"})

# With an agent
from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4")
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a research assistant. Use the keiro_search tool to find information."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, [tool], prompt)
agent_executor = AgentExecutor(agent=agent, tools=[tool])
response = agent_executor.invoke({"input": "What are the latest AI trends?"})
```

## Configuration

### KeiroRetriever

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `keiro_api_key` | `SecretStr` | required | Your Keiro API key |
| `base_url` | `str` | `https://kierolabs.space/api` | API base URL |
| `max_results` | `int` | `3` | Number of results (1-5) |
| `embedding_dimensions` | `int` | `768` | Vector dimensions (384, 512, 768, 1024) |

Always uses `mode="deep"` with `embeddings.enabled=true`.

### KeiroEmbeddings

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `keiro_api_key` | `SecretStr` | required | Your Keiro API key |
| `base_url` | `str` | `https://kierolabs.space/api` | API base URL |
| `model` | `str` | `"pplx-embed-v1-0.6b"` | Embedding model identifier |
| `dimensions` | `int` | `768` | Vector dimensions (384, 512, 768, 1024) |

### KeiroSearchTool

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `keiro_api_key` | `SecretStr` | required | Your Keiro API key |
| `base_url` | `str` | `https://kierolabs.space/api` | API base URL |

Always uses `mode="deep"` with `embeddings.enabled=true`.

## Embedding Dimensions (Matryoshka)

The Keiro API supports Matryoshka embedding dimensions, allowing you to trade off vector size for precision:

- **384**: Smallest, fastest, least precise
- **512**: Good balance for lightweight use
- **768** (default): Standard precision
- **1024**: Maximum precision

## Response Enrichment

The deep mode response includes rich metadata beyond just content:

| Field | Description |
|-------|-------------|
| `query_embedding` | 768-dim embedding vector for the search query |
| `chunk_embeddings` | Per-chunk embeddings with text and offset |
| `tldr` | AI-generated summary of the page |
| `tags` | Extracted topic tags |
| `entities` | Named entities found in the content |
| `readingTime` | Estimated reading time |
| `wordCount` | Word count of the content |
| `credibility` | Source credibility score |
| `quality` | Content quality score |

## API Key

Get your API key at [keirolabs.cloud](https://keirolabs.cloud). The Explorer plan includes 500 free credits.

## Development

```bash
# Install for development
pip install -e ".[test]"

# Run unit tests
pytest tests/unit_tests/

# Run integration tests (requires KEIRO_API_KEY)
KEIRO_API_KEY=keiro_... pytest tests/integration_tests/
```

## License

MIT