# Quick Start Guide

Get started with the Pinecone Python SDK in minutes.

## Installation

Install the SDK using pip:

```bash
pip install pinecone
```

## Authentication

Set your API key as an environment variable:

```bash
export PINECONE_API_KEY="your-api-key"
```

Or pass it directly when creating the client:

```python
from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
```

## Generate Embeddings

Use the inference API to generate embeddings:

```python
from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")

response = pc.inference.embed(
    model="multilingual-e5-large",
    texts=["Hello world", "Goodbye world"],
    parameters={"input_type": "passage", "truncate": "END"}
)

print(f"Generated {len(response.embeddings)} embeddings")
for i, embedding in enumerate(response.embeddings):
    print(f"Text {i}: {len(embedding)} dimensions")
```

## Rerank Documents

Rerank documents by relevance to a query:

```python
from pinecone import Pinecone, RerankDocument

pc = Pinecone(api_key="your-api-key")

documents = [
    RerankDocument(id="1", text="Pinecone is a vector database"),
    RerankDocument(id="2", text="Python is a programming language"),
    RerankDocument(id="3", text="Vectors are mathematical objects"),
]

response = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="What is Pinecone?",
    documents=documents,
    top_n=2
)

for result in response.results:
    print(f"Document {result.document.id}: {result.document.text}")
    print(f"Score: {result.score}")
```

## Async Usage

For async operations, use `AsyncPinecone`. The async client is safe to create in any context and will initialize properly when first used:

```python
import asyncio
from pinecone import AsyncPinecone

async def main():
    # Use async context manager for automatic cleanup
    async with AsyncPinecone(api_key="your-api-key") as pc:
        response = await pc.inference.embed(
            model="multilingual-e5-large",
            texts=["Hello world"],
            parameters={"input_type": "passage", "truncate": "END"}
        )
        print(f"Generated {len(response.embeddings)} embeddings")

asyncio.run(main())
```

### Concurrent Processing

Process multiple requests in parallel with `asyncio.gather`:

```python
async def embed_many(texts: list[str]):
    async with AsyncPinecone(api_key="your-api-key") as pc:
        # Split into batches
        batches = [texts[i:i+100] for i in range(0, len(texts), 100)]

        # Process concurrently
        tasks = [
            pc.inference.embed(model="multilingual-e5-large", texts=batch)
            for batch in batches
        ]
        results = await asyncio.gather(*tasks)

        # Flatten results
        return [emb for result in results for emb in result.embeddings]
```

### Web Framework Integration

The client is safe to create at module level for web frameworks:

```python
from fastapi import FastAPI
from pinecone import AsyncPinecone

app = FastAPI()
pc = AsyncPinecone(api_key="your-api-key")

@app.get("/embed")
async def embed(text: str):
    response = await pc.inference.embed(
        model="multilingual-e5-large",
        texts=[text],
    )
    return {"embedding": response.embeddings[0]}

@app.on_event("shutdown")
async def shutdown():
    await pc.close()
```

## Next Steps

- Learn about [configuration options](configuration.md)
- Understand [error handling](error-handling.md)
- Explore the [API reference](../api/client.rst)
