Metadata-Version: 2.4
Name: cortiqa
Version: 0.1.0
Summary: Official Python client library for Cortiqa AI & Falin Foundation Models
Author-email: Cortiqa AI Team <team@cortiqa.co>
License: MIT
Project-URL: Homepage, https://cortiqa.co
Project-URL: Documentation, https://github.com/cortiqa-ai/cortiqa-docs
Project-URL: Repository, https://github.com/cortiqa-ai/cortiqa-sdk-python
Project-URL: Bug Tracker, https://github.com/cortiqa-ai/cortiqa-sdk-python/issues
Keywords: cortiqa,ai,llm,falin,agents,machine-learning,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Cortiqa AI Python SDK

[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/cortiqa/)
[![Python Versions](https://img.shields.io/badge/python-3.8%2B-brightgreen.svg)](https://pypi.org/project/cortiqa/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Python client library for **Cortiqa AI** and **Falin Foundation Models**. Built for enterprise scalability, agentic workflows, and ultra-fast inference.

---

## ⚡ Installation

```bash
pip install cortiqa
```

Or install with development dependencies:

```bash
pip install "cortiqa[dev]"
```

---

## 🚀 Quickstart

Set your API key as an environment variable:

```bash
export CORTIQA_API_KEY="sk-cortiqa-your-api-key"
```

Then create your first completion:

```python
from cortiqa import Cortiqa

client = Cortiqa()

response = client.chat.completions.create(
    model="falin-01",
    messages=[
        {"role": "system", "content": "You are a helpful assistant by Cortiqa."},
        {"role": "user", "content": "Explain quantum computing in two sentences."}
    ],
    temperature=0.7,
)

print(response.choices[0].message.content)
```

---

## 🌊 Real-Time Streaming

Stream tokens in real-time as they are generated by the model:

```python
from cortiqa import Cortiqa
import sys

client = Cortiqa()

stream = client.chat.completions.create(
    model="falin-01",
    messages=[
        {"role": "user", "content": "Write a short poem about sunrise in the Himalayas."}
    ],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        sys.stdout.write(chunk.choices[0].delta.content)
        sys.stdout.flush()
```

---

## ⚡ Asynchronous Support

High-concurrency async client using `AsyncCortiqa`:

```python
import asyncio
from cortiqa import AsyncCortiqa

async def main():
    async with AsyncCortiqa() as client:
        response = await client.chat.completions.create(
            model="falin-pro",
            messages=[
                {"role": "user", "content": "Write a fast Go concurrent worker pool."}
            ]
        )
        print(response.choices[0].message.content)

asyncio.run(main())
```

---

## 🧠 Available Cortiqa Models

| Model ID | Provider | Description | Tier |
|---|---|---|---|
| `falin-01` | Cortiqa | Flagship foundation model for fast reasoning & conversational AI | Free / Starter |
| `falin-pro` | Cortiqa | Advanced model for complex coding, mathematical proofs, and system design | Pro |
| `falin-vision` | Cortiqa | Multimodal vision, OCR, document perception, and image reasoning | Free |
| `falin-ultra` | Cortiqa | Maximum reasoning capability for deep research and enterprise automation | Enterprise |

To query live models directly:

```python
models = client.models.list()
for m in models:
    print(m.id, "-", m.description)
```

---

## ⚙️ Configuration & Options

```python
client = Cortiqa(
    api_key="sk-cortiqa-...",                # Default: CORTIQA_API_KEY
    base_url="https://api.cortiqa.co",       # Default: https://api.cortiqa.co
    timeout=60.0,                            # Request timeout in seconds
    max_retries=2,                           # Auto-retries on transient failuress
)
```

---

## 🛡️ Error Handling

The SDK provides typed exceptions for predictable error handling:

```python
from cortiqa import Cortiqa
from cortiqa.exceptions import AuthenticationError, RateLimitError, APIError

client = Cortiqa()

try:
    response = client.chat.completions.create(
        model="falin-01",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except AuthenticationError:
    print("Invalid API Key! Check your sk-cortiqa key.")
except RateLimitError:
    print("Rate limit reached! Please slow down requests.")
except APIError as e:
    print(f"API failed with status {e.status_code}: {e.message}")
```

---

## 📄 License

MIT © [Cortiqa AI](https://cortiqa.co)
