sinapsis-api 1.0.0__py3-none-any.whl

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,143 @@
1
+ from collections.abc import Sequence
2
+ from dataclasses import dataclass
3
+
4
+ from docker.models.containers import Container
5
+
6
+ import docker
7
+
8
+ from .base import (
9
+ ContainerSpec,
10
+ DockerRuntimeError,
11
+ ServiceStatus,
12
+ ensure_container,
13
+ ensure_network,
14
+ get_container,
15
+ get_container_health,
16
+ get_docker_client,
17
+ remove_container,
18
+ stop_container,
19
+ wait_for_ready,
20
+ )
21
+ from .image import ImageSpec, ensure_image
22
+
23
+
24
+ @dataclass(frozen=True, slots=True)
25
+ class DockerRuntime:
26
+ """Manage an ordered collection of Docker services.
27
+
28
+ Services are started in declaration order and stopped in reverse order,
29
+ allowing dependencies to be expressed naturally.
30
+ """
31
+
32
+ image: ImageSpec
33
+ network_name: str
34
+ services: Sequence[ContainerSpec]
35
+ label_namespace: str
36
+
37
+ @property
38
+ def managed_label(self) -> str:
39
+ """Return the label used to mark runtime-owned resources."""
40
+ return f"{self.label_namespace}.managed"
41
+
42
+ @property
43
+ def spec_fingerprint_label(self) -> str:
44
+ """Return the label used to track container configuration."""
45
+ return f"{self.label_namespace}.spec-fingerprint"
46
+
47
+ def ensure(self, client: docker.DockerClient | None = None, *, rebuild_image: bool = False) -> dict[str, Container]:
48
+ """Ensure the image, network, and all services are ready."""
49
+ client = client or get_docker_client()
50
+
51
+ ensure_image(client, self.image, rebuild=rebuild_image)
52
+
53
+ ensure_network(client, self.network_name, labels={self.managed_label: "true"})
54
+
55
+ containers: dict[str, Container] = {}
56
+
57
+ for spec in self.services:
58
+ container = ensure_container(
59
+ client,
60
+ spec,
61
+ network_name=self.network_name,
62
+ managed_label=self.managed_label,
63
+ spec_fingerprint_label=self.spec_fingerprint_label,
64
+ )
65
+
66
+ wait_for_ready(container, timeout_seconds=spec.startup_timeout_seconds)
67
+
68
+ containers[spec.name] = container
69
+
70
+ return containers
71
+
72
+ def stop(self, client: docker.DockerClient | None = None) -> None:
73
+ """Stop managed services in reverse dependency order."""
74
+ client = client or get_docker_client()
75
+
76
+ for spec in reversed(tuple(self.services)):
77
+ container = get_container(client, spec.name)
78
+
79
+ if container is None:
80
+ continue
81
+
82
+ self._verify_managed(container)
83
+ stop_container(container)
84
+
85
+ def remove(self, client: docker.DockerClient | None = None, *, remove_network: bool = False) -> None:
86
+ """Remove managed containers and optionally their network."""
87
+ client = client or get_docker_client()
88
+
89
+ for spec in reversed(tuple(self.services)):
90
+ container = get_container(client, spec.name)
91
+
92
+ if container is None:
93
+ continue
94
+
95
+ self._verify_managed(container)
96
+ remove_container(container)
97
+
98
+ if remove_network:
99
+ try:
100
+ network = client.networks.get(self.network_name)
101
+ network.remove()
102
+
103
+ except docker.errors.NotFound:
104
+ pass
105
+
106
+ except docker.errors.APIError as exc:
107
+ raise DockerRuntimeError(f"Failed to remove Docker network {self.network_name!r}.") from exc
108
+
109
+ def restart(self, client: docker.DockerClient | None = None) -> dict[str, Container]:
110
+ """Restart all services and wait until they are ready."""
111
+ client = client or get_docker_client()
112
+
113
+ self.stop(client)
114
+
115
+ return self.ensure(client)
116
+
117
+ def status(self, client: docker.DockerClient | None = None) -> dict[str, ServiceStatus]:
118
+ """Return runtime and health status for every service."""
119
+ client = client or get_docker_client()
120
+
121
+ statuses: dict[str, ServiceStatus] = {}
122
+
123
+ for spec in self.services:
124
+ container = get_container(client, spec.name)
125
+
126
+ if container is None:
127
+ statuses[spec.name] = ServiceStatus(status="missing", health=None)
128
+ continue
129
+
130
+ container.reload()
131
+
132
+ statuses[spec.name] = ServiceStatus(status=container.status, health=get_container_health(container))
133
+
134
+ return statuses
135
+
136
+ def _verify_managed(self, container: Container) -> None:
137
+ """Ensure a container is owned by this runtime."""
138
+ container.reload()
139
+
140
+ labels = container.attrs.get("Config", {}).get("Labels", {}) or {}
141
+
142
+ if labels.get(self.managed_label) != "true":
143
+ raise DockerRuntimeError(f"Container {container.name!r} is not managed by this runtime.")
@@ -0,0 +1,127 @@
1
+ from urllib.parse import urlparse
2
+
3
+ from sinapsis_api.env_vars import (
4
+ SINAPSIS_API_HOST_PORT,
5
+ SINAPSIS_API_ROUTER_AGENT_ENDPOINT,
6
+ SINAPSIS_API_ROUTER_API_ENDPOINT,
7
+ SINAPSIS_API_ROUTER_STREAM_ENDPOINT,
8
+ )
9
+
10
+ from ._file import get_installed_package_version, get_runtime_dockerfile, get_runtime_image_name
11
+ from .base import ContainerSpec, HealthCheck
12
+ from .image import ImageSpec
13
+ from .runtime import DockerRuntime
14
+
15
+ NETWORK_NAME = "sinapsis"
16
+
17
+ API_CONTAINER_NAME = "sinapsis-api"
18
+ ROUTER_CONTAINER_NAME = "sinapsis-agent-router"
19
+
20
+ LABEL_NAMESPACE = "ai.sinapsis.runtime"
21
+
22
+
23
+ def get_runtime() -> DockerRuntime:
24
+ """Return the Docker runtime for the Sinapsis API stack."""
25
+ package_version = get_installed_package_version()
26
+ image_name = get_runtime_image_name(package_version)
27
+
28
+ return DockerRuntime(
29
+ image=ImageSpec(name=image_name, dockerfile=get_runtime_dockerfile(package_version)),
30
+ network_name=NETWORK_NAME,
31
+ services=(_router_spec(image_name), _api_spec(image_name)),
32
+ label_namespace=LABEL_NAMESPACE,
33
+ )
34
+
35
+
36
+ def _router_spec(image_name: str) -> ContainerSpec:
37
+ """Return the container specification for the agent router."""
38
+ return ContainerSpec(
39
+ name=ROUTER_CONTAINER_NAME,
40
+ image=image_name,
41
+ command=("python", "-m", "sinapsis_api.agent_router"),
42
+ environment={
43
+ "SINAPSIS_API_ROUTER_API_ENDPOINT": _bind_endpoint(SINAPSIS_API_ROUTER_API_ENDPOINT),
44
+ "SINAPSIS_API_ROUTER_AGENT_ENDPOINT": _bind_endpoint(SINAPSIS_API_ROUTER_AGENT_ENDPOINT),
45
+ "SINAPSIS_API_ROUTER_STREAM_ENDPOINT": _bind_endpoint(SINAPSIS_API_ROUTER_STREAM_ENDPOINT),
46
+ },
47
+ healthcheck=HealthCheck(
48
+ command=("python", "-m", "sinapsis_api.api.healthcheck"),
49
+ interval_seconds=5,
50
+ timeout_seconds=5,
51
+ retries=10,
52
+ start_period_seconds=5,
53
+ ),
54
+ startup_timeout_seconds=60,
55
+ )
56
+
57
+
58
+ def _api_spec(image_name: str) -> ContainerSpec:
59
+ """Return the container specification for the HTTP API."""
60
+ api_port = int(SINAPSIS_API_HOST_PORT)
61
+
62
+ return ContainerSpec(
63
+ name=API_CONTAINER_NAME,
64
+ image=image_name,
65
+ command=(
66
+ "gunicorn",
67
+ "sinapsis_api.api.main:app",
68
+ "--workers",
69
+ "5",
70
+ "--worker-class",
71
+ "uvicorn.workers.UvicornWorker",
72
+ "--bind",
73
+ f"0.0.0.0:{api_port}",
74
+ "--access-logfile",
75
+ "-",
76
+ "--error-logfile",
77
+ "-",
78
+ "--log-level",
79
+ "info",
80
+ ),
81
+ environment={
82
+ "SINAPSIS_API_ROUTER_API_ENDPOINT": _service_endpoint(SINAPSIS_API_ROUTER_API_ENDPOINT),
83
+ "SINAPSIS_API_ROUTER_AGENT_ENDPOINT": _service_endpoint(SINAPSIS_API_ROUTER_AGENT_ENDPOINT),
84
+ "SINAPSIS_API_ROUTER_STREAM_ENDPOINT": _service_endpoint(SINAPSIS_API_ROUTER_STREAM_ENDPOINT),
85
+ },
86
+ ports={f"{api_port}/tcp": api_port},
87
+ healthcheck=HealthCheck(
88
+ command=(
89
+ "python",
90
+ "-c",
91
+ (
92
+ "import urllib.request; "
93
+ "urllib.request.urlopen("
94
+ f"'http://127.0.0.1:{api_port}/api/v1/health', "
95
+ "timeout=5)"
96
+ ),
97
+ ),
98
+ interval_seconds=10,
99
+ timeout_seconds=6,
100
+ retries=5,
101
+ start_period_seconds=10,
102
+ ),
103
+ startup_timeout_seconds=60,
104
+ )
105
+
106
+
107
+ def _bind_endpoint(endpoint: str) -> str:
108
+ """Return the router-side bind endpoint."""
109
+ return f"tcp://0.0.0.0:{_endpoint_port(endpoint)}"
110
+
111
+
112
+ def _service_endpoint(endpoint: str) -> str:
113
+ """Return the API-side endpoint for the router container."""
114
+ return f"tcp://{ROUTER_CONTAINER_NAME}:{_endpoint_port(endpoint)}"
115
+
116
+
117
+ def _endpoint_port(endpoint: str) -> int:
118
+ """Extract the port from a configured TCP endpoint."""
119
+ parsed = urlparse(endpoint)
120
+
121
+ if parsed.scheme != "tcp":
122
+ raise ValueError(f"Expected a TCP router endpoint, got {endpoint!r}.")
123
+
124
+ if parsed.port is None:
125
+ raise ValueError(f"Router endpoint does not define a port: {endpoint!r}.")
126
+
127
+ return parsed.port
@@ -0,0 +1,19 @@
1
+ from pydantic import BaseModel
2
+ from sinapsis.env_vars import return_docs_for_vars
3
+
4
+ from .env_vars import _SinapsisAPIEnvVars
5
+
6
+ SinapsisAPIEnvVarDefaults: BaseModel = _SinapsisAPIEnvVars()
7
+
8
+ __doc__ = return_docs_for_vars(SinapsisAPIEnvVarDefaults)
9
+
10
+
11
+ def __getattr__(name: str) -> str:
12
+ """To use as an import, when updating the value is not important"""
13
+ if name in SinapsisAPIEnvVarDefaults.model_fields:
14
+ return SinapsisAPIEnvVarDefaults.model_fields[name].default.value
15
+
16
+ raise AttributeError(f"Sinapsis API env module does not have `{name}` env var")
17
+
18
+
19
+ __all__ = (*list(SinapsisAPIEnvVarDefaults.model_fields.keys()), "SinapsisAPIEnvVarDefaults")
@@ -0,0 +1,202 @@
1
+ from pydantic import BaseModel
2
+ from sinapsis.env_vars import EnvVarEntry
3
+
4
+
5
+ class _SinapsisAPIEnvVars(BaseModel):
6
+ """Environment variable definitions for the Sinapsis API."""
7
+
8
+ SINAPSIS_PACKAGE_INDEX: EnvVarEntry = EnvVarEntry(
9
+ var_name="SINAPSIS_PACKAGE_INDEX",
10
+ default_value="https://pypi.sinapsis.ai",
11
+ description="Additional package index where sinapsis packages may live other than in the public pypi registry.",
12
+ return_type=str,
13
+ )
14
+
15
+ SINAPSIS_API_HOST_PORT: EnvVarEntry = EnvVarEntry(
16
+ var_name="SINAPSIS_API_HOST_PORT",
17
+ default_value="8000",
18
+ description="The host port of the Sinapsis API",
19
+ return_type=int,
20
+ )
21
+
22
+ SINAPSIS_API_ROUTER_API_ENDPOINT: EnvVarEntry = EnvVarEntry(
23
+ var_name="SINAPSIS_API_ROUTER_API_ENDPOINT",
24
+ default_value="tcp://127.0.0.1:8765",
25
+ description=(
26
+ "ZeroMQ endpoint exposed by the Router for API worker communication. "
27
+ "API processes use this endpoint to send commands to the Router and "
28
+ "receive command responses."
29
+ ),
30
+ return_type=str,
31
+ )
32
+
33
+ SINAPSIS_API_ROUTER_AGENT_ENDPOINT: EnvVarEntry = EnvVarEntry(
34
+ var_name="SINAPSIS_API_ROUTER_AGENT_ENDPOINT",
35
+ default_value="tcp://127.0.0.1:8766",
36
+ description=(
37
+ "ZeroMQ endpoint exposed by the Router for agent worker communication. "
38
+ "Agent subprocesses use this endpoint for commands, lifecycle messages, "
39
+ "and event delivery to the Router."
40
+ ),
41
+ return_type=str,
42
+ )
43
+
44
+ SINAPSIS_API_ROUTER_STREAM_ENDPOINT: EnvVarEntry = EnvVarEntry(
45
+ var_name="SINAPSIS_API_ROUTER_STREAM_ENDPOINT",
46
+ default_value="tcp://127.0.0.1:8767",
47
+ description=(
48
+ "ZeroMQ endpoint exposed by the Router for event-stream subscribers. "
49
+ "API workers use this endpoint to request retained event replay and "
50
+ "subscribe to live agent events."
51
+ ),
52
+ return_type=str,
53
+ )
54
+
55
+ SINAPSIS_API_EVENT_RETENTION_SECONDS: EnvVarEntry = EnvVarEntry(
56
+ var_name="SINAPSIS_API_EVENT_RETENTION_SECONDS",
57
+ default_value=3600.0,
58
+ description=(
59
+ "Maximum age, in seconds, of events retained in each agent's rolling "
60
+ "journal. Events older than this value are eligible for eviction."
61
+ ),
62
+ return_type=float,
63
+ )
64
+
65
+ SINAPSIS_API_EVENT_MAX_EVENTS_PER_AGENT: EnvVarEntry = EnvVarEntry(
66
+ var_name="SINAPSIS_API_EVENT_MAX_EVENTS_PER_AGENT",
67
+ default_value=10_000,
68
+ description=(
69
+ "Maximum number of events retained in a single agent's rolling journal. "
70
+ "When the limit is exceeded, the oldest retained events are evicted."
71
+ ),
72
+ return_type=int,
73
+ )
74
+
75
+ SINAPSIS_API_EVENT_MAX_BYTES_PER_AGENT: EnvVarEntry = EnvVarEntry(
76
+ var_name="SINAPSIS_API_EVENT_MAX_BYTES_PER_AGENT",
77
+ default_value=256 * 1024 * 1024,
78
+ description=(
79
+ "Maximum cumulative size, in bytes, of serialized event payloads retained "
80
+ "in a single agent's rolling journal. The oldest events are evicted when "
81
+ "the journal exceeds this limit."
82
+ ),
83
+ return_type=int,
84
+ )
85
+
86
+ SINAPSIS_API_EVENT_MAX_BYTES: EnvVarEntry = EnvVarEntry(
87
+ var_name="SINAPSIS_API_EVENT_MAX_BYTES",
88
+ default_value=100 * 1024 * 1024,
89
+ description=(
90
+ "Maximum serialized payload size, in bytes, accepted for an individual "
91
+ "agent event. Events exceeding this limit are rejected instead of being "
92
+ "added to the agent journal."
93
+ ),
94
+ return_type=int,
95
+ )
96
+
97
+ SINAPSIS_API_EVENT_REPLAY_LIMIT: EnvVarEntry = EnvVarEntry(
98
+ var_name="SINAPSIS_API_EVENT_REPLAY_LIMIT",
99
+ default_value=1000,
100
+ description=(
101
+ "Maximum number of retained events returned in a single replay page. "
102
+ "Larger replays are paginated and continue from the last returned cursor."
103
+ ),
104
+ return_type=int,
105
+ )
106
+
107
+ SINAPSIS_API_EVENT_REPLAY_MAX_BYTES: EnvVarEntry = EnvVarEntry(
108
+ var_name="SINAPSIS_API_EVENT_REPLAY_MAX_BYTES",
109
+ default_value=64 * 1024 * 1024,
110
+ description=(
111
+ "Maximum cumulative serialized payload size, in bytes, returned in a "
112
+ "single event replay page. Replay continues on a subsequent page when "
113
+ "additional retained events remain."
114
+ ),
115
+ return_type=int,
116
+ )
117
+
118
+ SINAPSIS_API_SUBSCRIBER_QUEUE_SIZE: EnvVarEntry = EnvVarEntry(
119
+ var_name="SINAPSIS_API_SUBSCRIBER_QUEUE_SIZE",
120
+ default_value=1024,
121
+ description=(
122
+ "Maximum number of live events buffered for an individual event "
123
+ "subscriber. A subscriber that cannot consume events before this queue "
124
+ "fills is treated as lagging without blocking other subscribers."
125
+ ),
126
+ return_type=int,
127
+ )
128
+
129
+ SINAPSIS_API_AGENT_START_TIMEOUT_SECONDS: EnvVarEntry = EnvVarEntry(
130
+ var_name="SINAPSIS_API_AGENT_START_TIMEOUT_SECONDS",
131
+ default_value=15.0,
132
+ description=(
133
+ "Maximum time, in seconds, the Router waits for a newly spawned agent "
134
+ "subprocess to report that it is ready before considering startup failed."
135
+ ),
136
+ return_type=float,
137
+ )
138
+
139
+ SINAPSIS_API_STOPPED_AGENT_RETENTION_SECONDS: EnvVarEntry = EnvVarEntry(
140
+ var_name="SINAPSIS_API_STOPPED_AGENT_RETENTION_SECONDS",
141
+ default_value=86_400.0,
142
+ description=(
143
+ "Maximum time, in seconds, to retain a stopped agent's journal and "
144
+ "associated Router state. This allows retained events to remain available "
145
+ "for replay after the agent process has exited."
146
+ ),
147
+ return_type=float,
148
+ )
149
+
150
+ SINAPSIS_API_JOURNAL_GC_INTERVAL_SECONDS: EnvVarEntry = EnvVarEntry(
151
+ var_name="SINAPSIS_API_JOURNAL_GC_INTERVAL_SECONDS",
152
+ default_value=30.0,
153
+ description=(
154
+ "Interval, in seconds, between Router garbage-collection passes that "
155
+ "remove expired event data and purge stopped-agent journals whose "
156
+ "retention period has elapsed."
157
+ ),
158
+ return_type=float,
159
+ )
160
+
161
+ SINAPSIS_API_WORKER_OUTBOUND_QUEUE_SIZE: EnvVarEntry = EnvVarEntry(
162
+ var_name="SINAPSIS_API_WORKER_OUTBOUND_QUEUE_SIZE",
163
+ default_value=1024,
164
+ description=(
165
+ "Maximum number of outbound event and control messages buffered inside "
166
+ "an agent subprocess while waiting to send them to the Router. The shared "
167
+ "FIFO queue preserves event and job-state ordering."
168
+ ),
169
+ return_type=int,
170
+ )
171
+
172
+ SINAPSIS_API_COMMAND_CACHE_SIZE: EnvVarEntry = EnvVarEntry(
173
+ var_name="SINAPSIS_API_COMMAND_CACHE_SIZE",
174
+ default_value=10_000,
175
+ description=(
176
+ "Maximum number of processed command identifiers retained by the Router "
177
+ "for command deduplication and idempotent command handling."
178
+ ),
179
+ return_type=int,
180
+ )
181
+
182
+ SINAPSIS_API_ZMQ_SEND_HWM: EnvVarEntry = EnvVarEntry(
183
+ var_name="SINAPSIS_API_ZMQ_SEND_HWM",
184
+ default_value=1024,
185
+ description=(
186
+ "ZeroMQ send high-water mark used by Sinapsis API IPC sockets. It limits "
187
+ "the number of outbound messages ZeroMQ may queue before applying "
188
+ "backpressure."
189
+ ),
190
+ return_type=int,
191
+ )
192
+
193
+ SINAPSIS_API_ZMQ_RECEIVE_HWM: EnvVarEntry = EnvVarEntry(
194
+ var_name="SINAPSIS_API_ZMQ_RECEIVE_HWM",
195
+ default_value=1024,
196
+ description=(
197
+ "ZeroMQ receive high-water mark used by Sinapsis API IPC sockets. It "
198
+ "limits the number of inbound messages ZeroMQ may queue for a socket "
199
+ "before applying its configured queueing behavior."
200
+ ),
201
+ return_type=int,
202
+ )