# LangChain Seahorse VectorStore SDK

You are an expert Python developer working on a LangChain VectorStore integration for Seahorse API Gateway.

## Project Overview

- **Target**: PyPI-ready Python SDK (`langchain-seahorse`)
- **Python Version**: 3.8 - 3.12
- **Package Manager**: uv
- **Key Dependencies**: langchain-core, httpx, pydantic

## Python Development Standards

### Code Style

- Follow PEP 8 strictly
- Max line length: 88 characters (Black default)
- Use 4 spaces for indentation (no tabs)
- Import order: standard library → third-party → local modules

```python
# Good example
import json
from typing import Any, Dict, List, Optional

import httpx
from langchain_core.vectorstores import VectorStore

from langchain_seahorse.client import SeahorseClient
```

### Type Hints (Required)

- Add complete type hints to ALL functions and methods
- Use `List`, `Dict`, `Optional` from `typing` (Python 3.8 compatibility)
- Always specify return types (use `-> None` if no return)

```python
# ✅ Good
def add_texts(
    self,
    texts: List[str],
    metadatas: Optional[List[Dict[str, Any]]] = None,
    **kwargs: Any,
) -> List[str]:
    pass

# ❌ Bad
def add_texts(self, texts, metadatas=None, **kwargs):
    pass
```

### Docstrings (Required)

Use Google-style docstrings for all public functions, classes, and methods:

```python
def similarity_search(
    self,
    query: str,
    k: int = 4,
    filter: Optional[Dict[str, Any]] = None,
    **kwargs: Any,
) -> List[Document]:
    """Search for similar documents using natural language query.
    
    Args:
        query: Search query text
        k: Number of documents to return (default: 4)
        filter: Optional metadata filter
        **kwargs: Additional arguments
    
    Returns:
        List of similar Document objects
    
    Raises:
        SeahorseAPIError: If API call fails
        SeahorseValidationError: If parameters are invalid
    
    Examples:
        >>> vectorstore = SeahorseVectorStore(api_key="key", base_url="url")
        >>> docs = vectorstore.similarity_search("machine learning", k=5)
    """
    pass
```

### Naming Conventions

- Classes: `PascalCase` (e.g., `SeahorseVectorStore`)
- Functions/methods: `snake_case` (e.g., `add_texts`)
- Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRIES`)
- Private members: `_leading_underscore` (e.g., `_client`)

### Code Quality Tools

Always run these before committing:

```bash
uv run black langchain_seahorse/      # Format code
uv run ruff check langchain_seahorse/ --fix  # Lint and fix
uv run mypy langchain_seahorse/       # Type check
```

## Testing Standards

### Test Structure

```
tests/
├── unit/              # Unit tests (with mocks)
│   ├── test_vectorstore.py
│   ├── test_client.py
│   └── test_filters.py
├── integration/       # Integration tests (real API calls)
│   ├── test_add_texts.py
│   └── test_search.py
└── conftest.py        # pytest fixtures
```

### Testing Requirements

- Maintain **minimum 80% test coverage**
- Test all public methods
- Include error cases and edge cases
- Use mocks for unit tests
- Use real API for integration tests (with proper fixtures)

### Running Tests

```bash
uv run pytest                            # All tests
uv run pytest tests/unit/                # Unit tests only
uv run pytest tests/integration/         # Integration tests only
uv run pytest --cov=langchain_seahorse   # With coverage
```

## Project-Specific Rules

### Important: Refer to Documentation

For project-specific implementation details, **always refer to the `docs/` directory**:

- `docs/TECHNICAL_SPEC.md` - API specifications and data models
- `docs/ARCHITECTURE.md` - System architecture and class design
- `docs/DEV_GUIDELINES.md` - Development guidelines and workflows
- `docs/TEST_REQUIREMENTS.md` - Testing strategies and requirements
- `docs/SUMMARY.md` - Quick reference for confirmed information
- `docs/api/gw-api-specification-rc15.md` - Seahorse API documentation

### Key Project Constraints

- **Python 3.8 compatibility required** - Use `List[str]` not `list[str]`
- **LangChain VectorStore interface** - Must inherit from `langchain_core.vectorstores.VectorStore`
- **Seahorse API specifics** - CoralResponse wrapper, metadata filtering, etc. (see `docs/TECHNICAL_SPEC.md`)
- **Package manager** - Use `uv` for all dependency management

## Additional Guidelines

### Security

- Never hardcode API keys
- Use environment variables for sensitive data
- Add `.env` to `.gitignore`

### Performance

- Use batch processing for large datasets (recommended batch size: 1024)
- Minimize unnecessary API calls
- Consider caching when appropriate

### Compatibility

- Support Python 3.8 - 3.12
- Maintain backward compatibility
- Use major version bump for breaking changes (Semantic Versioning)

## Quick Commands

```bash
# Development
uv sync                                  # Sync dependencies
source .venv/bin/activate                # Activate venv

# Code quality
uv run black langchain_seahorse/
uv run ruff check langchain_seahorse/ --fix
uv run mypy langchain_seahorse/

# Testing
uv run pytest --cov=langchain_seahorse

# Build & Deploy
uv build                                 # Build package
uv publish                               # Publish to PyPI
```

## Summary for AI Assistant

1. **Always add type hints** (Python 3.8 compatible)
2. **Write Google-style docstrings** for all public APIs
3. **Follow LangChain VectorStore interface** exactly
4. **Refer to `docs/` directory** for project-specific details
5. **Use Conventional Commits** for all commits
6. **Run code quality tools** (Black, Ruff, Mypy) before committing
7. **Write tests** (Unit + Integration, 80%+ coverage)
8. **Check documentation** in `docs/` folder for API specifics and implementation details

