Metadata-Version: 2.4
Name: plcsai
Version: 1.0.0
Summary: Official Python SDK for the PLCs.ai API — interpret PLC code from your own tools.
Author: PLCs.ai
License: Proprietary
Project-URL: Homepage, https://developer.plcs.ai
Project-URL: Documentation, https://developer.plcs.ai
Keywords: plc,automation,rockwell,siemens,ai,plcs.ai
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# plcsai — Python SDK for the PLCs.ai API

Interpret PLC code from your own tools. Official Python client for the
[PLCs.ai API](https://developer.plcs.ai). Zero third-party dependencies.

## Install

```bash
pip install plcsai
```

Requires Python 3.8+.

## Quickstart

```python
from plcsai import Client

client = Client(api_key="plck_live_…")  # or set PLCS_API_KEY

result = client.interpret(
    project_id="prj_…",
    prompt="Why is the filler at line 2 not advancing past Starting?",
)
print(result.answer)
print(result.citations)
print(result.request_id)  # quote this in a support request
```

### Streaming

```python
for event in client.interpret_stream(project_id="prj_…", prompt="…"):
    if event.type == "token":
        print(event.text, end="", flush=True)
    elif event.type == "done":
        print("\nusage:", event.usage)
```

### Conversations, analyses, ingest, embed tokens

```python
conv = client.create_conversation("prj_…", name="Line 2 stoppage")
client.send_message(conv.conversation_id, "And why now?")

job = client.start_analysis("prj_…")
done = client.wait_for_analysis(job.analysis_id)

client.ingest_project(file_path="Conveyor.L5X")

token = client.mint_embed_token("prj_…")  # read-only, for the iframe
```

## What the client handles for you

- **Auth** — sends `Authorization: Bearer …` on every request.
- **Idempotency** — auto-generates a stable `Idempotency-Key` per write (reused across retries).
- **Retries** — backs off and retries only on retryable errors, respecting `Retry-After`.
- **Streaming** — parses SSE into typed `StreamEvent`s.
- **`request_id`** — surfaced on every result.

## Errors

Non-2xx responses raise `plcsai.ApiError` with `.status_code`, `.error`,
`.user_message`, `.suggested_action`, `.is_retryable`, and `.request_id`.

## Development

```bash
pip install -e '.[dev]'
pytest
```

## Releasing (maintainers)

`plcsai` is published to PyPI. Bump `version` in `pyproject.toml`, then:

```bash
python -m build
python -m twine upload dist/*
```
