Client

cpsl.Client is the lightweight Python client for talking to deployed Capsule apps from outside the app runtime. You will usually reach for it when the app already exists and you want to talk to it from somewhere else, such as a smoke test, admin script, or another Python service. It is useful for:

deploy smoke tests
scripts and admin tools
cron jobs
other Python services that want to call a Capsule app

Worked example

The most common use is a deploy smoke test for a real app:

import cpsl

client = cpsl.Client()

first = client.chat(
    "support-ops",
    "How many threads are waiting for review right now?",
)
second = client.chat(
    "support-ops",
    "Turn that into a two-step triage plan.",
    session_id=first.session_id,
)

assert first.text.strip()
assert second.text.strip()
assert first.session_id == second.session_id

That pattern is useful because it exercises both the app’s answer quality and its session continuity after a deploy.

Setup

The client authenticates from capsule login by default:

import cpsl

client = cpsl.Client()

You can also pass a token manually:

client = cpsl.Client(token="...")

If you have already run capsule login, the zero-argument form is usually all you need.

App lookup methods

Method	Purpose
`list_apps()`	List apps in the workspace
`get_app(name_or_id)`	Get metadata for one app
`create_checkout(app, return_url="")`	Create a checkout URL
`list_payments(app)`	List payments for an app
`get_earnings(app)`	Get earnings summary

Chat methods

`chat(app, text, session_id=None)`

Send a message and wait for the full response.

reply = client.chat("support-ops", "How many support threads are waiting for review right now?")
print(reply.text)

If you are writing a quick post-deploy smoke test, this is usually the most convenient entry point. Returns ChatResponse with:

text
session_id
request_id
raw

`stream(app, text, session_id=None)`

Stream a response via SSE:

for chunk in client.stream("support-ops", "Summarize the riskiest support threads."):
    print(chunk.text, end="")

This is handy when you want your script to show progress instead of waiting for the entire response. Each StreamChunk exposes:

event
data
text convenience property
done convenience property

Session continuity

Pass session_id if you want multiple client calls to continue the same conversation:

first = client.chat(
    "support-ops",
    "How many threads are waiting for review, and which queue looks busiest?",
)
second = client.chat(
    "support-ops",
    "Turn that into a two-step triage plan.",
    session_id=first.session_id,
)

Without session_id, each call starts a fresh conversation.

Typical use

Example smoke test:

import cpsl

client = cpsl.Client()
reply = client.chat("support-ops", "Give me a one-sentence triage plan for the current support queue.")

assert reply.text.strip()
assert reply.session_id
print("smoke test passed")

Python App API

CLI

Worked example

Setup

App lookup methods

Chat methods

`chat(app, text, session_id=None)`

`stream(app, text, session_id=None)`

Session continuity

Typical use

See also

​Worked example

​Setup

​App lookup methods

​Chat methods

​chat(app, text, session_id=None)

​stream(app, text, session_id=None)

​Session continuity

​Typical use

​See also

Worked example

Setup

App lookup methods

Chat methods

`chat(app, text, session_id=None)`

`stream(app, text, session_id=None)`

Session continuity

Typical use

See also