plcsai 1.0.0

Official Python SDK for the PLCs.ai API — interpret PLC code from your own tools.

plcsai — Python SDK for the PLCs.ai API

Interpret PLC code from your own tools. Official Python client for the PLCs.ai API. Zero third-party dependencies.

Install

pip install plcsai

Requires Python 3.8+.

Quickstart

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

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

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 StreamEvents.
• 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

pip install -e '.[dev]'
pytest

Releasing (maintainers)

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

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