canyonos-api-interface 1.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,51 @@
1
+ Metadata-Version: 2.4
2
+ Name: canyonos-api-interface
3
+ Version: 1.0.1
4
+ Summary: Typed client for the CanyonOS REST API
5
+ License-Expression: AGPL-3.0-only
6
+ Project-URL: Homepage, https://canyonos.ai
7
+ Project-URL: Source, https://github.com/CanyonCodeCoreAI/canyonos
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+ Requires-Dist: pydantic>=2.4
11
+
12
+ # canyonos-api-interface
13
+
14
+ Typed clients for the CanyonOS REST API (`/v1`), for TypeScript and Python.
15
+
16
+ A deploy's address and headers are in `~/.canyonos/deployments/<deployment>/state.json`: the API is on `http://127.0.0.1:<port>`, and every request sends its `headers`.
17
+
18
+ ## TypeScript
19
+
20
+ ```sh
21
+ npm install @canyoncode/canyonos-api-interface
22
+ ```
23
+
24
+ ```ts
25
+ import { createClient } from '@canyoncode/canyonos-api-interface';
26
+
27
+ const api = createClient('http://127.0.0.1:8000', { Authorization: 'Bearer <secret>' });
28
+ const { data, error } = await api.GET('/v1/deployments/{deployment_id}', {
29
+ params: { path: { deployment_id: '<deployment_id>' } },
30
+ });
31
+ ```
32
+
33
+ ## Python
34
+
35
+ ```sh
36
+ pip install canyonos-api-interface
37
+ ```
38
+
39
+ ```python
40
+ from canyonos_api_interface.client import Client
41
+
42
+ api = Client("http://127.0.0.1:8000", {"Authorization": "Bearer <secret>"})
43
+ status = api.status("<deployment_id>")
44
+ print(status.phase)
45
+ ```
46
+
47
+ An error answer raises `urllib.error.HTTPError`, with an `Error` as its body.
48
+
49
+ ## Versions
50
+
51
+ Each change to the API's shapes publishes a new `1.0.x` of both packages. A breaking change moves the API to `/v2` and the packages to a new major version.
@@ -0,0 +1,40 @@
1
+ # canyonos-api-interface
2
+
3
+ Typed clients for the CanyonOS REST API (`/v1`), for TypeScript and Python.
4
+
5
+ A deploy's address and headers are in `~/.canyonos/deployments/<deployment>/state.json`: the API is on `http://127.0.0.1:<port>`, and every request sends its `headers`.
6
+
7
+ ## TypeScript
8
+
9
+ ```sh
10
+ npm install @canyoncode/canyonos-api-interface
11
+ ```
12
+
13
+ ```ts
14
+ import { createClient } from '@canyoncode/canyonos-api-interface';
15
+
16
+ const api = createClient('http://127.0.0.1:8000', { Authorization: 'Bearer <secret>' });
17
+ const { data, error } = await api.GET('/v1/deployments/{deployment_id}', {
18
+ params: { path: { deployment_id: '<deployment_id>' } },
19
+ });
20
+ ```
21
+
22
+ ## Python
23
+
24
+ ```sh
25
+ pip install canyonos-api-interface
26
+ ```
27
+
28
+ ```python
29
+ from canyonos_api_interface.client import Client
30
+
31
+ api = Client("http://127.0.0.1:8000", {"Authorization": "Bearer <secret>"})
32
+ status = api.status("<deployment_id>")
33
+ print(status.phase)
34
+ ```
35
+
36
+ An error answer raises `urllib.error.HTTPError`, with an `Error` as its body.
37
+
38
+ ## Versions
39
+
40
+ Each change to the API's shapes publishes a new `1.0.x` of both packages. A breaking change moves the API to `/v2` and the packages to a new major version.
@@ -0,0 +1,5 @@
1
+ # SPDX-FileCopyrightText: 2026 Canyon Code, Inc.
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+
4
+ """Typed client for the CanyonOS REST API: `client.Client` calls its routes and
5
+ `models` holds what each route takes and answers."""
@@ -0,0 +1,161 @@
1
+ # SPDX-FileCopyrightText: 2026 Canyon Code, Inc.
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+
4
+ """Calls each CanyonOS API route with the standard library and returns its answer as
5
+ the matching model from `models`."""
6
+
7
+ import os
8
+ import urllib.request
9
+ from collections.abc import Iterator
10
+ from typing import BinaryIO, TypeVar
11
+ from urllib.parse import quote, urlencode
12
+
13
+ from pydantic import BaseModel
14
+
15
+ from canyonos_api_interface.models import (
16
+ DashboardBody,
17
+ DashboardProject,
18
+ DeploymentBody,
19
+ Deployments,
20
+ Generation,
21
+ Health,
22
+ Project,
23
+ Projects,
24
+ ReplicaLogs,
25
+ Status,
26
+ Uploaded,
27
+ )
28
+
29
+ Answer = TypeVar("Answer", bound=BaseModel)
30
+ JSON = {"Content-Type": "application/json"}
31
+
32
+
33
+ class Client:
34
+ """Calls the API at `base_url`, such as `http://127.0.0.1:8000`, sending `headers`
35
+ with every request and waiting up to `timeout` seconds (None: no limit). An error
36
+ answer raises urllib's `HTTPError`, its body an `Error`; an answer that isn't its
37
+ route's model raises pydantic's `ValidationError`."""
38
+
39
+ def __init__(
40
+ self,
41
+ base_url: str,
42
+ headers: dict[str, str] | None = None,
43
+ timeout: float | None = 60,
44
+ ):
45
+ self.base_url = base_url
46
+ self.headers = headers or {}
47
+ self.timeout = timeout
48
+
49
+ def _open(self, method, path, data=None, headers=None):
50
+ """Send `method` to `path` with body `data` and return the open response."""
51
+ request = urllib.request.Request(
52
+ self.base_url + path,
53
+ data=data,
54
+ headers={**self.headers, **(headers or {})},
55
+ method=method,
56
+ )
57
+ return urllib.request.urlopen(request, timeout=self.timeout)
58
+
59
+ def _call(
60
+ self, answer: type[Answer], method, path, data=None, headers=None
61
+ ) -> Answer:
62
+ """Send `method` to `path` with body `data` and return the answer as `answer`."""
63
+ with self._open(method, path, data, headers) as response:
64
+ return answer.model_validate_json(response.read())
65
+
66
+ def list_deployments(self) -> Deployments:
67
+ """GET /v1/deployments: the deployments the server holds."""
68
+ return self._call(Deployments, "GET", "/v1/deployments")
69
+
70
+ def status(self, deployment_id: str) -> Status:
71
+ """GET /v1/deployments/{deployment_id}: the deployment's status."""
72
+ return self._call(Status, "GET", f"/v1/deployments/{deployment_id}")
73
+
74
+ def put_deployment(self, deployment_id: str, body: DeploymentBody) -> Uploaded:
75
+ """PUT /v1/deployments/{deployment_id}: upload deployment.yaml and its .env."""
76
+ return self._call(
77
+ Uploaded,
78
+ "PUT",
79
+ f"/v1/deployments/{deployment_id}",
80
+ body.model_dump_json().encode(),
81
+ JSON,
82
+ )
83
+
84
+ def delete_deployment(self, deployment_id: str) -> Generation:
85
+ """DELETE /v1/deployments/{deployment_id}: stop the deploy and remove the
86
+ upload."""
87
+ return self._call(Generation, "DELETE", f"/v1/deployments/{deployment_id}")
88
+
89
+ def list_projects(self, deployment_id: str) -> Projects:
90
+ """GET /v1/deployments/{deployment_id}/projects: the uploaded projects."""
91
+ return self._call(Projects, "GET", f"/v1/deployments/{deployment_id}/projects")
92
+
93
+ def get_project(self, deployment_id: str, name: str) -> Project:
94
+ """GET /v1/deployments/{deployment_id}/projects/{name}: one uploaded project."""
95
+ return self._call(
96
+ Project, "GET", f"/v1/deployments/{deployment_id}/projects/{quote(name)}"
97
+ )
98
+
99
+ def put_project(self, deployment_id: str, name: str, archive: BinaryIO) -> Uploaded:
100
+ """PUT /v1/deployments/{deployment_id}/projects/{name}: upload `archive`, an
101
+ open gzip tar file of the project's folder."""
102
+ return self._call(
103
+ Uploaded,
104
+ "PUT",
105
+ f"/v1/deployments/{deployment_id}/projects/{quote(name)}",
106
+ archive,
107
+ # Without a length, urllib sends a file chunked.
108
+ {
109
+ "Content-Type": "application/gzip",
110
+ "Content-Length": str(os.fstat(archive.fileno()).st_size),
111
+ },
112
+ )
113
+
114
+ def delete_project(self, deployment_id: str, name: str) -> Generation:
115
+ """DELETE /v1/deployments/{deployment_id}/projects/{name}: remove a project."""
116
+ return self._call(
117
+ Generation,
118
+ "DELETE",
119
+ f"/v1/deployments/{deployment_id}/projects/{quote(name)}",
120
+ )
121
+
122
+ def controller_log(
123
+ self, deployment_id: str, tail: str | int = "all", follow: bool = False
124
+ ) -> Iterator[str]:
125
+ """GET /v1/deployments/{deployment_id}/logs/controller: yield the deploy
126
+ process's last `tail` lines, then with `follow` each new one until it exits."""
127
+ query = urlencode({"tail": tail, "follow": str(follow).lower()})
128
+ with self._open(
129
+ "GET", f"/v1/deployments/{deployment_id}/logs/controller?{query}"
130
+ ) as response:
131
+ for line in response:
132
+ yield line.decode(errors="replace")
133
+
134
+ def health(self, deployment_id: str) -> Health:
135
+ """GET /v1/deployments/{deployment_id}/health: check the running deploy."""
136
+ return self._call(Health, "GET", f"/v1/deployments/{deployment_id}/health")
137
+
138
+ def agent_logs(
139
+ self, deployment_id: str, name: str, tail: str | int = "all"
140
+ ) -> ReplicaLogs:
141
+ """GET /v1/deployments/{deployment_id}/logs/agents/{name}: the last `tail`
142
+ lines of each replica of agent `name`, or of the replica with that ID."""
143
+ return self._call(
144
+ ReplicaLogs,
145
+ "GET",
146
+ f"/v1/deployments/{deployment_id}/logs/agents/{quote(name)}"
147
+ f"?{urlencode({'tail': tail})}",
148
+ )
149
+
150
+ def put_dashboard(
151
+ self, deployment_id: str, body: DashboardBody
152
+ ) -> DashboardProject:
153
+ """PUT /v1/deployments/{deployment_id}/dashboard: register the deployment's
154
+ Redis with the dashboard api at `body.url`."""
155
+ return self._call(
156
+ DashboardProject,
157
+ "PUT",
158
+ f"/v1/deployments/{deployment_id}/dashboard",
159
+ body.model_dump_json().encode(),
160
+ JSON,
161
+ )
@@ -0,0 +1,204 @@
1
+ # generated by datamodel-codegen:
2
+ # filename: openapi.json
3
+
4
+ from __future__ import annotations
5
+
6
+ from typing import Literal
7
+
8
+ from pydantic import BaseModel, Field
9
+
10
+
11
+ class Error(BaseModel):
12
+ """
13
+ Every error answer; `findings` and `warnings` only come with `project_invalid`.
14
+ """
15
+
16
+ error: str = Field(..., title="Error")
17
+ code: str = Field(..., title="Code")
18
+ findings: list[str] | None = Field(None, title="Findings")
19
+ warnings: list[str] | None = Field(None, title="Warnings")
20
+
21
+
22
+ class Deployment(BaseModel):
23
+ """
24
+ `name` is what the deployment's `PUT` last sent, empty before one.
25
+ """
26
+
27
+ deployment_id: str = Field(..., title="Deployment Id")
28
+ name: str = Field(..., title="Name")
29
+
30
+
31
+ class Uploaded(BaseModel):
32
+ """
33
+ `warnings` name problems in the upload that don't stop the deploy.
34
+ """
35
+
36
+ generation: int = Field(..., title="Generation")
37
+ warnings: list[str] = Field(..., title="Warnings")
38
+
39
+
40
+ class DeploymentBody(BaseModel):
41
+ """
42
+ `config` is `deployment.yaml`'s text and `env` the `.env` beside it, null for
43
+ none. `projects`, when given, is every project the deployment has; the uploaded
44
+ projects it leaves out are removed. `api_key_hash`, when given, is the SHA-256 of the
45
+ deploy's API key, "" for none, used only on Kubernetes, where a change restarts the
46
+ deploy.
47
+ """
48
+
49
+ name: str = Field(..., title="Name")
50
+ config: str = Field(..., title="Config")
51
+ env: str | None = Field(..., title="Env")
52
+ projects: list[str] | None = Field(None, title="Projects")
53
+ api_key_hash: str | None = Field(None, title="Api Key Hash")
54
+
55
+
56
+ class Generation(BaseModel):
57
+ generation: int = Field(..., title="Generation")
58
+
59
+
60
+ class Agent(BaseModel):
61
+ desired_replicas: int = Field(..., title="Desired Replicas")
62
+ running_replicas: int = Field(..., title="Running Replicas")
63
+ launch_error: str | None = Field(..., title="Launch Error")
64
+
65
+
66
+ class LastApply(BaseModel):
67
+ """
68
+ What the apply loop last did to bring the deploy in line with `generation`.
69
+ """
70
+
71
+ generation: int = Field(..., title="Generation")
72
+ action: Literal["none", "start", "restart", "reload", "stop"] = Field(
73
+ ..., title="Action"
74
+ )
75
+ ok: bool = Field(..., title="Ok")
76
+ error: str | None = Field(..., title="Error")
77
+ code: (
78
+ Literal[
79
+ "config_invalid",
80
+ "reload_failed",
81
+ "reload_timeout",
82
+ "stop_timeout",
83
+ "stop_failed",
84
+ ]
85
+ | None
86
+ ) = Field(..., title="Code")
87
+
88
+
89
+ class Route(BaseModel):
90
+ project: str = Field(..., title="Project")
91
+ agent: str = Field(..., title="Agent")
92
+ method: str = Field(..., title="Method")
93
+ arguments: list[str] = Field(..., title="Arguments")
94
+ url: str = Field(..., title="Url")
95
+
96
+
97
+ class SlowestStep(BaseModel):
98
+ name: str = Field(..., title="Name")
99
+ seconds: float = Field(..., title="Seconds")
100
+
101
+
102
+ class Check(BaseModel):
103
+ name: str = Field(..., title="Name")
104
+ ok: bool = Field(..., title="Ok")
105
+ detail: str = Field(..., title="Detail")
106
+ fix: str | None = Field(..., title="Fix")
107
+
108
+
109
+ class Fingerprints(BaseModel):
110
+ """
111
+ Digests over a project's uploaded files: `config` over its `config/` files and
112
+ `.env`, which a reload applies, and `code` over the rest.
113
+ """
114
+
115
+ code: str = Field(..., title="Code")
116
+ config: str = Field(..., title="Config")
117
+
118
+
119
+ class Project(BaseModel):
120
+ """
121
+ `test_query` is its `config/test_query.txt`, null when it has none.
122
+ """
123
+
124
+ name: str = Field(..., title="Name")
125
+ fingerprints: Fingerprints
126
+ test_query: str | None = Field(..., title="Test Query")
127
+
128
+
129
+ class ReplicaLogs(BaseModel):
130
+ logs: dict[str, list[str]] = Field(..., title="Logs")
131
+
132
+
133
+ class DashboardProject(BaseModel):
134
+ project_id: str = Field(..., title="Project Id")
135
+ name: str = Field(..., title="Name")
136
+
137
+
138
+ class DashboardBody(BaseModel):
139
+ """
140
+ `url` is the dashboard api's address as this container reaches it.
141
+ """
142
+
143
+ url: str = Field(..., title="Url")
144
+
145
+
146
+ class Deployments(BaseModel):
147
+ deployments: list[Deployment] = Field(..., title="Deployments")
148
+
149
+
150
+ class Endpoint(BaseModel):
151
+ public_host: str = Field(..., title="Public Host")
152
+ api_port: int = Field(..., title="Api Port")
153
+ routes: list[Route] = Field(..., title="Routes")
154
+
155
+
156
+ class Health(BaseModel):
157
+ ok: bool = Field(..., title="Ok")
158
+ checks: list[Check] = Field(..., title="Checks")
159
+
160
+
161
+ class Projects(BaseModel):
162
+ projects: list[Project] = Field(..., title="Projects")
163
+
164
+
165
+ class Status(BaseModel):
166
+ """
167
+ `name` and `config` are what the deployment's `PUT` last sent, without the `.env`;
168
+ `running` is whether the deploy process is alive, so a failed deploy can still be
169
+ running while it stops itself.
170
+ """
171
+
172
+ version: str = Field(..., title="Version")
173
+ name: str = Field(..., title="Name")
174
+ config: str | None = Field(..., title="Config")
175
+ running: bool = Field(..., title="Running")
176
+ phase: Literal["starting", "up", "failed", "stopped"] | None = Field(
177
+ ..., title="Phase"
178
+ )
179
+ message: str | None = Field(..., title="Message")
180
+ steps: list[str] = Field(..., title="Steps")
181
+ slowest_step: SlowestStep | None
182
+ idle_seconds: float | None = Field(..., title="Idle Seconds")
183
+ error: str | None = Field(..., title="Error")
184
+ error_code: (
185
+ Literal[
186
+ "deploy_failed",
187
+ "deploy_incomplete",
188
+ "deploy_stopped_early",
189
+ "deploy_timeout",
190
+ "controller_exited",
191
+ ]
192
+ | None
193
+ ) = Field(..., title="Error Code")
194
+ root_cause: str | None = Field(..., title="Root Cause")
195
+ endpoint: Endpoint | None
196
+ agents: dict[str, Agent] | None = Field(..., title="Agents")
197
+ machine_errors: dict[str, str] | None = Field(..., title="Machine Errors")
198
+ generation: int = Field(..., title="Generation")
199
+ applied_generation: int = Field(..., title="Applied Generation")
200
+ applying: Literal["start", "restart", "reload", "stop"] | None = Field(
201
+ ..., title="Applying"
202
+ )
203
+ last_apply: LastApply | None
204
+ errors: list[str] = Field(..., title="Errors")
@@ -0,0 +1,51 @@
1
+ Metadata-Version: 2.4
2
+ Name: canyonos-api-interface
3
+ Version: 1.0.1
4
+ Summary: Typed client for the CanyonOS REST API
5
+ License-Expression: AGPL-3.0-only
6
+ Project-URL: Homepage, https://canyonos.ai
7
+ Project-URL: Source, https://github.com/CanyonCodeCoreAI/canyonos
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+ Requires-Dist: pydantic>=2.4
11
+
12
+ # canyonos-api-interface
13
+
14
+ Typed clients for the CanyonOS REST API (`/v1`), for TypeScript and Python.
15
+
16
+ A deploy's address and headers are in `~/.canyonos/deployments/<deployment>/state.json`: the API is on `http://127.0.0.1:<port>`, and every request sends its `headers`.
17
+
18
+ ## TypeScript
19
+
20
+ ```sh
21
+ npm install @canyoncode/canyonos-api-interface
22
+ ```
23
+
24
+ ```ts
25
+ import { createClient } from '@canyoncode/canyonos-api-interface';
26
+
27
+ const api = createClient('http://127.0.0.1:8000', { Authorization: 'Bearer <secret>' });
28
+ const { data, error } = await api.GET('/v1/deployments/{deployment_id}', {
29
+ params: { path: { deployment_id: '<deployment_id>' } },
30
+ });
31
+ ```
32
+
33
+ ## Python
34
+
35
+ ```sh
36
+ pip install canyonos-api-interface
37
+ ```
38
+
39
+ ```python
40
+ from canyonos_api_interface.client import Client
41
+
42
+ api = Client("http://127.0.0.1:8000", {"Authorization": "Bearer <secret>"})
43
+ status = api.status("<deployment_id>")
44
+ print(status.phase)
45
+ ```
46
+
47
+ An error answer raises `urllib.error.HTTPError`, with an `Error` as its body.
48
+
49
+ ## Versions
50
+
51
+ Each change to the API's shapes publishes a new `1.0.x` of both packages. A breaking change moves the API to `/v2` and the packages to a new major version.
@@ -0,0 +1,11 @@
1
+ README.md
2
+ pyproject.toml
3
+ canyonos_api_interface/__init__.py
4
+ canyonos_api_interface/client.py
5
+ canyonos_api_interface/models.py
6
+ canyonos_api_interface/py.typed
7
+ canyonos_api_interface.egg-info/PKG-INFO
8
+ canyonos_api_interface.egg-info/SOURCES.txt
9
+ canyonos_api_interface.egg-info/dependency_links.txt
10
+ canyonos_api_interface.egg-info/requires.txt
11
+ canyonos_api_interface.egg-info/top_level.txt
@@ -0,0 +1 @@
1
+ canyonos_api_interface
@@ -0,0 +1,37 @@
1
+ # SPDX-FileCopyrightText: 2026 Canyon Code, Inc.
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+
4
+ [project]
5
+ name = "canyonos-api-interface"
6
+ # The release workflow sets the patch from the commits that changed this folder.
7
+ version = "1.0.1"
8
+ description = "Typed client for the CanyonOS REST API"
9
+ readme = "README.md"
10
+ license = "AGPL-3.0-only"
11
+ requires-python = ">=3.10"
12
+ dependencies = [
13
+ "pydantic>=2.4",
14
+ ]
15
+
16
+ [project.urls]
17
+ Homepage = "https://canyonos.ai"
18
+ Source = "https://github.com/CanyonCodeCoreAI/canyonos"
19
+
20
+ [build-system]
21
+ requires = ["setuptools>=84.1.0"]
22
+ build-backend = "setuptools.build_meta"
23
+
24
+ [tool.setuptools.packages.find]
25
+ include = ["canyonos_api_interface*"]
26
+
27
+ [tool.datamodel-codegen]
28
+ input = "openapi.json"
29
+ input-file-type = "openapi"
30
+ output = "canyonos_api_interface/models.py"
31
+ output-model-type = "pydantic_v2.BaseModel"
32
+ target-python-version = "3.10"
33
+ enum-field-as-literal = "all"
34
+ use-union-operator = true
35
+ disable-timestamp = true
36
+ use-schema-description = true
37
+ formatters = ["builtin"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+