Metadata-Version: 2.4
Name: specific-ai
Version: 0.3.0
Summary: specific.ai python sdk
Home-page: https://specific.ai/
Author: specific.ai team
Author-email: support@specific.ai
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: openai
Requires-Dist: pydantic
Requires-Dist: anthropic
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

# Specific AI Python SDK

This SDK supports two main workflows:

* **Platform automation**: manage Tasks, Assets (datasets/benchmarks), Trainings, and Models
* **Inference**: run inference on deployed Specific AI models

For copy‑paste‑ready deep dives, see `optune-sdk/examples/platform/`.

## Installation

```bash
pip install specific-ai
```

## Authentication & configuration

Set these environment variables:

* `SPECIFIC_AI_API_KEY`: API key / bearer token for the platform backend
* `SPECIFIC_AI_BASE_URL`: platform backend base URL (default in examples: `https://platform.specific.ai/`)

Optional:

* `SPECIFIC_AI_TASK_ID`: current task id. You can create a new task or see the current task\_id in the platform url. for example - the following url: https://platform.specific.ai/model-setup?usecaseId=68bedd42667aca8d3086e536 the task\_id is '68bedd42667aca8d3086e536'
* `SPECIFIC_AI_TASK_TYPE`: task type string (e.g. `ClassificationResponse`)

## 5-line quickstart (platform)

```python
import os
from specific_ai import SpecificAIClient

client = SpecificAIClient(base_url=os.getenv("SPECIFIC_AI_BASE_URL", "http://localhost:8000"), api_key=os.environ["SPECIFIC_AI_API_KEY"])
task_id = client.tasks.list()[0].iter_tasks()[0].task_id
print(client.models.get_metrics(task_id=task_id).versions)
```

## Which URL goes where

`SpecificAIClient` takes three different URLs. They are not interchangeable:

| Argument | Points at | Used for |
| --- | --- | --- |
| `base_url` | The platform **API** base, e.g. `https://platform.specific.ai/api` | Tasks, assets, trainings, models |
| `url` | The SpecificAI **gateway** root, e.g. `https://platform.specific.ai` | Inference through the gateway, plus tracing and logging |
| `inference_url` | A **Triton** server you can reach directly, e.g. `http://triton:8000` | Inference only, bypassing the gateway |

### `inference_url` vs `url`

* `url` — for the SpecificAI gateway. The SDK derives the Triton path for you.
  On the SpecificAI-hosted platform that path names the workspace the model was
  deployed from, so that two customers deploying the same project and task name
  still get one URL each; the SDK asks the platform for it on its first
  inference (`GET {url}/public/api/inference_path`, authenticated with your API
  key) and keeps the answer. **You never handle a workspace id**, and against a
  self-hosted install nothing changes: inference goes to
  `{url}/public/triton/v2/models/...` exactly as before.
* `inference_url` — for **direct** Triton connections only. When set it is used
  verbatim as the Triton base, so inference goes to
  `{inference_url}/v2/models/...`. **Never point it at the gateway**: the extra
  `/public/triton` hop would be missing and every request would 404.

```python
from specific_ai import SpecificAIClient

# Through the gateway — the SDK derives the Triton path for you.
client = SpecificAIClient(url="https://platform.specific.ai", api_key="sk-...")

# Straight to a Triton you can reach (in-cluster, port-forward, local Docker).
client = SpecificAIClient(inference_url="http://triton:8000")
```

`inference_url` is client-side configuration: it changes which host the SDK
calls and nothing else. Tracing and logging always go through the gateway, so
`trace=True` and the `log_*` methods require `url` — an `inference_url`-only
client raises `ValueError` if you ask it to log.

Both modes can be combined with `base_url` in one client when you need platform
automation and inference from the same object.

`inference_url` requires **`specific-ai >= 0.3.0`**. Released 0.2.0 does not
accept the argument; see [CHANGELOG.md](CHANGELOG.md).

## Inference & logging

Initialize with `url` (your SpecificAI platform URL) for inference and logging:

```python
from specific_ai import SpecificAIClient

client = SpecificAIClient(url="<your-specific-ai-service-URL>")

# Run inference on a deployed SpecificAI model:
response = client.create(message="...", task_name="my-task", project_name="my-project")

# Log an interaction from an external (non-SpecificAI) model into the platform.
# Use the task-specific helpers so the usecase is created with the correct task
# type. The record is added to an existing Task or used to bootstrap a new one
# with the same task_name and project_name.
client.log_classification(example="...", task_name="my-task", labels=["Positive"], is_multilabel=False)
client.log_summarization(example="...", task_name="my-summary-task", summary="...")
client.log_entity_recognition(example="...", task_name="my-ner-task", entities=[{"label": "PERSON", "content": "Ada", "start_index": 0}])

# Omit the response to log only the example (for later labeling):
client.log_classification(example="...", task_name="my-task")
```

See `optune-sdk/examples/specific_ai_basic_usage.py` and `optune-sdk/examples/specific_ai_log_usage.py`.

## Deep dive examples

Located in `optune-sdk/examples/platform/`:

* `01_task_management.py`
* `02_asset_management.py`
* `03_training_workflows.py`
* `04_model_deployment.py`

## Support

Contact `support@specific.ai`.
