maitento 26.11.1__tar.gz

maitento-26.11.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.venv/
+dist/
+build/

maitento-26.11.1/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to the `maitento` Python package. Versions are shared with the other Maitento SDKs (`YY.M.N`).
+
+## 26.11.1 (2026-11-03)
+
+- First release: `Maitento` (blocking) and `AsyncMaitento` (asyncio) clients covering every public API route,
+  `deploy()`/`validate()` for resource projects, `run()` helpers with token streaming, live events over the
+  `/notifications` WebSocket, typed errors, paged lists, and web-hook verification helpers.
+- Deploying needs a tenant admin: anyone else is refused with a 403, code `api:builds:deploy-requires-admin`. Any
+  member can still `validate()`.
+- A `run()` helper's errors word a run the same way in every Maitento SDK: `App run <id> ended Error: <failure
+  details>` (`... ended Killed.` when the run recorded nothing), and `Interaction run <id> did not finish within 2s.`
+- `automations.trigger()` raises `ValidationError` with code `api:automations:start-failed` (followed by the cause's
+  own codes) when no action could start, instead of returning an empty process id. Creating or updating an automation
+  whose app action leaves out one of the app's inputs is refused with `api:automations:app-input-missing`.
+- Usage: `toolCalls` (on `/usage/runs` rows and the usage totals) counts an interaction run's tool calls too; it was 0
+  for every interaction run.
+- Starting an interaction, an app or a code pipeline takes `credential_stack` (the stack's id or name) to run on that
+  credential stack: its credentials serve the run, and Maitento's own keys never do. An app's stack is the stack of
+  every run it starts. Naming a stack and passing `credentials` at once is refused with
+  `api:credential-stacks:with-credentials`; naming one the tenant hasn't got, with `api:credential-stacks:unknown`.
+- Interactions, apps and code pipelines can name their own credential stack (`credential_stack` on their versions and
+  on the interaction update and pipeline create requests; `credentialStack` in an `.mtr` file or `pipeline-definition.json`):
+  runs that don't name one at the start use it before the namespace's and the tenant's default.
+- `credentials` and `credential_stacks` manage the tenant's own model credentials and the stacks runs use them
+  through. `credentials`: `list(tag=)`, `get`, `find`, `create`, `update`, `delete`, `delete_by_tag` (returns how
+  many), `test`, and `start_sign_in`/`finish_sign_in` to sign a Claude Code or Codex subscription in as a credential.
+  Keys are write-only: only each key's `key_hint` is served; an update keeps a key sent by `id` alone, or with the value
+  it already has. `credential_stacks`: `list`, `get`, `find`, `create`,
+  `update`, `delete`, and `get_tenant_default`/`set_tenant_default` and
+  `get_namespace_default`/`set_namespace_default` (`None` clears a default).
+- An Anthropic credential can reach Claude on Amazon Bedrock or Google Vertex AI: `cloud={"kind": "Bedrock",
+  "awsRegion": ...}` or `{"kind": "Vertex", "gcpProjectId": ..., "gcpRegion": ...}` (endpoint kinds `Bedrock` and
+  `Vertex`), with the Bedrock API key or the service account's JSON key file as its key. Only code pipelines' Claude Code
+  agents run on it; testing it answers `api:credentials:test-not-supported`; a cloud that can't be reached is refused
+  with `api:credentials:cloud-invalid`.
+- On a credential stack, a model an agent override defines inline (`custom_model`) and a coding agent on your own
+  endpoint (`CustomAnthropic`, `CustomOpenAiResponses`, `CustomOpenAiChat`) run on the stack's credentials that have
+  their own endpoint, for the model's API, and name the model in `models`; they had no credential on a stack before.
+- `credential_stacks.find_by_name(name)` (`GET /credential-stacks/by-name/{name}`): a stack by its name, or `None`.
+- `credentials.test_unsaved(...)` (`POST /credentials/test`): tests a credential before saving it, with what `create`
+  takes, and stores nothing.
+- `credential_stacks.usage(id)` (`GET /credential-stacks/by-id/{id}/usage`): whether a stack is the tenant's default,
+  the namespaces whose default it is, and the knowledge bases that embed with it.
+- `credentials.import_sign_in(tool=, access_token=, refresh_token=, expires_at_utc=, id_token=)` makes an OAuth
+  credential from a sign-in whose tokens you already hold, and `replace_sign_in_tokens(id, ...)` swaps them after you
+  refresh: Maitento never refreshes such a sign-in itself (`oauth.refreshed_by_caller`). Each route refuses the other
+  kind of sign-in (`api:credentials:sign-in-refreshed-here`, `api:credentials:sign-in-refreshed-by-caller`).
+- An automation's `app` and `interaction` actions take `credential_stack` (the stack's id or name) for the runs they
+  start, as a `codepipeline` action's `request` does. Saving an action that names a stack the tenant hasn't got is
+  refused with `api:credential-stacks:unknown`; a pipeline action with a stack and `credentials` of its own, with
+  `api:credential-stacks:with-credentials`.
+- `partitions.set_embedding_credential_stack(id, stack_id)` (`None` clears it): a knowledge base embeds on its own
+  credential stack (`embedding_credential_stack_id` on `Partition`), after its own embedding keys and in place of the
+  tenant's model keys and default stack, never on Maitento's key. Deleting a stack a knowledge base embeds with is
+  refused with `api:credential-stacks:in-use-by-partition`.
+- A `NotFoundError` from starting a run by name, or from naming a namespace that does not exist, says what was not
+  found (`Interaction 'brainstorm' was not found in namespace 'demo'.`): the 404 now carries it as `{ error }`.
+- Stable error codes for a refused interaction start (`api:interactions:input-required`, `input-empty`,
+  `input-invalid`, `input-unknown`, `not-found`, `no-enabled-version`, `response-schema-invalid`,
+  `swarm-limits-invalid`, `loom-*`, `ai-model-override-invalid`), for deleting a knowledge base that still holds files
+  (`api:partition:not-empty`), and for refused embedding credentials. They used to be derived from the request member
+  (`request`, `id`, `credentials`). The messages name the interaction rather than its id.
+- A required tool-binding or auth input with a default no longer refuses a run that leaves it out: the run uses the
+  default (shown in the run's inputs), as it does when the input is passed empty.
+- An interaction created through the API without `contextSettings` gets the same context defaults as one deployed
+  from a `.mtr` file with no `context` block (`Automatic` trimming, a 32,000-token reply cap); it used to get
+  `FailOnOverflow` and the model's full reply.
+- Files: `IngestedFile.indexingFailure` (and on file listings): why a file can't be indexed until someone acts, as a
+  `code` (`api:embeddings:fallback-not-permitted` when there is no embedding key, `api:embeddings:credentials-exhausted`
+  when every key failed), a `message` and `dateFailed`. Cleared once the file is indexed. Searching a knowledge base
+  that can't embed is refused with `api:embeddings:fallback-not-permitted` instead of returning no results.
+- Files of a knowledge base with no embedding key it may use wait instead of being retried every few minutes, and start
+  again once a key, a credential stack or consent to Maitento's key is added. Such a knowledge base carries one
+  `PartitionEmbeddingCredentialFailure` with `failure_reason` `IndexingDisabled` and `credential_id` `maitento-fallback`
+  (listed by `GET /partitions/embedding-credential-failures`), so you can tell your admins.
+- `capsule_runs.exec_and_wait(id, command, arguments, timeout=..., abort=...)` queues a command and waits for it to
+  end, over live events when a stream is open and by polling the one command otherwise; it returns the command with
+  its exit code and output, and raises the new `CapsuleCommandAbortedError` when the capsule ends first.
+  `capsule_runs.get_command(id, command_id)` reads one command (`GET /capsule-processes/by-id/{id}/commands/{commandId}`).
+- Secrets are write-only: `secrets.value(name)` and its route, `GET /secrets/by-name/{name}/value`, are removed, so
+  nothing reads a stored value back. Replace a value with `secrets.update` instead.
+- Code pipeline repositories take `is_read_only` (`isReadOnly` in the API): a read-only repository is cloned as context for
+  the agents, but a run never commits, pushes or diffs it. It defaults to `false`.
+- `tenant.set_retention(hours=)`: a tenant admin sets how long finished runs are kept, up to the plan's maximum (the new
+  `plan_max_hours` in `tenant.retention()`); `hours=None` goes back to the platform default. A retained run is kept for
+  at most the plan's maximum, and its retention status says when that is (`lease_ends_at_utc`).
+- `runs.lane(id, type=)`: whether a run is waiting for a lane before it starts, since when, why (`LANES_IN_USE` or
+  `PLATFORM_BUSY`), and how many of your runs are ahead of it. Runs and run lists carry `waiting_for_lane_since_utc`.
+- `billing`: the tenant's plan and billing. `standing()` (the plan and its state, the balance, whether work can start,
+  any plan change on its way, and this month's use of each allowance), `plan()`, `balance()`, `catalogue()` (the
+  plans on sale), `notices(limit=)`, and the balance settings: `auto_top_up()` / `set_auto_top_up()` and `alerts()` /
+  `set_alerts()`. Buying a plan or credit, and changing the plan, stay in the portal. The standing also says when the
+  balance is low (`low_balance`, by the alert settings) and when the subscription renews (`term_ends_at_utc`).
+- `TenantRegisterRequest`: `code` is optional, and there's a new `turnstileToken`. Where sign-up is open, a tenant can be
+  registered without an invitation code, with the sign-up page's Cloudflare Turnstile token instead.
+- Sign-in with GitHub, Google and Microsoft is a portal flow under `/auth/sso`, which the SDK doesn't wrap (an SDK
+  client has no browser to send to a provider). Its request and response models are generated: `SsoProvider`,
+  `SsoProvidersResponse` (with `sign_up_open` and the `start_base_url` a sign-in starts from), `SsoExchangeRequest`
+  and `SsoConfirmLinkRequest`.
+- A `Billing` webhook type: a `BillingNotice` is delivered when your tenant runs out of credit or gets it back
+  (`OutOfCredit`, `CreditRestored`), uses up an allowance (`AllowanceUsed`), runs low (`LowBalance`), its plan changes
+  (`PlanChanged`, `PlanRestored`, `MovedToFree`), a renewal payment fails (`PaymentFailed`, then `FreezeReminder` and
+  `FreezeEnded`), or an automatic top-up can't be charged (`AutoTopUpFailed`). It carries the `meter`, `balance`,
+  `currency`, `tier`, `previousTier` and `frozenUntilUtc` where they apply.
+- Web-hook deliveries are signed. `verify_webhook(headers, body, secret, *, tolerance=300, now=None)` now checks
+  `X-MT-WebHook-Signature` (`v1=` and the HMAC-SHA256 of `"{timestamp}." + body`, keyed with your secret) against the
+  **raw** body, and refuses a delivery whose `X-MT-WebHook-Timestamp` is more than 5 minutes from now, so a delivery
+  can't be forged by someone who saw another, or replayed. `sign_webhook(secret, timestamp, body)` makes the `v1=`
+  value, for your receiver's tests; `maitento.webhooks` has `TIMESTAMP_HEADER`, `SIGNATURE_HEADER` and
+  `DEFAULT_TOLERANCE`. `parse_webhook(headers, body, secret=...)` verifies the signature the same way (so `body` must
+  then be raw). This replaces `verify_webhook(headers, secret)`, which compared the plain `X-MT-WebHook-Secret`
+  header: that header isn't sent to new webhooks, and the SDK no longer accepts it (`SECRET_HEADER` is gone). (A
+  breaking change, made before the first release.)
+- A `WebHookRegistration` has `signed_only`: `True` when its deliveries are only signed, as for every webhook
+  registered now, and `False` for one registered before deliveries were signed, which also gets its secret in
+  `X-MT-WebHook-Secret`. `webhooks.update(id, url=..., signed_only=True)` stops such a webhook sending its secret, in
+  place: there's no need to delete it and register it again. It can't be undone, and `False` or leaving it out changes
+  nothing. The `mt` CLI does the same with `mt webhook-set ... --signed-only`.

maitento-26.11.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

maitento-26.11.1/NOTICE

@@ -0,0 +1,5 @@
+Maitento Python SDK
+Copyright 2026 Brunelly Ltd
+
+This product includes software developed by Maitento (https://docs.maitento.com).
+Licensed under the Apache License, Version 2.0 (see LICENSE).

maitento-26.11.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: maitento
+Version: 26.11.1
+Summary: The official Python SDK for Maitento, the AI OS: deploy agents and interactions, run them, and follow them live.
+Project-URL: Homepage, https://docs.maitento.com
+Project-URL: Documentation, https://docs.maitento.com
+Project-URL: Repository, https://github.com/maitento/maitento
+Project-URL: Changelog, https://github.com/maitento/maitento/blob/main/sdks/python/CHANGELOG.md
+Author: Maitento
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,ai,interactions,llm,maitento,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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 :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: mypy==2.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: respx==0.23.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://docs.maitento.com/brand/logo-horizontal-on-light-600.png" alt="maitento" width="240"></p>
+
+# Maitento Python SDK
+
+The official Python SDK for [Maitento](https://docs.maitento.com), the AI OS: deploy agents and interactions, run
+them, stream their answers, and react to what they do.
+
+```bash
+pip install maitento
+```
+
+Python 3.10 or newer. It depends on `httpx`, `pydantic` (v2) and `websockets`.
+
+## Quick start
+
+```python
+from maitento import Maitento
+
+mt = Maitento()                          # reads MAITENTO_API_KEY, MAITENTO_BASE_URL, MAITENTO_NAMESPACE
+mt.deploy("./maitento")                  # the resource project folder
+run = mt.interactions.run("hello")       # start, wait, return the finished run
+print(run.output)
+```
+
+`MAITENTO_API_KEY` is `"<userId>:<secret>"`, as the portal shows it: the id of the user that owns the key, a colon,
+then the secret. The same code runs on asyncio with `AsyncMaitento` and `await`:
+
+```python
+import asyncio
+from maitento import AsyncMaitento
+
+async def main() -> None:
+    async with AsyncMaitento() as mt:
+        run = await mt.interactions.run(
+            "haiku",
+            inputs={"topic": "autumn"},
+            on_token=lambda text, agent: print(text, end="", flush=True),
+        )
+        print("\n", run.status)
+
+asyncio.run(main())
+```
+
+## What is in it
+
+- **Every API resource** as a method group: `namespaces`, `models`, `model_keys`, `agents`, `interactions`,
+  `interaction_runs`, `apps`, `app_runs`, `capsules`, `capsule_runs`, `pipelines`, `pipeline_runs`, `runs`,
+  `connectors`, `tools`, `secrets`, `webhooks`, `partitions`, `files`, `vfs`, `looms`, `automations`, `builds`,
+  `usage`, `users`, `api_keys`, `invitations`, `tenant`, `events`.
+- **`get` vs `find`**: `get…` raises `NotFoundError`; `find…` returns `None`.
+- **`run()` helpers** for interactions, apps, capsules and pipelines: start once (never retried), follow the run
+  over the live event socket or by polling, call `on_token` / `on_update` / `on_waiting`, and return the finished run
+  (or raise `ProcessFailedError`).
+- **Live events** (`mt.events.connect()`): callbacks with `on(...)` or a plain `for event in stream` loop, with
+  automatic pings, reconnects and a `reconnected` event.
+- **Typed errors** (`ValidationError`, `NotFoundError`, `RateLimitError`, ...), all derived from `MaitentoError`.
+  Calls that only read are retried on network errors, 429 and 502/503/504, honouring `Retry-After`.
+- **Paged lists** you can iterate across pages: `for run in mt.runs.list(state="Terminal"): ...`
+- **Web-hook helpers** for your receiver: `verify_webhook(headers, body, secret)` checks a delivery's signature from
+  its raw body, and `parse_webhook(headers, body)` reads it.
+- **Generated wire models** (pydantic v2) that tolerate new fields and new enum values from a newer server.
+
+## Links
+
+- Documentation: <https://docs.maitento.com>
+- Source: <https://github.com/maitento/maitento>
+- Changelog: [CHANGELOG.md](https://github.com/maitento/maitento/blob/main/sdks/python/CHANGELOG.md)
+
+Licensed under the Apache License, Version 2.0.

maitento-26.11.1/README.md

@@ -0,0 +1,69 @@
+<p align="center"><img src="https://docs.maitento.com/brand/logo-horizontal-on-light-600.png" alt="maitento" width="240"></p>
+
+# Maitento Python SDK
+
+The official Python SDK for [Maitento](https://docs.maitento.com), the AI OS: deploy agents and interactions, run
+them, stream their answers, and react to what they do.
+
+```bash
+pip install maitento
+```
+
+Python 3.10 or newer. It depends on `httpx`, `pydantic` (v2) and `websockets`.
+
+## Quick start
+
+```python
+from maitento import Maitento
+
+mt = Maitento()                          # reads MAITENTO_API_KEY, MAITENTO_BASE_URL, MAITENTO_NAMESPACE
+mt.deploy("./maitento")                  # the resource project folder
+run = mt.interactions.run("hello")       # start, wait, return the finished run
+print(run.output)
+```
+
+`MAITENTO_API_KEY` is `"<userId>:<secret>"`, as the portal shows it: the id of the user that owns the key, a colon,
+then the secret. The same code runs on asyncio with `AsyncMaitento` and `await`:
+
+```python
+import asyncio
+from maitento import AsyncMaitento
+
+async def main() -> None:
+    async with AsyncMaitento() as mt:
+        run = await mt.interactions.run(
+            "haiku",
+            inputs={"topic": "autumn"},
+            on_token=lambda text, agent: print(text, end="", flush=True),
+        )
+        print("\n", run.status)
+
+asyncio.run(main())
+```
+
+## What is in it
+
+- **Every API resource** as a method group: `namespaces`, `models`, `model_keys`, `agents`, `interactions`,
+  `interaction_runs`, `apps`, `app_runs`, `capsules`, `capsule_runs`, `pipelines`, `pipeline_runs`, `runs`,
+  `connectors`, `tools`, `secrets`, `webhooks`, `partitions`, `files`, `vfs`, `looms`, `automations`, `builds`,
+  `usage`, `users`, `api_keys`, `invitations`, `tenant`, `events`.
+- **`get` vs `find`**: `get…` raises `NotFoundError`; `find…` returns `None`.
+- **`run()` helpers** for interactions, apps, capsules and pipelines: start once (never retried), follow the run
+  over the live event socket or by polling, call `on_token` / `on_update` / `on_waiting`, and return the finished run
+  (or raise `ProcessFailedError`).
+- **Live events** (`mt.events.connect()`): callbacks with `on(...)` or a plain `for event in stream` loop, with
+  automatic pings, reconnects and a `reconnected` event.
+- **Typed errors** (`ValidationError`, `NotFoundError`, `RateLimitError`, ...), all derived from `MaitentoError`.
+  Calls that only read are retried on network errors, 429 and 502/503/504, honouring `Retry-After`.
+- **Paged lists** you can iterate across pages: `for run in mt.runs.list(state="Terminal"): ...`
+- **Web-hook helpers** for your receiver: `verify_webhook(headers, body, secret)` checks a delivery's signature from
+  its raw body, and `parse_webhook(headers, body)` reads it.
+- **Generated wire models** (pydantic v2) that tolerate new fields and new enum values from a newer server.
+
+## Links
+
+- Documentation: <https://docs.maitento.com>
+- Source: <https://github.com/maitento/maitento>
+- Changelog: [CHANGELOG.md](https://github.com/maitento/maitento/blob/main/sdks/python/CHANGELOG.md)
+
+Licensed under the Apache License, Version 2.0.

maitento-26.11.1/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "maitento"
+dynamic = ["version"]
+description = "The official Python SDK for Maitento, the AI OS: deploy agents and interactions, run them, and follow them live."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Maitento" }]
+keywords = ["maitento", "ai", "agents", "llm", "sdk", "interactions"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+# Lower bounds are releases that have been widely available for a long time (httpx 0.27: Feb 2024,
+# pydantic 2.9: Sep 2024, websockets 13.0: Aug 2024 — the first with the `websockets.asyncio` client).
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2.9,<3",
+    "websockets>=13.0",
+]
+
+[project.optional-dependencies]
+# Pinned so a contributor's run matches CI. Every pin was released at least two weeks before 2026-10-26.
+dev = [
+    "pytest==9.1.1",
+    "pytest-asyncio==1.4.0",
+    "respx==0.23.1",
+    "mypy==2.4.0",
+]
+
+[project.urls]
+Homepage = "https://docs.maitento.com"
+Documentation = "https://docs.maitento.com"
+Repository = "https://github.com/maitento/maitento"
+Changelog = "https://github.com/maitento/maitento/blob/main/sdks/python/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/maitento/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maitento"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/maitento",
+    "tests",
+    "scripts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "route-map.json",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "-m 'not live' -p no:cacheprovider"
+markers = [
+    "live: calls a running Maitento API (needs MAITENTO_BASE_URL, MAITENTO_API_KEY and MAITENTO_TEST_DEEPSEEK_KEY); run with `pytest -m live`",
+]
+filterwarnings = ["error"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/maitento"]
+plugins = ["pydantic.mypy"]
+cache_dir = "/tmp/.mypy_cache"
+
+[[tool.mypy.overrides]]
+# Generated from the server's wire contract; regenerated, never hand-edited.
+module = ["maitento._generated.*"]
+ignore_errors = true