pine-assistant

Pine AI SDK for Python. Let Pine AI handle your digital chores.

Install

pip install pine-assistant          # SDK only
pip install pine-assistant[cli]     # SDK + CLI

Instinct and other agents

Follow Set up Pine in Instinct to connect with a user token and the Pine skill. The skill prefers Socket.IO when available and uses REST in HTTP-only environments; Python is not required.

Quick Start (Async)

from pine_assistant import AsyncPineAI

client = AsyncPineAI(access_token="...", user_id="...")
async with client:
    await client.connect()

    session = await client.sessions.create()
    await client.join_session(session["id"])
    await client.rebuild(session["id"])          # load the session's messages

    async for event in client.chat(session["id"], "Negotiate my Comcast bill",
                                   turn_timeout=120):
        print(event.type, event.data)

A client tracks one session. Concurrent sessions need one client each.

disconnect() only ends the real-time connection. aclose() (including the end of async with) also releases the SDK-owned HTTP client. If you pass an httpx.AsyncClient, it remains your responsibility to close it. Use api_base_path to select an API prefix; it defaults to /api for compatibility.

REST identity and sessions

async with AsyncPineAI(access_token="...") as client:
    identity = await client.auth.me()               # AuthIdentity(user_id="...")
    sessions = await client.sessions.list(limit=20) # SessionListResponse
    session = await client.sessions.get("123")     # SessionInfo

The list call sends ensure_copilot=false by default. It is read-only when used with a backend that supports this query option; older backends may ignore it and retain their legacy Copilot behavior.

Use await client.sessions.end_task(session_id) to request a user-ended task; the synchronous client provides the same method without await. The backend checks ownership and eligibility, and the method returns the updated SessionInfo. This is not proof that the task objective succeeded or that an external action has already stopped. The SDK never retries this write: after a timeout or server error, query the session and its history before deciding whether to retry, because the state may already have changed.

Use sessions.send_message() when an application needs the REST write acknowledgement without joining Socket.IO. It returns a typed status: received means the message was persisted, delivered means it was handed to the Agent, and delivery_failed means that handoff failed. None means that a task has finished. A timeout or connection error leaves persistence unknown, so the SDK never retries a send; recover Socket history before deciding what to do next.

status = await client.sessions.send_message(
    "123", "Continue the task", request_id="ui-click-42",
)
if status.status == "delivered":
    print(status.message_id, status.revision)

outcomes = await client.sessions.outcomes("123")
for outcome in outcomes.items:
    print(outcome.outcome_id, outcome.outcome_narrative)

outcomes() returns newest-first persisted Outcomes. Follow next_cursor to request older pages with before=...; total is a first-page snapshot and is not a pagination signal.

For structured form answers, use the async method on a connected client:

await client.connect()
try:
    receipt = await client.submit_form_response(
        "123", "456", {"contact_name": "Example User"},
    )
finally:
    await client.disconnect()

The method re-reads the original agent form from authenticated history, preserves its message and request IDs, validates visible required fields, and JSON-encodes array answers like the web app. Callers cannot override field privacy levels. The backend's session:message_status receipt supplies the persisted reply ID: delivered means it reached the agent and received means it was persisted but delivery was not observed before the deadline. unknown requires checking history before deciding whether to submit again. Each Socket.IO connection sends a form only once because a late receipt cannot identify an attempt; reconnects never retry or replay form submissions. A transport ACK is not a delivery receipt. The legacy synchronous send_form_response() is deprecated because it cannot verify the original form request.

Platform API for partners

A partner is a business that builds on Pine through the Platform API. It holds a secret key, pine_sk_live_.... Keep it on your servers: read it from an environment variable or secret store, and never ship it in browser, mobile or other client-side code, prompts, or logs. To get a key, contact [email protected]. Each end user of your product becomes a managed user, identified by your own external_id (1-128 of letters, digits, ., _, :, |, -, not starting with .; no personal data).

All managed users of one partner use that partner's credits. A partner can limit the total credits that its managed users use.

The SDK methods for managed users are listed in docs/sdk-api.md. If you do not use Python, see the HTTP API in docs/http-api.md and the Socket.IO reference in docs/socketio.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