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_idmay beNoneor an empty string. The service then creates a new user for your agent and returns it asresponse.user; keepresponse.user.external_idto continue the conversation. An agent without the Users block is stateless:response.userandresponse.chat_idareNone.attachmentsis a list of files for the model: images, PDFs, text, audio, video. Build them withAttachment.from_file(path),Attachment.from_bytes(data, "image/png")orAttachment.from_url(url). The model must be able to handle them (for images it must see); a model that cannot givesUpstreamError. The history keeps only a note that a file was there, never the file.
send_message_stream(user_id, message, attachments=None): Likesend_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 raisesStreamErrorif 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; itsuserattribute holds the user (also a newly created one) as soon as the service sends it, before the first chunk (Nonefor 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_messageandsend_message_streamtakechat_id=;MessageResponse.chat_idsays where it was written. Withoutchat_ida message goes to the user's default chat, so code that knows nothing about chats works as before;get_history/clear_historyare that chat's. -
Interrupting:
interrupt(user_id)stops the answer that is being streamed to that user and returnsInterrupted(interrupted, text). The stream ends cleanly (MessageStream.interruptedisTrue), what had been said goes to the history (markedinterrupted). 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.tooloffers a function of yours to the model with every message (the agent needs the Client tools block; without itConflict):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.toolslists 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 ofToolCall:idlike"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_messagejoins it: a failure after the service began to answer isStreamError, 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 ofkind="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="")—kindischat,embeddingordecision(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, andobserver(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_urlpoints a model at another OpenAI-compatible server (default: OpenRouter),use_proxy=Falsecalls it without the service's proxy,api_tokenis the key for that server (default: the key of the service; it is never returned,Model.has_api_tokensays whether there is one;""inupdate_modelclearsbase_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 akind:chat(what an agent answers with) orembedding(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 withInvalidRequest; it may live on another server withbase_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 asNone: the service's setting decides).get_blocks()is the catalog the service gives (BlockType: title,requires,min_role,default, the JSONschema_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=Truefor a type that may be there more than once, such asmcp),agent.without_blocks("rag");agent.block("history")reads one. A broken list (a block without what it needs, a type twice) raisesInvalidRequest; a block your role may not change raisesNoAccess. Options left unset take the service's settings:get_settings()andupdate_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 kindembedding). They also name the provider models are called at:default_provider(an OpenAI-compatible address, OpenRouter's unless changed) and its keyprovider_token(never returned:has_provider_tokenandprovider_token_source,settingsorenv, say whether one is known;""goes back to the environment's value). A model whosebase_urlisNonefollows 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 (pendingoftotal, andstores: the same forrag,memoryandmemfs). The knowledge base (rag), the memory (memory) and the files (memfs) each have an optionembedding_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.scoreandRAG.matched(bm25,vectororboth) say how an entry of a search was found. Aragblock withwritable=Truelets the agent add, change and delete entries. -
Connections between agents and MCP tools of an agent are blocks too: an
agent_callsblock lists the agents it may ask (connections=[{"agent_id": 2}]; it gets the toolslist_agentsandask_agent), anmcpblock 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,todefaults to the latest) androllback_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 withConflictif the agent has moved on since versionn, 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 (TimeoutErrorpasttimeout),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 flagscore,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 unlesslimit; without one: every message, the newest first, 50 a page afteroffset). A summary kept by the service (Archival'ssummarize) is listed byget_core_memoryas the read-only blocksummary. What leaves the History window is saved as archival passages (source == "history"). -
Files (MemFS, the block
memfswith the flagsagent_filesandperson_files(andagent_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)(nouser_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 inresponse.trace;stream_message(..., trace=True)collects them instream.tracewhile the answer arrives. ATraceStepis a call to the model (kind="model", withtext, tokens,duration_ms), a tool the model called (kind="tool", withargs,resultorerror). -
Users made by agents: when an agent asks another, the called one talks to the user
agent_<caller>:<person>, markedUser.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, withlast_activeandmessages; the window is the service's message TTL),search_users(query, limit=10)returns the users of your agent whose external id starts withquery(at least 3 characters, elseInvalidRequest; 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.tokenis 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 userregularanduser(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
nameon 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-emptyname; old entities without one get a fallback from the service (model -> its model name, agent -> the start of its prompt orAgent <id>,MCP <id>,Unit <id>).get_self_unit()andget_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'sINITIAL_API_KEY: an owner that cannot be deleted). What each role may do is decided by the service (NoAccesswhen a call is refused). An admin or owner may work as another agent:Client(token, url, act_as_agent=7)sendsX-Act-As-Agenton 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, themodel_idof its model and itsblocks. - 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:
urlor base64data, withmedia_typeand an optionalname. - 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 searchscoreandmatched). MemfsEntry / MemfsFile / MemfsRevision / MemfsHit / MemfsUser: the files. - Model: Contains the identification number and the
request_jsonsent 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.