Metadata-Version: 2.5
Name: omnixon-lib
Version: 3.0.0
Summary: A small enterprise chatbot library
Project-URL: Homepage, https://github.com/lixelv/pypi-package-template
Project-URL: Issues, https://github.com/lixelv/pypi-package-template
Author-email: lixelv <simeongfremenko@gmail.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# Omnixon Python Client

## Overview

This document provides instructions for the Python client used to connect to the Omnixon web service. The Omnixon service receives text requests, processes them through artificial intelligence programs, and returns text responses.

## Connection and Setup

To use the client, you must provide an access token and the base web address. Every request requires this access token, which is placed in the request headers automatically by the client.

The client verifies the connection upon creation. It returns a 403 error if the token is incorrect. It returns a connection error if the web address is incorrect.

## Client Functions

The client provides the following functions to interact with the service:

* `send_message(user_id, message, attachments=None, trace=False, chat_id=None)`: Sends a user text request to the service and returns a generated answer. This function has a 120-second timeout. What is stored and what the model is given are decided by the agent's **blocks** (see below), not by the request.
  * `user_id` may be `None` or an empty string. The service then creates a new user for your agent and returns it as `response.user`; keep `response.user.external_id` to continue the conversation. An agent without the Users block is stateless: `response.user` and `response.chat_id` are `None`.
  * `attachments` is a list of files for the model: images, PDFs, text, audio, video. Build them with `Attachment.from_file(path)`, `Attachment.from_bytes(data, "image/png")` or `Attachment.from_url(url)`. The model must be able to handle them (for images it must see); a model that cannot gives `UpstreamError`. The history keeps only a note that a file was there, never the file.
* `send_message_stream(user_id, message, attachments=None)`: Like `send_message`, but an asynchronous generator that yields the answer in text chunks while it is being generated (`async for chunk in client.send_message_stream(...)`). It raises `StreamError` if the service fails midway, and is not retried automatically.
* `stream_message(user_id, message, attachments=None)`: The same stream as an object. Iterate it for the chunks; its `user` attribute holds the user (also a newly created one) as soon as the service sends it, before the first chunk (`None` for a stateless agent).
* `get_history(user_id)`: Returns a list of saved text records for a specific user.
* `clear_history(user_id)`: Deletes all saved text records for a specific user.
* `get_user(user_id)`: Retrieves stored information for a specific user. It returns nothing if the user is not found.
* `create_user(user_id)`: Adds a new user to the database.
* `update_user(user_id, new_user_id)`: Modifies existing information for a user, such as their identification number.
* `delete_user(user_id)`: Removes a user from the database.

Administrative functions (admin token required):

* Chats: a user has several conversations, each its own thread of messages (what the agent remembers about the user is shared). `get_chats(user_id)` (the latest first), `create_chat(user_id, title=None)` (no title: named after the first message), `get_chat`, `rename_chat(user_id, chat_id, title)`, `delete_chat` (with its messages), `get_chat_history(user_id, chat_id)`, `clear_chat_history`. `send_message`, `stream_message` and `send_message_stream` take `chat_id=`; `MessageResponse.chat_id` says where it was written. Without `chat_id` a message goes to the user's default chat, so code that knows nothing about chats works as before; `get_history` / `clear_history` are that chat's.
* Interrupting: `interrupt(user_id)` stops the answer that is being streamed to that user and returns `Interrupted(interrupted, text)`. The stream ends cleanly (`MessageStream.interrupted` is `True`), what had been said goes to the history (marked `interrupted`). A new request of the same user does the same by itself. Streams can only be reached in the service process that runs them.
* Client tools: `@client.tool` offers a function of yours to the model with every message (the agent needs the Client tools block; without it `Conflict`):

  ```python
  client = Client(token, base_url)

  @client.tool
  async def get_order(order_id: int) -> dict:
      """Order status by its id."""
      return {"status": "shipped"}

  answer = await client.send_message(None, "Where is order 42?")
  ```

  The schema comes from the signature (pydantic types) and the first paragraph of the docstring (`@client.tool(name="...", description="...")` overrides). Sync functions run in a thread, async ones are awaited; calls of one turn run at the same time. When the model calls one, the library runs it and gives the model what it returned; an exception, or arguments that do not fit, reach the model as the tool's failure and the answer goes on. `client.tools` lists the tools, `client.remove_tool(name)` drops one. `@client.tool(record="hidden")` says how calls of the function are kept in the history of the chat: `"full"` (the model is given the arguments and the result back), `"hidden"` (it is told only that the call happened; it reads the rest with the agent's Get tool call block) or `"off"` (not kept); unset, the agent's Client tools block decides.
