> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aisearchapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

This SDK helps you use the **AI Search API** in your Python projects.\
It gives you **semantic search**, context support, and flexible outputs with a simple Pythonic interface.

👉 To start, get your free API key from the [AI Search API dashboard](https://app.aisearchapi.io/dashboard).

## Features

* 🔍 **AI-Powered Semantic Search** – Use advanced embeddings for natural language queries
* 🎯 **Context Awareness** – Add chat-like history for smarter results
* ⚡ **Simple API Client** – Clean Python interface with error handling
* 🛡️ **Type Safety** – Full type hints for modern Python
* 🔄 **Flexible Output** – Choose plain text or markdown responses
* 💰 **Usage Tracking** – Monitor your credits anytime

***

# Installation

Install from PyPI:

```bash theme={null}
pip install aisearchapi-client
```

Or install from source:

```bash theme={null}
git clone https://github.com/aisearchapi/aisearchapi-python.git
cd aisearchapi-python
pip install -e .
```

***

# Quick Start

## Get Your API Key

1. [Sign up](https://app.aisearchapi.io/join)
2. [Log in](https://app.aisearchapi.io/login)
3. Copy your API key from the dashboard.

## Basic Usage Example

```python theme={null}
from aisearchapi_client import AISearchAPIClient

client = AISearchAPIClient(api_key="your-api-key-here")

result = client.search(
    prompt="What is machine learning and how does it work?",
    response_type="markdown"
)

print("Answer:", result.answer)
print("Sources:", result.sources)
print(f"Total time: {result.total_time}ms")

balance = client.balance()
print(f"Available credits: {balance.available_credits}")
client.close()
```

***

# Advanced Usage

## Contextual Search

```python theme={null}
from aisearchapi_client import AISearchAPIClient, ChatMessage

with AISearchAPIClient(api_key="your-api-key-here") as client:
    result = client.search(
        prompt="What are the main advantages and disadvantages?",
        context=[
            ChatMessage(role="user", content="I am researching solar energy for my home"),
            ChatMessage(role="user", content="I live in a sunny climate with high electricity costs")
        ],
        response_type="text"
    )
    print("Contextual Answer:", result.answer)
```

## Custom Configuration

```python theme={null}
client = AISearchAPIClient(
    api_key="your-api-key-here",
    base_url="https://api.aisearchapi.io",
    timeout=60
)
```

***

# API Reference

## AISearchAPIClient

### Constructor

```python theme={null}
AISearchAPIClient(
    api_key: str,
    base_url: str = "https://api.aisearchapi.io",
    timeout: int = 30
)
```

* `api_key`: Get yours from the dashboard
* `base_url`: Optional custom endpoint
* `timeout`: Timeout in seconds

### Methods

* `search(prompt, context=None, response_type=None)` → Run an AI-powered search
* `balance()` → Check available credits

***

# Error Handling

```python theme={null}
from aisearchapi_client import AISearchAPIClient, AISearchAPIError

try:
    with AISearchAPIClient(api_key="your-api-key") as client:
        result = client.search(prompt="Your query")
        print(result.answer)
except AISearchAPIError as e:
    print(f"API Error [{e.status_code}]: {e.description}")
```

***

# Environment Variables

You can set your API key globally:

```bash theme={null}
export AI_SEARCH_API_KEY="your-api-key-here"
```

Then use it in Python:

```python theme={null}
import os
from aisearchapi_client import AISearchAPIClient

api_key = os.getenv("AI_SEARCH_API_KEY")
client = AISearchAPIClient(api_key=api_key)
```

***

# Examples

* Basic search and balance check
* Contextual search with history
* Async usage
* Error handling

Find more examples in the `examples/` folder.

***

# Requirements

* Python 3.8+
* `requests >= 2.25.0`
* `typing-extensions >= 4.0.0` (if Python \< 3.10)

***

# Development

```bash theme={null}
git clone https://github.com/aisearchapi/aisearchapi-python.git
cd aisearchapi-python
python -m venv venv
source venv/bin/activate
pip install -e ".[dev,test]"
pytest
```

***

# License

This project is licensed under the **MIT License** – see the LICENSE file.

***

# Resources

* [Get API Key – Dashboard](https://app.aisearchapi.io/dashboard)
* [Homepage](https://aisearchapi.io)
* [Issues](https://github.com/aisearchapi/aisearchapi-python/issues)
* [Blog](https://aisearchapi.io/blog)

***