# artasupport Python SDK

`artasupport` is a Python SDK for ArtaSupport TSE APIs (`copilot` and `batch`).

## Requirements

- Python `3.10+`
- An API key (`arta_live_...`)
- Backend base URL (`https://artasupport.com` or for local testing `http://localhost:8000`)

## Install

```bash
pip install artasupport
```

Local development install:

```bash
pip install -e .
```

## Environment setup

```bash
export ARTASUPPORT_API_KEY="arta_live_..."
export ARTASUPPORT_BASE_URL="http://localhost:8000"
```

You can also pass `api_key=` and `base_url=` directly in code.

## How it works

Each SDK call:
1. Builds auth headers (`x-api-key` + Bearer)
2. Sends request to backend (`/api/tse`, `/v1/models`, `/v1/sessions`, `/api/ingest`)
3. Parses typed response (`text`, `session_id`, `usage`, `next_steps`, etc.)
4. Raises typed exceptions for API/network/config errors

## Usage mode 1: Quick one-shot calls

Use top-level helper functions for simple scripts.

```python
from artasupport import tse_copilot, tse_batch

response = tse_copilot(user_input="my machine is slow")
print(response.text)

response = tse_batch(user_input="cannot connect to the Internet")
print(response.text)
```

## Usage mode 2: Sync conversation with context

Use `ArtaSupportMessage` when you want multi-turn chat.
Conversation context is tied to `session_id`.

```python
from artasupport import ArtaSupportMessage

with ArtaSupportMessage() as client:
    sid = client.create_session().session_id

    response_1 = client.tse_copilot(user_input="internet is slow", session_id=sid)
    response_2 = client.tse_copilot(user_input="only my laptop at home is affected", session_id=sid)

    print(response_1.text)
    print(response_2.text)

    # optional cleanup
    client.delete_session(sid)
```

## Usage mode 3: Async conversation

Use `AsyncArtaSupportMessage` in async apps.

```python
import asyncio
from artasupport import AsyncArtaSupportMessage

async def main():
    async with AsyncArtaSupportMessage() as client:
        sid = (await client.create_session()).session_id
        response = await client.tse_batch(user_input="summarize issue", session_id=sid)
        print(response.text)

asyncio.run(main())
```

`AsyncArtaSupportMessage` is non-blocking async I/O, not token streaming.

## Usage mode 4: File ingestion

Upload PDF or Excel files for runbook extraction and cases ingestion.

```python
from artasupport import tse_ingest

# Quick one-shot upload
response = tse_ingest("doc.pdf")
print(response.status)  # "completed" or "processing"

# With explicit client
from artasupport import ArtaSupportMessage

with ArtaSupportMessage() as client:
    response = client.tse_ingest("doc.xlsx")
    print(f"Ingestion {response.status}")
```

Async version:

```python
import asyncio
from artasupport import AsyncArtaSupportMessage

async def upload_file():
    async with AsyncArtaSupportMessage() as client:
        response = await client.tse_ingest("doc.pdf")
        print(f"Status: {response.status}")

asyncio.run(upload_file())
```

Supported file types: `.pdf`, `.xlsx`, `.xls`, '.txt'. Files can contain embedded images.
Folders are not supported; `tse_ingest(...)` expects a single file path.

## Input styles

For `tse_copilot(...)` and `tse_batch(...)`, provide exactly one of:
- `user_input="..."`
- `messages=[{"role": "user", "content": "..."}]`

## Error handling

```python
from artasupport import (
    ArtaSupportMessage,
    APIError,
    AuthenticationError,
    RateLimitError,
)

try:
    with ArtaSupportMessage() as client:
        response = client.tse_copilot(user_input="help", session_id="sess_...")
except AuthenticationError as exc:
    print("Invalid/revoked API key:", exc)
except RateLimitError as exc:
    print("Rate limited:", exc)
except APIError as exc:
    print("API failure:", exc.status_code, exc.request_id, exc.message)
```

## API surface

- Top-level helpers:
  - `tse_copilot(...)`
  - `tse_batch(...)`
  - `tse_ingest(file_path)`
- Sync client:
  - `ArtaSupportMessage`
  - `list_models()`, `create_session()`, `delete_session()`
  - `tse_copilot(...)`, `tse_batch(...)`, `tse_ingest(file_path)`
- Async client:
  - `AsyncArtaSupportMessage`
  - `await list_models()`, `await create_session()`, `await delete_session()`
  - `await tse_copilot(...)`, `await tse_batch(...)`, `await tse_ingest(file_path)`
