# Pinecone Python SDK

[![Verification](https://github.com/pinecone-io/python-sdk/actions/workflows/verification.yaml/badge.svg)](https://github.com/pinecone-io/python-sdk/actions/workflows/verification.yaml)
[![codecov](https://codecov.io/gh/pinecone-io/python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/pinecone-io/python-sdk)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

## Development

### Setup

```bash
# Initialize git submodules (optional, internal Pinecone employees only)
# The apis submodule contains OpenAPI specs and is not required for SDK development
git submodule update --init

# Install dependencies with uv
uv sync

# Install pre-commit hooks
pre-commit install
```

**Note:** The `apis/` submodule is only accessible to Pinecone employees. External contributors can develop and test the SDK without it.

### Interactive Testing

**REPL:** Quickly test and experiment with the SDK using the interactive REPL:

```bash
uv run repl
```

The REPL automatically:
- Loads environment variables from `.env`
- Creates pre-configured `pc` (sync) and `apc` (async) client instances using `PINECONE_API_KEY`
- Sets up logging for debugging
- Maintains command history across sessions

Example session:

```python
>>> response = pc.inference.embed(model="multilingual-e5-large", inputs=["hello world"])
>>> response.model  # Attribute access (recommended)
>>> data = response.to_dict()  # Convert to dict
>>> data["model"]  # Dict access after to_dict()
>>> response.to_json()  # Convert to JSON
>>> await apc.inference.embed(model="multilingual-e5-large", inputs=["hello world"])
```

**Jupyter Notebooks:** For more exploratory testing or creating demos, ask your AI assistant to create a test notebook:

```
"Create a jupyter notebook to test the embeddings API"
```

This will generate `notebooks/test_TIMESTAMP.ipynb` with automatic environment setup and client initialization. It will load environment variables from your `.env` file. See [.cursor/skills/jupyter-notebook/SKILL.md](.cursor/skills/jupyter-notebook/SKILL.md) for details.

### Maintaining this package with AI coding assistants

This repository includes rules, skills, and agents for AI coding assistants. Both Cursor and Claude Code are supported.

**📖 New to this repository? Start with [HUMANS.md](HUMANS.md)** - A complete guide showing how to work effectively with AI assistants in this codebase, including realistic workflows and examples.

- **Cursor users**: Configuration files are in `.cursor/` directory
- **Claude Code users**: Access via `.claude/` symlinks (points to same files)
- **Editing**: Changes made through either tool are immediately available to the other

The configuration includes:
- **Rules** (`.cursor/rules/`): Architecture, naming conventions, commit messages, documentation style, error handling, testing patterns
- **Skills** (`.cursor/skills/`): Common development tasks like adding methods, implementing protocols, writing tests
- **Agents** (`.cursor/agents/`): Code reviewers for async patterns, docstrings, performance, security, and test quality

For technical details, see [AGENTS.md](AGENTS.md).

## Documentation

### User Documentation

Build the Sphinx documentation:

```bash
# Build HTML documentation (dependencies installed via uv sync)
cd docs
make html

# Open in browser
open _build/html/index.html
```

Other useful commands:

```bash
make doctest    # Test code examples in docstrings
make linkcheck  # Verify all links work
make coverage   # Check documentation coverage
make clean      # Remove build artifacts
```

### Developer Documentation

- [Architecture](docs/architecture/) - System design and architecture
- [Conventions](docs/conventions/) - Coding standards and patterns
- [Development Workflow](docs/development-workflow.md) - Step-by-step guides for common tasks

---

*Last audited: February 5, 2026*
