langchain-seahorse 0.1.0
LangChain VectorStore integration for Seahorse API Gateway
License: MIT
Requires Python: <4.0,>=3.8.1
Keywords: embeddings, langchain, seahorse, vector-database, vectorstore

# LangChain Seahorse VectorStore

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

LangChain VectorStore integration for Seahorse API Gateway - A high-performance vector database for semantic search and RAG applications.

## Features

- **LangChain Compatible**: Full implementation of LangChain VectorStore interface
- **Dual Embedding Support**: Use Seahorse's built-in embeddings or bring your own (OpenAI, Cohere, etc.)
- **Metadata Filtering**: Filter search results by metadata
- **Batch Processing**: Efficient handling of large datasets (1024 documents per batch)
- **Type-Safe**: Complete type hints for Python 3.8+
- **Well-Tested**: Comprehensive unit and integration tests

## Installation

```bash
# Using pip
pip install langchain-seahorse

# Using uv (recommended)
uv add langchain-seahorse
```

## Quick Start

### Basic Usage with Built-in Embeddings

```python
from seahorse_vector_store import SeahorseVectorStore

# Initialize vectorstore
vectorstore = SeahorseVectorStore(
    api_key="your-seahorse-api-key",
    base_url="https://your-table-uuid.api.seahorse.dnotitia.ai",
)

# Add documents
ids = vectorstore.add_texts(
    texts=[
        "Machine learning is a subset of AI.",
        "Deep learning uses neural networks.",
    ],
    metadatas=[
        {"source": "doc1.pdf", "page": 1},
        {"source": "doc2.pdf", "page": 5},
    ]
)

# Search
docs = vectorstore.similarity_search(
    query="What is machine learning?",
    k=2
)

for doc in docs:
    print(doc.page_content)
    print(doc.metadata)
```

### Using External Embeddings

```python
from seahorse_vector_store import SeahorseVectorStore
from langchain_openai import OpenAIEmbeddings

vectorstore = SeahorseVectorStore(
    api_key="your-seahorse-api-key",
    base_url="https://your-table-uuid.api.seahorse.dnotitia.ai",
    embedding=OpenAIEmbeddings(api_key="your-openai-key"),
    use_builtin_embedding=False,
)

# Use as normal...
```

### Metadata Filtering

```python
# Search with metadata filter
docs = vectorstore.similarity_search(
    query="neural networks",
    k=5,
    filter={"source": "doc1.pdf", "page": 1}
)
```

## 🔧 Configuration

### Environment Variables

You can set API credentials via environment variables:

```bash
export SEAHORSE_API_KEY="your-api-key"
export SEAHORSE_BASE_URL="https://your-table-uuid.api.seahorse.dnotitia.ai"
```

Then use them in your code:

```python
import os
from seahorse_vector_store import SeahorseVectorStore

vectorstore = SeahorseVectorStore(
    api_key=os.environ["SEAHORSE_API_KEY"],
    base_url=os.environ["SEAHORSE_BASE_URL"],
)
```

### Advanced Options

```python
vectorstore = SeahorseVectorStore(
    api_key="your-api-key",
    base_url="https://your-table-uuid.api.seahorse.dnotitia.ai",
    use_builtin_embedding=True,  # Use Seahorse embeddings
    index_name="embedding",      # Vector column name
)
```

## 📖 API Reference

### SeahorseVectorStore

Main class for interacting with Seahorse as a vector store.

#### Synchronous Methods

- `add_texts(texts, metadatas=None, **kwargs)` - Add texts to the vector store
- `similarity_search(query, k=4, filter=None, **kwargs)` - Search for similar documents
- `similarity_search_with_score(query, k=4, filter=None, **kwargs)` - Search with distance scores
- `similarity_search_by_vector(embedding, k=4, filter=None, **kwargs)` - Search by vector
- `similarity_search_by_vector_with_score(embedding, k=4, filter=None, **kwargs)` - Search by vector with scores
- `delete(ids=None, **kwargs)` - Delete documents by IDs
- `from_texts(texts, embedding=None, metadatas=None, **kwargs)` - Create vectorstore from texts

#### Async Methods

- `aadd_texts(texts, metadatas=None, **kwargs)` - Add texts asynchronously
- `asimilarity_search(query, k=4, filter=None, **kwargs)` - Search asynchronously
- `asimilarity_search_with_score(query, k=4, filter=None, **kwargs)` - Search with scores asynchronously
- `asimilarity_search_by_vector(embedding, k=4, filter=None, **kwargs)` - Search by vector asynchronously
- `asimilarity_search_by_vector_with_score(embedding, k=4, filter=None, **kwargs)` - Search by vector with scores asynchronously
- `adelete(ids=None, **kwargs)` - Delete documents asynchronously

#### Not Supported

- `max_marginal_relevance_search()` - ⚠️ MMR search is not supported by Seahorse API


## Testing

### Setup for Integration Tests

Create a `.env` file in the project root with your Seahorse credentials:

```bash
# Copy the example file
cp .env.example .env

# Edit .env and add your credentials
SEAHORSE_API_KEY=your-api-key
SEAHORSE_BASE_URL=https://your-table-uuid.api.seahorse.dnotitia.ai
```

### Running Tests

```bash
# Run unit tests
uv run pytest tests/unit/

# Run basic integration tests (requires .env file with API credentials)
uv run pytest tests/integration/ \
  --ignore=tests/integration/test_ollama_embeddings.py \
  --ignore=tests/integration/test_rag_pipeline.py

# Run all tests with coverage
uv run pytest --cov=seahorse_vector_store --cov-report=term-missing

# Skip integration tests
uv run pytest -m "not integration"
```

### Running Ollama Integration Tests (Optional)

For advanced tests using Ollama LLM and embeddings:

```bash
# 1. Install Ollama dependencies (Python 3.9+ required)
uv pip install langchain langchain-ollama

# 2. Start Ollama server
ollama serve

# 3. Download models
ollama pull qwen3-embedding:8b  # For embeddings
ollama pull qwen3:8b             # For RAG

# 4. Run Ollama tests
uv run pytest tests/integration/test_ollama_embeddings.py -v
uv run pytest tests/integration/test_rag_pipeline.py -v

# 5. Run all integration tests (including Ollama)
uv run pytest tests/integration/ -v
```

**Note**: Ollama tests will automatically skip if Ollama is not available or required models are not installed.

## Examples

See the `examples/` directory for complete examples:

- `basic_usage.py` - Basic vectorstore operations
- `async_usage.py` - Async/await operations for better performance
- `rag_pipeline.py` - Building a RAG (Retrieval-Augmented Generation) pipeline
- `metadata_filtering.py` - Advanced metadata filtering techniques
- `external_embeddings.py` - Using external embeddings (OpenAI, Cohere, etc.)

## Documentation

- [API Reference](docs/API_REFERENCE.md) - Complete API documentation
- [Tutorial](./TUTORIAL.md) 

## Requirements

- Python 3.8+
- langchain-core >= 0.2.0
- httpx >= 0.27.0
- pydantic >= 2.0.0

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

- **Console**: [Seahorse Console](https://console.seahorse.dnotitia.ai)

## Links

- [LangChain Documentation](https://python.langchain.com/)
- [Seahorse Cloud](https://console.seahorse.dnotitia.ai)

## Development Status

This package is in **Alpha** stage. APIs may change between versions.

Current version: **0.1.0**

---

Made with by the Seahorse Team