* Tool calls in the history: an answer of an agent that keeps them has `message.tool_calls` (a list of `ToolCall`: `id` like `"12.1"`, `name`, `arguments`, `result`, `mode`, `failed`); `Defaults.tool_call_args_limit` / `tool_call_result_limit` (settings, 4000 characters each) cut what is kept. Every message call (`send_message`, `stream_message`, `send_message_stream`) reads the service's stream under the hood (that is how the model can ask for your functions), `send_message` joins it: a failure after the service began to answer is `StreamError`, a refusal before it (`RateLimited`, `Conflict`, `NoAccess`, ...) is the same exception as ever.
* Agents: `get_agents()`, `create_agent(name, model_id=None, blocks=None, comment=None, model_ids=None, decision_model_id=None)` (no model: the chat model of the settings; no blocks: the service's default ones), `get_self_agent()`, `get_agent(agent_id)`, `update_agent(agent_id, name=None, model_id=None, blocks=None, comment=None, expected_version=None, model_ids=None, decision_model_id=...)`, `delete_agent(agent_id)`. An agent answers with a list of chat models (`Agent.model_ids`, 1-10): with more than one, a decision model (`decision_model_id`, `None`: the settings' one) picks the model of each request by its description, and when the provider refuses before any text the next one answers; the trace has a step of `kind="decision"` (`TraceStep.decision`: each model with its probability and outcome).
* Models: `create_model(name="", request_json=..., base_url=None, use_proxy=True, api_token=None, kind="chat", description="")` — `kind` is `chat`, `embedding` or `decision` (TypeSafe Jev: picks, scores, says how likely); an empty description of an OpenRouter model is filled by the service from OpenRouter's list (its input modalities first). `update_model(..., description=None)`. The settings name three default models: `default_chat_model_id`, `default_embedding_model_id`, `default_decision_model_id`.
* Models called directly (OpenAI-compatible endpoint, observer / admin / owner tokens; the model name is the id of the record): `chat_completion(model_id, messages, **options)`, `embed(model_id, texts, dimensions=None)`, `decide(model_id, state, questions)`. Any OpenAI SDK works too: `base_url=<omnixon>/api/v1/openai`, the token as the key.
* Roles: `regular`, `user`, `admin`, `owner`, and `observer` (sees everything, runs any agent, changes nothing; made by admin and owner).
* Models: `get_models(kind=None)`, `create_model(name="", request_json=..., base_url=None, use_proxy=True, api_token=None, kind="chat")`, `get_model(model_id)`, `update_model(model_id, request_json=None, name=None, base_url=None, use_proxy=None, api_token=None)`, `delete_model(model_id)`. `base_url` points a model at another OpenAI-compatible server (default: OpenRouter), `use_proxy=False` calls it without the service's proxy, `api_token` is the key for that server (default: the key of the service; it is never returned, `Model.has_api_token` says whether there is one; `""` in `update_model` clears `base_url` / `api_token`). A model is an OpenRouter request body that must contain a `"model"` name, for example `{"model": "openai/gpt-4o-mini", "provider": {"order": ["openai"]}}`. A model has a `kind`: `chat` (what an agent answers with) or `embedding` (what makes texts searchable: `create_model("Small", {"model": "openai/text-embedding-3-small", "dimensions": 1536}, kind="embedding")`; the service tries it first and refuses one that cannot be reached or gives another size with `InvalidRequest`; it may live on another server with `base_url`, and is never an agent's model).
* MCP servers: `get_mcp_servers()`, `create_mcp_server(name, config, agent_id=None)`, `get_mcp_server(id)`, `update_mcp_server(id, config=None, name=None)`, `delete_mcp_server(id)`. The config needs a `"url"` and an optional `"transport"` (`"streamable_http"` by default, or `"sse"`).
* Blocks: an agent is made of blocks, each one capability with its own options; its presence means "on". A block is `Block(type="history", limit=3)`: a type and the options of that type as attributes (an option that is not set reads as `None`: the service's setting decides). `get_blocks()` is the catalog the service gives (`BlockType`: title, `requires`, `min_role`, `default`, the JSON `schema_` of the options): which types there are, what each needs and which options it has; the library lists none of them, so a type the service adds later works at once. `update_agent(blocks=...)` sends the WHOLE list: what is not in it is removed. Make the list from the agent you read: `agent.with_block(Block(type="history", limit=3))` (replaces or adds it; `many=True` for a type that may be there more than once, such as `mcp`), `agent.without_blocks("rag")`; `agent.block("history")` reads one. A broken list (a block without what it needs, a type twice) raises `InvalidRequest`; a block your role may not change raises `NoAccess`. Options left unset take the service's settings: `get_settings()` and `update_settings(default_rate_limit_per_minute=20, ...)` (admin). The settings also name the embedding model of every store that names none (`default_embedding_model_id`, a model of kind `embedding`). They also name the provider models are called at: `default_provider` (an OpenAI-compatible address, OpenRouter's unless changed) and its key `provider_token` (never returned: `has_provider_token` and `provider_token_source`, `settings` or `env`, say whether one is known; `""` goes back to the environment's value). A model whose `base_url` is `None` follows that provider, whichever it is at the time of the call. Another model makes those embeddings again in the background; `get_embedding_status()` (admin) says the model (`model_id`, `model`), the size and how many are left (`pending` of `total`, and `stores`: the same for `rag`, `memory` and `memfs`). The knowledge base (`rag`), the memory (`memory`) and the files (`memfs`) each have an option `embedding_model_id`: that store is made with that model, with a vector size of its own, and only it is made again when the model changes (`Block(type="rag", embedding_model_id=5)`). Searches of the knowledge base, the memory and the files are hybrid (BM25 over Russian and English words and the nearest vectors, fused by reciprocal rank); `RAG.score` and `RAG.matched` (`bm25`, `vector` or `both`) say how an entry of a search was found. A `rag` block with `writable=True` lets the agent add, change and delete entries.
* Connections between agents and MCP tools of an agent are blocks too: an `agent_calls` block lists the agents it may ask (`connections=[{"agent_id": 2}]`; it gets the tools `list_agents` and `ask_agent`), an `mcp` block gives it the tools of a server (`get_agent_mcp_servers(agent_id)` lists them; `create_mcp_server(name, config, agent_id=...)` makes a server and adds its block at once, which needs the Tools block).
* Agent versions: every change of an agent (its blocks, model, even an edit of the model or MCP server record it uses) is a numbered version. `get_agent_versions(agent_id)` (newest first), `get_agent_version(agent_id, number)`, `diff_agent_versions(agent_id, number, to=None)` (what changed, `to` defaults to the latest) and `rollback_agent(agent_id, to, comment=None)` (the agent becomes what that version was; recorded as a new version, nothing is lost). `update_agent(..., expected_version=n)` refuses with `Conflict` if the agent has moved on since version `n`, so two people do not overwrite each other. A message knows the version that produced it (`Message.agent_version`).
* Evals of versions: `run_eval(agent_id, versions, judge_model_id, dataset, criteria=None)` runs up to 5 versions over a dataset of conversations in the background and has the judge (a decision model; `judge_model_id=None`: the settings' one) score every answer 0-100 against the one expected (how likely the answer says what the expected one says, x 100); the dataset is people -> chats -> messages, `[[[{"role": "user", "content": ...}, {"role": "assistant", "content": <expected>}, ...]]]`. `wait_eval(agent_id, run_id, poll=2.0, timeout=None)` waits until it is done (`TimeoutError` past `timeout`), `get_evals(agent_id)`, `get_eval(agent_id, run_id)` (`EvalRun.scores`: per version the mean score, how many were scored and how many failed; `key_sources`: whose API key each version's model used), `get_eval_results(agent_id, run_id, version=None)` (`EvalResult`: question, expected, answer, score, reason, error), `delete_eval(agent_id, run_id)` (stops a running one).
* Memory (Letta's three tiers; the block `memory`, whose parts are its flags `core`, `recall`, `archival`, with the options of each: `core_blocks`, `recall_limit`, `archival_limit`, `summarize`, ...): `get_memory_users(agent_id=None, query=None)` (the people that have something in memory); core blocks (text the agent keeps in front of every message and edits itself): `get_core_memory(user_id=None, agent_id=None)`, `set_core_memory(label, value, user_id=None, agent_id=None)`, `delete_core_memory(label, ...)`; archival passages: `search_archival(user_id, query=None, limit=10, offset=0, agent_id=None)` (the newest, or the best match by words and meaning), `add_archival(user_id, content, agent_id=None)`, `add_archival_many(user_id, contents, agent_id=None)` (up to 1024, all or none), `update_archival(passage_id, content)`, `delete_archival(passage_id)`; the conversation: `search_recall(user_id, query=None, role=None, since=None, until=None, limit=None, agent_id=None, offset=None)` (with a query: a search, 20 hits unless `limit`; without one: every message, the newest first, 50 a page after `offset`). A summary kept by the service (Archival's `summarize`) is listed by `get_core_memory` as the read-only block `summary`. What leaves the History window is saved as archival passages (`source == "history"`).
* Files (MemFS, the block `memfs` with the flags `agent_files` and `person_files` (and `agent_files_writable`, `person_files_writable`)): a tree of the agent and one for each person, every change a revision: `get_memfs_users(agent_id=None)`, `memfs_tree(user_id=None, agent_id=None)` (no `user_id`: the tree of the agent), `memfs_read(path, user_id=None, revision=None, agent_id=None)`, `memfs_write(path, content, description=None, ...)`, `memfs_move(src, dst, ...)`, `memfs_delete(path, ...)`, `memfs_history(path, ...)`, `memfs_revert(path, revision, ...)`, `memfs_search(query, user_id=None, limit=5, agent_id=None)`. Paths are written without the root (`notes/plan.md`).
* The chain of calls: `send_message(..., trace=True)` puts the steps in `response.trace`; `stream_message(..., trace=True)` collects them in `stream.trace` while the answer arrives. A `TraceStep` is a call to the model (`kind="model"`, with `text`, tokens, `duration_ms`), a tool the model called (`kind="tool"`, with `args`, `result` or `error`).
* Users made by agents: when an agent asks another, the called one talks to the user `agent_<caller>:<person>`, marked `User.is_agent`; with Chats on both agents its chat belongs to the caller's chat (`Chat.parent_chat_id`).
* Finding users: `get_recent_users(limit=20)` (who wrote lately: latest first, with `last_active` and `messages`; the window is the service's message TTL), `search_users(query, limit=10)` returns the users of your agent whose external id starts with `query` (at least 3 characters, else `InvalidRequest`; the service has no list of all users), sorted, for suggestions while someone types.
* Tokens: `get_self_token()`, `get_tokens(agent_id=None)`, `create_token(name, role, agent_id=None)` (the answer's `.token` is the secret, shown once), `update_token(id, name=None, role=None)` (rename and/or change the role), `rename_token(id, name)`, `delete_token(id)`. Roles, least to most: `regular`, `user`, `admin`, `owner`; an owner hands out any, an admin and a user `regular` and `user` (a user only for its own agent). A token is bound to an **agent**; there are no units any more.
* Usage of the models (no texts): `get_usage(days=30, token_id=None, agent_id=None)` by day, token and model; `get_usage_monthly(...)` for what is older (folded by month).
* Knowledge base: `search_rag()`, `list_rag()`, `create_rag()`, `create_rag_batch(items, agent_id=None)` (1 to 1024 entries in one request, all or none, answered in order; an item is a string or `{content, embedding_content, metadata}`), `create_rag_many(items, agent_id=None, batch_size=1024, concurrency=4)` (any number: batches that go several at a time, answered in order; a failed batch raises and the ones already made stay), `get_rag()`, `update_rag()`, `delete_rag()`.

## Data Structures

The client receives data organized into the following structures:

* **Names**: agents, MCP servers and tokens require a `name` on create and accept an optional one on update. Models may omit the name or send an empty one: OpenRouter models use their display name from the catalog, while external models fall back to their model id. Explicitly empty model names and descriptions are refreshed from OpenRouter on update; omitted fields keep their values. Every object read back has a non-empty `name`; old entities without one get a fallback from the service (model -> its model name, agent -> the start of its prompt or `Agent <id>`, `MCP <id>`, `Unit <id>`). `get_self_unit()` and `get_self_agent()` use the main API, so they work without admin rights.
* **Token**: `role` (`regular|user|admin|owner`), `agent_id`, `is_initial` (the token of the service's `INITIAL_API_KEY`: an owner that cannot be deleted). What each role may do is decided by the service (`NoAccess` when a call is refused). An admin or owner may work as another agent: `Client(token, url, act_as_agent=7)` sends `X-Act-As-Agent` on every call (what is spent is still written on your own token).
* **User**: the system identification number, the agent's id, the external identification string and a timestamp.
* **Agent**: its `name`, the `model_id` of its model and its `blocks`.
* **AgentVersion**: Contains the agent, its number, a `snapshot` (blocks, model, MCP servers as they were), the comment, who made it and a timestamp.
* **Attachment**: A file for the model: `url` or base64 `data`, with `media_type` and an optional `name`.
* **CoreBlock**, **ArchivalPassage**, **RecallHit**, **MemoryUser**: the three tiers of memory (a core block: label, scope `person`|`agent`, limit, value; a passage: text, source, timestamp, and in a search `score` and `matched`). **MemfsEntry** / **MemfsFile** / **MemfsRevision** / **MemfsHit** / **MemfsUser**: the files.
* **Model**: Contains the identification number and the `request_json` sent to the model provider.
* **MCPServer**: Contains the identification number and the connection `config`.
* **MessageResponse**: Contains the text response from the artificial intelligence and the user information.
* **Message**: Contains the message identification number, user identification number, the text content, and a timestamp. The content is automatically converted from text format into a dictionary.

## Connections

By default every call opens its own connection. For many calls use the client as an async context manager, which keeps one connection pool:

```python
async with Client(token, base_url) as client:
    for text in texts:
        await client.send_message(user_id, text)
```

`await client.aclose()` closes the pool by hand. `await client.ready()` asks the service whether it is up and its database is ready (no token needed).

## Errors

All errors derive from `UnlinkError` and carry the explanation given by the service: `NoAccess` (401/403), `NotFound` (404), `Conflict` (409, for example deleting a model that an agent uses), `InvalidRequest` (422, rejected data), `StreamError` (a streamed answer failed midway) and `UpstreamError` (HTTP 502 or 504: the model provider or an MCP server failed or timed out; a retry may help), `RateLimited` (429: the agent's Rate limit; `retry_after` says in how many seconds to try again) and `ConnectionError` (the service cannot be reached).

## Development

```bash
uv sync                # create .venv (with the dev group: pytest)
uv run pytest            # unit tests and the contract test
uv build                 # build the wheel and sdist into dist/
```

`tests/test_server_contract.py` compares the models of this library with `tests/server_openapi.json`, a snapshot of the service's OpenAPI schema. After a model changes in the service, regenerate the snapshot there (`uv run python scripts/dump_openapi.py <path to this file>`) and adapt the library until the tests pass.
