Metadata-Version: 2.4
Name: liyagent
Version: 0.2.0
Summary: Python SDK for Liyagent: agents, runs, evals, knowledge, approvals and solution templates
Author: Liyagent
License-Expression: Apache-2.0
Project-URL: Homepage, https://liyagent.com
Keywords: liyagent,ai agents,agent platform,itsm,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# Liyagent Python SDK

A small client for Liyagent's public API: agents, runs, evals, knowledge,
approvals and solution templates. It depends only on `httpx` and returns the
server's JSON as it is.

```bash
pip install liyagent          # from PyPI, once released
pip install ./sdk/python      # from this repository
```

Python 3.10+. Versioned with the package (`liyagent.__version__`); see
`CHANGELOG.md`.

## Sign in

```python
from liyagent import Client

# A service account (what a pipeline uses): exchanged for a one-hour session,
# and for a new one when it expires.
liya = Client("https://acme.liyagent.com", token="svc/ci-deployer:...")

# A person, as the console signs in.
liya = Client("https://acme.liyagent.com", username="ana", password="...")

# The machine surface (knowledge.answer): the instance API key or a client token.
liya = Client("https://acme.liyagent.com", api_key="...")
```

`LIYA_URL`, `LIYA_TOKEN` (or `TICKETIQ_TOKEN`) and `LIYA_API_KEY` are read
when the arguments are left out, as the `liya` CLI reads them.

## What it covers

| Namespace | Calls |
| --- | --- |
| `liya.agents` | `list`, `get`, `put`, `delete`, `export`, `apply` (agents as code), `ask`, `start`, `stop`, `workflows`, `run_workflow`, `workflow_run` |
| `liya.runs` | `list`, `checkpoint`, `resume` |
| `liya.evals` | `datasets`, `dataset`, `create_dataset`, `start_run`, `runs`, `run`, `compare`, `wait` |
| `liya.knowledge` | `answer`, `collections`, `articles`, `approve_article`, `reject_article` |
| `liya.approvals` | `list`, `get`, `approve`, `reject` |
| `liya.templates` | `list`, `get`, `preview`, `install` (with `params`), `installs`, `uninstall` |
| `liya.templates` (authoring, `templates.write`) | `authored`, `authored_versions`, `validate`, `draft_from_agent`, `save_draft`, `publish`, `delete_draft`, `withdraw` |

Anything else: `liya.request("GET", "/api/...")`, with the same credentials
and errors.

## Types

Request bodies are typed: `liyagent.models` holds a `TypedDict` per body
(`TemplateInstallBody`, `BundleApplyBody`, …) and `REQUEST_BODIES` maps each
operation to its body. They are generated from the server's OpenAPI document
by `sdk/scripts/generate_models.py`, and the server's test suite fails when
the committed file differs from what the document says. The package ships
`py.typed`, so mypy and pyright read them. Responses are the server's JSON
as it is.

## Your own templates

```python
doc = liya.templates.draft_from_agent("desk-helper", key="desk-answers")["template"]
doc["params"] = [{"name": "team", "label": "Escalation team", "required": True}]
doc["agent"]["instructions"] += "\nEscalate to {{ params.team }}."
assert liya.templates.validate(doc)["ok"]
liya.templates.save_draft(doc)
liya.templates.publish("desk-answers", doc["version"])
liya.templates.install("desk-answers", agent_id="desk-two", params={"team": "Network"})
```

## Errors

A refusal raises `LiyagentError` with `status`, the server's `detail` (for a
bundle or template refusal, `{message, at}`: where in the document it was)
and a `kind`: `auth` (401, sign in again), `forbidden` (403, a permission is
missing), `not_found`, `invalid` (400, 422), `conflict` (409, 412),
`unreachable` or `error`.

## Check the server

`liya.check_server()` lists the operations this SDK uses that the server
does not serve, so a pipeline can stop before it calls a route an older
release does not have. The same list (`liyagent.OPERATIONS`) is checked
against the server's OpenAPI document in the server's test suite
(`tests/unit/test_sdk_python.py`).

## Examples

- `examples/install_template.py` — preview a template, stop if any part would
  be refused, install it.
- `examples/eval_gate.py` — score an agent on its eval set and fail a build
  that is worse than the pinned baseline.
- `examples/approvals_queue.py` — work the approval queue from a terminal.

## Releasing

See `sdk/RELEASING.md`: a tag `sdk-py-vX.Y.Z` builds and publishes this
package to PyPI from GitHub Actions (`.github/workflows/sdk-release.yml`)
by trusted publishing.
