wheelmachine 0.1.0__tar.gz

wheelmachine-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.pytest_cache/
+dist/
+build/
+*.egg-info/

wheelmachine-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+`wheelmachine`, the Wheelmachine library for Python. Each release is tagged `py-v<version>`.
+
+## 0.1.0
+
+The first public release.
+
+- The whole Wheelmachine API from Python, method for method, with retries that never make two of anything.
+- Python 3.9 or later, with the standard library alone.

wheelmachine-0.1.0/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.

wheelmachine-0.1.0/NOTICE

@@ -0,0 +1,4 @@
+Wheelmachine Python library
+Copyright 2026 Antelligen Private Limited
+
+Licensed under the Apache License, Version 2.0 (LICENSE).

wheelmachine-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: wheelmachine
+Version: 0.1.0
+Summary: The official Python SDK for the Wheelmachine API: machines for agents and people, by the second.
+Project-URL: Homepage, https://wheelmachine.ai
+Project-URL: Documentation, https://docs.wheelmachine.ai/libraries
+Project-URL: Source, https://github.com/Antelligen/wheelmachine/tree/main/frontend/sdk/python
+Project-URL: Issues, https://github.com/Antelligen/wheelmachine/issues
+Project-URL: Changelog, https://github.com/Antelligen/wheelmachine/blob/main/frontend/sdk/python/CHANGELOG.md
+Author-email: Antelligen Private Limited <team@antelligen.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,api,cloud,machines,sdk,wheelmachine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Wheelmachine for Python
+
+The official Python SDK for the Wheelmachine API: machines for agents and people, by the second.
+Python 3.9 or later, and nothing else: it uses only the standard library.
+
+## Install from source
+
+```sh
+pip install ./frontend/sdk/python # from a checkout of this repository
+export WHEELMACHINE_API_KEY=ak_live_...
+```
+
+## Quick start
+
+```python
+from pathlib import Path
+from wheelmachine import Wheelmachine
+
+client = Wheelmachine()  # reads WHEELMACHINE_API_KEY
+machine = client.machines.create(name="demo")
+machine = client.machines.wait(machine.id, "running")  # at once if it already is
+print(client.machines.exec(machine.id, ["uname", "-a"]).stdout)
+client.machines.write_file(machine.id, "work/notes.txt", Path("notes.txt"))  # a file in...
+client.machines.read_file(machine.id, "work/notes.txt", to="notes-back.txt")  # ...and back out
+client.machines.delete(machine.id)
+```
+
+## Signing in through the browser
+
+A program with no key yet can sign in the way `wm login` does: the person approves it in their browser, signed in
+with GitHub or Google, and the program is given a key of its own, once.
+
+```python
+from wheelmachine import DeviceLogin, Wheelmachine
+
+login = DeviceLogin.start(name="my-tool on laptop")      # scopes=[...] asks for less than everything
+print("Open", login.verification_uri, "and enter", login.user_code)
+key = login.wait()                                        # key.secret is the new key: keep it now
+client = Wheelmachine(api_key=key.secret)
+```
+
+## Credit
+
+```python
+credit = client.credit.get()                    # what is left: running time taken from it
+print(credit.balance_usd, credit.empty)
+for entry in client.credit.entries():           # every entry, the newest first
+    print(entry.at, entry.kind, entry.amount_usd, entry.machine_name)
+purchase = client.credit.buy(25)                # buy $25: pay it at purchase.checkout.url
+print(purchase.checkout.url)
+```
+
+At zero the account's machines are paused, and none starts until the balance is above $0. Credit is bought in $10, $25, $50
+or $100, from Paddle, our reseller, which adds any sales tax or VAT and e-mails the receipt and tax invoice: open
+`checkout.url` in a browser signed in to the dashboard, in the same account, and the credit is there once Paddle
+confirms the payment. In an organisation the credit is the organisation's, read and bought by its owners, admins and
+billing.
+
+## Organisations and the audit
+
+```python
+from datetime import datetime, timezone
+
+for org in client.orgs.list():                 # with a key of your own account
+    print(org.id, org.name, org.role)
+me = client.me()                                # with a key made in an organisation
+print(me.in_org, me.role, me.teams, me.limits)
+since = datetime(2026, 10, 1, tzinfo=timezone.utc)
+for event in client.audit.list(action="machine.", since=since):
+    print(event.at, event.person.name if event.person else event.by, event.action, event.target)
+client.audit.export("csv", since=since, to="audit.csv")  # whole: a year at most, 100,000 events at most
+```
+
+`DeviceLogin.start(account="acc_...")` asks for a key made in an organisation. The audit is read with a key that holds
+every scope, and in an organisation by its owners and admins.
+
+## Handing on and forking, in an organisation
+
+```python
+q = client.machines.fork_for(machine.id, "ravi@example.com")    # or hand_off(): cleared before it is theirs
+print(q.state, q.waiting_on)                                      # waiting on you ("asker"): approve it in the dashboard
+q = client.requests.get(q.id)                                     # then done and the fork in q.result, or on whom it waits
+asked = client.requests.ask("fork", "ravi", why="for the demo")   # Ravi picks which machine as they approve
+client.requests.take_back(asked.id)
+mine = client.machines.fork(machine.id)                           # a member's own: a MachineRequest until it is approved
+print(client.projects.rules(machine.project).forks)              # ask or off
+```
+
+Approving and declining are a person's, signed in to the dashboard, and a team's rules are set there. A key decides
+nothing by itself: a give or an ask made with one waits first for its maker's own OK there. A machine handed on arrives
+paused, its memory kept, until its receiver starts it. A member's own fork waits too, for the OK of a full manager of
+its team, an owner or an admin: `machines.fork` answers it with the request, and the fork is its `result` once made.
+
+## What to know
+
+- **The client.** `Wheelmachine(api_key=None, base_url=None, timeout=60.0, max_retries=3, proxy=None)`. The key
+  comes from `WHEELMACHINE_API_KEY` and the address from `WHEELMACHINE_BASE_URL` when not given. The key is never
+  logged, printed, or put in an error or a repr. One client is safe to share between threads, and keeps its
+  connections open between calls; `close()` or a `with` block closes them. HTTPS_PROXY and NO_PROXY are followed.
+- **Errors.** Everything raised is a `WheelmachineError`, with `status`, `code` (the API's stable code), `detail`,
+  `request_id` (give it when you ask us about a call) and `retry_after`. By family: `BadRequestError` (400),
+  `AuthenticationError` (401), `PaymentRequiredError` (402), `PermissionDeniedError` (403), `NotFoundError` (404),
+  `WaitTimeoutError` (408), `ConflictError` (409, 422), `RateLimitError` (429), `InternalServerError` (500),
+  `UnavailableError` (502, 503, 504), and `APIConnectionError` / `APITimeoutError` when no answer came.
+- **Retries.** A call refused for a moment (429, 503) is tried again after the API's `Retry-After`, or a backoff with
+  full jitter; so is a call that lost its connection - but a command (`exec`), `start`, `pause` and the other
+  actions are not sent again once they went out, since they may have run. A call that creates something (a
+  machine, fork, backup, project or key, a give or an ask) carries an `Idempotency-Key`, the same on every retry, so a retry never
+  makes two; pass your own with `idempotency_key=` to retry across restarts. A 503 `not_open` is something not
+  served yet, not a moment's refusal: it is never tried again.
+- **Long calls.** Calls the API holds by design - making a machine ready (`wait_s`), `wait()`, `exec()` (up to 10
+  minutes), `archive()` - are given the time they need on top of `timeout`.
+- **Lists** page by themselves: `for m in client.machines.list(state="running", labels={"team": "ml"})`.
+- **Files** are `home/...` or `work/...` in the machine. `write_file` streams bytes, a `pathlib.Path` or a binary
+  file object with its length; `read_file` gives bytes, or streams into a path (whole or not at all) or a file object.
+- **Backups** keep a machine's files as they are: `backup = client.machines.backup(machine.id, note="before")`. A fork
+  is made from one, starting afresh, at the machine's size or another: `client.machines.fork(machine.id,
+  backup=backup, cpus=8)`, or `backup="latest"` for its newest. `client.machines.backups(machine.id)` lists a
+  machine's, the newest first, and `client.machines.backups()` every one the key reaches.
+- **Answers** are typed objects with the API's own field names; each keeps its JSON in `raw`, and one a call answered
+  with says how it came in `last_response` (`request_id`, `replayed`, `rate_limit`).
+- **What a machine used**: `client.machines.metrics(machine.id, since="6h", step=300)` gives its processors (a share
+  of its own size), memory, disk and network a point a step; `since` is also a `timedelta` or an aware `datetime`.
+  Its server keeps a point a minute for the last day, in memory, read while the machine runs.
+- **Secrets** are values every command in a machine gets as environment variables:
+  `client.secrets.set("API_TOKEN", token)`, then `client.machines.create(secrets=["API_TOKEN"])` or
+  `client.machines.update(machine.id, secrets=["API_TOKEN"])` (the names said whole; `[]` takes them away).
+  Hold what a machine reaches on the internet with `network=` on `create`/`update` - `{"internet": "closed"}`, or
+  `{"internet": "allowed", "allow": ["api.github.com", "*.githubusercontent.com", "140.82.112.0/20"]}` (names for web,
+  ranges for other ports); a running machine's policy changes at once, without a restart. `machine.network` shows it.
+  `client.secrets.list()` gives names and the machines given each - a value is never answered again, and never put
+  in an error. Read the value from somewhere safe (a file, a vault, the environment), never write it in code.
+- **Your own AI keys** are set once, under the names agents read them by: `client.secrets.set("ANTHROPIC_API_KEY",
+  key)` keeps it outside every machine - each holds a placeholder, and the key is sent only to its maker's hosts -
+  and every machine gets it (`machine.ai_keys`). `every_machine=False` keeps it on the machines given it, and
+  `outside=False` makes it an ordinary secret. `client.secrets.presets()` lists the names and where each key goes.
+
+## Ports
+
+A program listening on a port in a machine is reached at a web address of its own,
+`https://<port>-<the machine's id without m_>.run.wheelmachine.ai`. HTTP, WebSockets and streams pass through, and a
+paused or archived machine is started by the first visit. The address is private unless the port is opened with
+`public=True`: it answers a call carrying an API key that can see the machine (the key never reaches the program),
+and a browser that opened a link made for it. Anyone else is answered 401.
+
+```python
+import os
+import urllib.request
+import webbrowser
+
+port = client.ports.open(machine.id, 8080)  # a program in the machine listens on 8080
+headers = {"Authorization": "Bearer " + os.environ["WHEELMACHINE_API_KEY"]}
+print(urllib.request.urlopen(urllib.request.Request(port.url, headers=headers)).status)  # in with the key
+link = client.ports.link(machine.id, 8080)  # or in with a link, for one browser
+webbrowser.open(link.url)  # it opens once, within five minutes
+print([(p.port, p.public) for p in client.ports.list(machine.id)])  # lowest first
+client.ports.close(machine.id, 8080)  # the address answers 404 from then on
+```
+
+`link()` also takes `access_s`, how long the browser that opens it stays in (1800 seconds by default, 60 to 3600),
+and `path`, where it lands (`/` by default). A link's `url` is in that answer only, and never in a repr. A port open
+already is made public or private as asked, so `open` is sent again after a lost connection; `link` never is once
+it may have reached the API, not even when refused for a moment, since each call makes a new link. A machine has at
+most 20 ports open, and the ones it uses itself (5900, 6080, 7070, 9222, 9223, 9224) cannot be opened. Until web
+addresses are served, `open` is refused with `UnavailableError` and the code `not_open`.
+
+## Apps
+
+A machine carries apps, on by default and turned on and off: a desktop and a code editor in the browser and an agent's
+own page (`kind` `web`), a model server reached from inside the machine (`service`), and agents that each keep a
+session of their own in its terminal (`agent`; a machine made before agents had sessions lists them as `terminal`, run
+by typing their `command`). Gemini CLI starts off, until it is turned on; the code editor is always on, and turning it
+off is refused with `ConflictError`. A web app is reached at the machine's private address for its port; asking for a
+link into one that is on opens that address private when it is not open.
+
+```python
+import webbrowser
+
+for app in client.apps.list(machine.id):
+    print(app.name, app.kind, app.on)
+desktop = client.apps.turn_on(machine.id, "desktop")  # its port opened private, if it was not
+webbrowser.open(desktop.link)  # it opens once, within five minutes, on the app's own page
+again = client.apps.link(machine.id, "desktop")  # a fresh link, while it is on
+client.apps.show(machine.id, "openclaw")  # its window on the machine's own screen, signed in
+client.apps.turn_off(machine.id, "desktop")
+```
+
+An app with a token of its own answers it once, in `token`, in the answer to `turn_on`. `link` and `token` are
+never in a repr. `turn_on` and `link` are never sent again once they may have reached the API; `turn_off` is. A machine
+made before apps came has none: `ConflictError` with the code `no_apps`.
+
+## Terminals
+
+An interactive terminal in a machine (a login shell, or one command on a terminal of its own) is a WebSocket, not a
+call this library makes: a WebSocket client is a dependency, and this library has none. Open one at
+
+```
+GET wss://api.wheelmachine.ai/v1/machines/{machine_id}/terminal
+    Authorization: Bearer ak_live_...
+```
+
+with the `cloud:machines:exec` scope. The query sets it up: `cols`, `rows`, `user` (`user` or `root`), `term`, `cwd`,
+and `cmd` repeated for each word of a command (left out, a login shell opens). A paused machine is woken for it.
+
+Over the socket, each message is one event. **From you:** a *binary* message is typed in (keystrokes, bytes as they
+are); a *text* message `{"resize":{"cols":C,"rows":R}}` sets the window. **From us:** a *binary* message is what the
+program wrote; a final *text* message `{"exit_code":N}` (or `{"reason":...,"message":...}` when it did not end by
+itself) says how it ended, just before the socket closes. We never log what is typed or shown.
+
+For a ready-made interactive client, `wm ssh <machine>` (the `wm` command-line tool) drives this endpoint: raw local
+terminal, window changes followed, and your shell's own exit code.
+
+For `scp`, `sftp` and editors' remote-SSH, `POST /v1/ssh/certificates` signs a short-lived SSH certificate (give a
+public key and a machine; good for at most an hour, for that machine alone) to present to the SSH server. `wm
+ssh-config <machine>` prints the matching `~/.ssh/config` block.
+
+## Tests
+
+```sh
+cd frontend/sdk/python && python3 -m pytest -q      # or: PYTHONPATH=src:tests python3 -m unittest discover -s tests
+```
+
+They run against a stand-in for the API on 127.0.0.1; nothing reaches the network.