Skip to main content

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):

    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:

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

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.

Metadata

Release files for omnixon-lib 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for omnixon-lib 3.0.0
File Size Uploaded Provenance Actions
omnixon_lib-3.0.0.tar.gz 101.9 kB Without provenance Details for omnixon_lib-3.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for omnixon-lib 3.0.0
File Interpreter ABI Platform Actions
omnixon_lib-3.0.0-py3-none-any.whl Python 3 none any Details for omnixon_lib-3.0.0-py3-none-any.whl

Total release size: 136.1 kB

Release files / omnixon_lib-3.0.0.tar.gz

Download URL omnixon_lib-3.0.0.tar.gz
Size 101.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b08b46d17cd8c6aec2abbe3c568b0cd0d956b9470ec94530e525a04567302fda
BLAKE2b-256 checksum
How to use checksums
a8a00633701dd16a595aca53f426d770f825915aafea10b3a41d542e03bcfd29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.22

Release files / omnixon_lib-3.0.0-py3-none-any.whl

Download URL omnixon_lib-3.0.0-py3-none-any.whl
Size 34.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c16b20ba8869e7e49a30d168fad4374053e0bb3be7ee1d4c893a051234485d67
BLAKE2b-256 checksum
How to use checksums
3c6d30f0e819b200bd142af474290b518a65e56e86528d56530bd6463c588a51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.22

Security for omnixon-lib 3.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page