# SDK Conventions

This directory contains comprehensive convention documentation that serves as the **primary source** for all development decisions in the Pinecone Python SDK.

## Overview

The Pinecone Python SDK is designed to be:
- **Fast**: High-performance implementation with msgspec, HTTP/2, and connection pooling
- **Stable**: Interfaces that evolve without breaking
- **Delightful**: Intuitive for humans and AI agents
- **Consistent**: Same patterns everywhere
- **Verifiable**: Multiple layers of automated checking

## Convention Documents

### Core Architecture
- [**Architecture**](./architecture.md) - Layering, modules, and dependencies
- [**Naming**](./naming.md) - Naming conventions for files, classes, and methods
- [**Types**](./types.md) - Type hints, msgspec patterns, and validation approach
- [**Validation**](./validation.md) - Input validation utilities and patterns

### Error Handling & Async
- [**Errors**](./errors.md) - Exception hierarchy and error message patterns
- [**Async**](./async.md) - Async/sync patterns and dual implementation

### Testing & Performance
- [**Testing**](./testing.md) - Test types, organization, and patterns
- [**Performance**](./performance.md) - Performance guidelines and benchmarking

### API Design & Stability
- [**Versioning**](./versioning.md) - API versioning and migration strategy
- [**API Stability**](./api-stability.md) - 11 stability principles with examples
- [**Usability**](./usability.md) - 12 usability principles with examples
- [**Interactive Discovery**](./interactive-discovery.md) - REPL, IDE integration, and API exploration patterns

### Implementation Details
- [**HTTP Client**](./http-client.md) - HTTP client architecture and configuration

### Documentation & Writing
- [**Documentation**](./documentation.md) - Writing voice, docstrings, and code examples
- [**Pull Requests**](./pull-requests.md) - PR titles, descriptions, and examples
- [**Commit Messages**](./commit-messages.md) - Conventional Commits format and guidelines

## Using These Conventions

1. **Development**: Read relevant conventions before implementing features
2. **Code Review**: Reference conventions when reviewing code
3. **AI Agents**: These docs are optimized for AI consumption via Cursor rules
4. **Updates**: Keep conventions current as patterns evolve

## Automated Review Agents

The SDK includes specialized review agents that enforce these conventions automatically. See [AGENTS.md](../../AGENTS.md) for the complete list. Key agents:

- **@protocol-compliance-review** - Validates protocol implementations ([architecture.md](./architecture.md))
- **@pagination-review** - Validates paginated list operations ([pagination.md](./pagination.md))
- **@adapter-review** - Validates response transformations ([types.md](./types.md), [performance.md](./performance.md))
- **@error-handling-review** - Validates exception usage ([errors.md](./errors.md))
- **@dependency-review** - Validates package additions ([types.md](./types.md), [performance.md](./performance.md))
- **@performance-review** - Identifies performance issues ([performance.md](./performance.md))
- **@security-review** - Identifies security vulnerabilities ([errors.md](./errors.md))
- **@async-review** - Validates async/await correctness ([async.md](./async.md))
- **@test-quality-review** - Validates test coverage and quality ([testing.md](./testing.md))
- **@ux-review** - Validates API ergonomics ([usability.md](./usability.md))

Use these agents during development to catch issues before code review.

## Principles

All conventions follow these meta-principles:

1. **Explicit over Implicit**: Make behavior obvious from the code
2. **Consistency over Cleverness**: Prefer patterns that work everywhere
3. **Safety over Convenience**: Default to safe behavior, allow opt-in
4. **Performance Matters**: Design for speed from the start
5. **AI-Friendly**: Clear patterns that AI agents can follow reliably

## Questions?

When conventions conflict or are unclear:
1. Check related convention docs for clarification
2. Look for examples in the reference implementation
3. Discuss in team channels to reach consensus
4. Update conventions to reflect the decision

---

*Last audited: February 5, 2026*
