Reference
Production guide.
Reliable by default. Yours to tune.
The SDK handles paging, retries and errors for you, so your integration stays small. Here’s how each one works, and how to tune it for your service.
Configure the client
client.py
import osfrom ollive import Ollive client = Ollive() # reads OLLIVE_API_KEYclient = Ollive(api_key=os.environ["MY_OLLIVE_KEY"]) # or pass it yourselfclient = Ollive(timeout=10, max_retries=4) # tune it for your service| Option | Environment variable | Default |
|---|---|---|
api_key | OLLIVE_API_KEY | Your API key. |
base_url | OLLIVE_BASE_URL | https://api.ollive.ai/api |
timeout | – | 30 seconds |
max_retries | – | 2 |
headers | – | Extra headers sent with every request. |
httpx_client | – | Your own httpx.Client, for proxies, custom TLS or connection limits. |
The client keeps a pool of connections, so create one and reuse it for the life of your process:
lifecycle.py
with Ollive() as client: ... # or keep one client for the life of your processclient = Ollive()...client.close()Need proxies, custom TLS or more connections? Bring your own httpx.Client:
custom_http.py
import httpxfrom ollive import Ollive client = Ollive(httpx_client=httpx.Client(timeout=20, limits=httpx.Limits(max_connections=50)))Async
AsyncOllive has every method Ollive has, each one awaited. It fits straight into FastAPI, aiohttp or any asyncio service.
async_client.py
import asynciofrom ollive import AsyncOllive async def main() -> None: async with AsyncOllive() as client: async for agent in await client.agents.list(): print(agent.name) asyncio.run(main())Pagination
List methods return an iterator that fetches the next page as you loop, so you never handle a cursor. Ask for include_total when you want the count across every page, for a heading or a progress bar.
every_run.py
runs = client.runs.list(limit=100, include_total=True)print(runs.response.total_count, "runs in total") for run in runs: # every run, across every page print(run.run_id, run.not_met_count)Paging through results yourself, for an infinite scroll in your UI? Pass each response’s next_cursor back as cursor.
Retries and timeouts
Every call only reads, so it’s always safe to send again. The SDK retries dropped connections, timeouts, rate limits and server errors twice, waiting the time Ollive asks for in Retry-After or backing off from about half a second. Requests time out after 30 seconds. Change either for the whole client, or for one call:
tuning.py
client = Ollive(max_retries=4) # every requestclient.runs.list(request_options={"max_retries": 0}) # just this one client = Ollive(timeout=10) # every requestclient.runs.list(request_options={"timeout": 60}) # just this oneRate limits apply to each API key on its own, so give each service its own key and one busy job never slows another.
Errors
Everything the SDK raises comes from one family, ollive.OlliveError, so one except can catch it all, and the specific ones are there when you need them.
Exceptions
OlliveError├── ApiError The API answered with an error status│ ├── BadRequestError 400│ ├── UnauthorizedError 401│ ├── ForbiddenError 403│ ├── NotFoundError 404│ ├── TooManyRequestsError 429│ └── InternalServerError 500└── ApiConnectionError Ollive couldn’t be reached └── ApiTimeoutError The request timed outAn ApiError carries status_code, a stable code to branch on, a message for people, the param at fault, and the request_id to send support.
errors.py
import loggingimport ollive log = logging.getLogger(__name__) try: run = client.runs.get(run_id)except ollive.NotFoundError: run = Noneexcept ollive.ApiError as e: log.warning("Ollive said %s: %s (request %s)", e.code, e.message, e.request_id)except ollive.ApiConnectionError: log.warning("Ollive couldn’t be reached; we’ll try again on the next sync")| Status | Exception | What to do |
|---|---|---|
| 400 | BadRequestError | A parameter needs to change. e.param names it. |
| 401 | UnauthorizedError | The key is missing, expired or revoked. |
| 403 | ForbiddenError | The key isn’t tied to a workspace. |
| 404 | NotFoundError | get found nothing with that ID. |
| 429 | TooManyRequestsError | Retried for you. Raised if the wait is long, so your code decides when to try again. |
| 5xx | InternalServerError | Retried for you. If it persists, send support the request_id. |
Every code is listed on Errors.
Logging
Turn logging on with a level, and lines go to the standard Python logger named ollive, with your key redacted.
logging.py
client = Ollive(logging={"level": "debug"})Versions and upgrades
The SDK follows semantic versioning. It accepts fields and values Ollive adds later, so a new Ollive release never breaks the version you’ve installed, and you upgrade on your own schedule. The current version is 0.1.0. Pin a compatible range in your requirements:
requirements.txt
ollive>=0.1,<0.2Each release is announced on the changelog.