runara 0.1.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.
runara/__init__.py ADDED
@@ -0,0 +1,39 @@
1
+ """Fine-tune open models on Runara. You write the training loop; we hold the weights.
2
+
3
+ import runara
4
+
5
+ sc = runara.ServiceClient(api_key="rk_live_...")
6
+ tc = sc.create_lora_training_client(base_model="qwen3.5-4b", rank=32)
7
+
8
+ Your data stays on your machine. Only token ids and per-token loss weights
9
+ cross the wire — see `runara_cookbook` for turning your files into those.
10
+ """
11
+
12
+ from ._futures import Future
13
+ from ._http import InsufficientBalance, RunaraError, SessionClosed
14
+ from .client import ServiceClient, TrainingClient
15
+ from .types import (
16
+ AdamParams,
17
+ Checkpoint,
18
+ Datum,
19
+ ForwardBackwardResult,
20
+ ModelInfo,
21
+ SampleResult,
22
+ )
23
+
24
+ __version__ = "0.1.0"
25
+
26
+ __all__ = [
27
+ "AdamParams",
28
+ "Checkpoint",
29
+ "Datum",
30
+ "ForwardBackwardResult",
31
+ "Future",
32
+ "InsufficientBalance",
33
+ "ModelInfo",
34
+ "RunaraError",
35
+ "SampleResult",
36
+ "ServiceClient",
37
+ "SessionClosed",
38
+ "TrainingClient",
39
+ ]
runara/_futures.py ADDED
@@ -0,0 +1,64 @@
1
+ """Futures that let a training loop stay ahead of the network.
2
+
3
+ A step is two calls — ``forward_backward`` then ``optim_step`` — and a loop
4
+ that awaits each one spends most of its wall-clock time waiting for a round
5
+ trip while the GPU sits idle. The worker already guarantees that calls for one
6
+ session are applied in the order they arrive, so the client can submit both and
7
+ collect later.
8
+
9
+ That ordering guarantee is what makes this safe, and it is the worker's
10
+ per-session lock that provides it. Without it, two in-flight calls would race
11
+ on the same adapter and the optimizer could apply a step before the gradients
12
+ it was meant to apply.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from concurrent.futures import Future as _Future
18
+ from concurrent.futures import ThreadPoolExecutor
19
+ from typing import Callable, Generic, TypeVar
20
+
21
+ T = TypeVar("T")
22
+
23
+
24
+ class Future(Generic[T]):
25
+ """A submitted request. Call ``result()`` when you actually need the value.
26
+
27
+ Deliberately thin: it is one outstanding HTTP request, not a task in a
28
+ scheduler. There is no polling, no result store and no reconnection
29
+ protocol, because there is nothing to reconnect to — the request either
30
+ returns or raises.
31
+ """
32
+
33
+ def __init__(self, inner: _Future) -> None:
34
+ self._inner = inner
35
+
36
+ def result(self, timeout: float | None = None) -> T:
37
+ """Block until the worker answers, re-raising whatever it raised."""
38
+ return self._inner.result(timeout)
39
+
40
+ def done(self) -> bool:
41
+ return self._inner.done()
42
+
43
+ def __repr__(self) -> str: # pragma: no cover - debugging convenience
44
+ state = "done" if self.done() else "pending"
45
+ return f"<runara.Future {state}>"
46
+
47
+
48
+ class Submitter:
49
+ """Runs requests for one session, one at a time, in submission order.
50
+
51
+ A single worker thread rather than a pool: the ordering the protocol
52
+ promises is per session, and a pool would let two requests for the same
53
+ session overlap. Pipelining comes from the client not blocking, not from
54
+ the requests running concurrently.
55
+ """
56
+
57
+ def __init__(self) -> None:
58
+ self._pool = ThreadPoolExecutor(max_workers=1, thread_name_prefix="runara")
59
+
60
+ def submit(self, fn: Callable[..., T], *args, **kwargs) -> Future[T]:
61
+ return Future(self._pool.submit(fn, *args, **kwargs))
62
+
63
+ def close(self) -> None:
64
+ self._pool.shutdown(wait=True)
runara/_http.py ADDED
@@ -0,0 +1,155 @@
1
+ """HTTP, with the retry policy spelled out.
2
+
3
+ Two different endpoints with different failure characters:
4
+
5
+ * The **control plane** creates sessions and lists checkpoints. Slow, rare,
6
+ and safe to retry only because session creation is idempotent on a request
7
+ id the client generates.
8
+ * The **worker** runs the training calls. Fast, frequent, and **not** safe to
9
+ retry: a ``forward_backward`` that timed out may well have applied its
10
+ gradients, and sending it again would train on the same batch twice. So the
11
+ worker path retries only on errors that prove the request never arrived.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import os
18
+ import ssl
19
+ import tempfile
20
+ import time
21
+ import urllib.error
22
+ import urllib.request
23
+ from typing import Any
24
+
25
+ #: Only these are retried on the worker path: the request did not land.
26
+ _CONNECTION_ERRORS = (urllib.error.URLError, TimeoutError, ConnectionError)
27
+
28
+
29
+ class _PinnedWorker:
30
+ """A TLS context that trusts one worker's certificate and nothing else.
31
+
32
+ A training worker is rented for minutes at an address we do not own, so
33
+ there is no public certificate for it and no DNS name to put in one. The
34
+ control plane, which we do authenticate normally, tells us the exact
35
+ certificate the worker will present; this trusts that and only that.
36
+
37
+ That is stronger than the usual path rather than weaker. A public CA would
38
+ vouch for anyone who could prove control of the address; this vouches for
39
+ the one machine the control plane placed our session on. The alternative
40
+ actually on offer — ``verify=False`` — would leave the training tokens on
41
+ the wire readable by anyone between here and the GPU.
42
+ """
43
+
44
+ def __init__(self, cert_pem: str):
45
+ if not cert_pem.startswith("-----BEGIN CERTIFICATE-----"):
46
+ raise ValueError("worker certificate is not PEM")
47
+ # NamedTemporaryFile because SSLContext loads CAs from a path. Written
48
+ # 0600 and removed when the client is done with it.
49
+ handle = tempfile.NamedTemporaryFile(
50
+ "w", suffix=".pem", prefix="runara-worker-", delete=False
51
+ )
52
+ try:
53
+ os.chmod(handle.name, 0o600)
54
+ handle.write(cert_pem)
55
+ finally:
56
+ handle.close()
57
+ self._path = handle.name
58
+
59
+ context = ssl.create_default_context(cafile=self._path)
60
+ context.minimum_version = ssl.TLSVersion.TLSv1_2
61
+ # The certificate carries the worker's IP in its SAN, so the hostname
62
+ # check is a real check and stays on.
63
+ context.check_hostname = True
64
+ context.verify_mode = ssl.CERT_REQUIRED
65
+ self.context = context
66
+
67
+ def close(self) -> None:
68
+ try:
69
+ os.unlink(self._path)
70
+ except OSError:
71
+ pass
72
+
73
+
74
+ class RunaraError(Exception):
75
+ """An error the service reported, with its code where there is one."""
76
+
77
+ def __init__(self, message: str, *, status: int | None = None, code: str | None = None):
78
+ super().__init__(message)
79
+ self.status = status
80
+ self.code = code
81
+
82
+
83
+ class InsufficientBalance(RunaraError):
84
+ """The organization is out of credit. Training stops until it is topped up."""
85
+
86
+
87
+ class SessionClosed(RunaraError):
88
+ """The session has ended, or is ending because the balance ran out."""
89
+
90
+
91
+ def _raise_for(status: int, body: Any, url: str) -> None:
92
+ error = body.get("error") if isinstance(body, dict) else None
93
+ code = error.get("code") if isinstance(error, dict) else (error if isinstance(error, str) else None)
94
+ message = error.get("message") if isinstance(error, dict) else str(error or body)
95
+
96
+ if status == 402 or code == "INSUFFICIENT_BALANCE":
97
+ raise InsufficientBalance(message, status=status, code=code)
98
+ if code in {"session_closed", "session_closing", "session_not_resident"}:
99
+ raise SessionClosed(message, status=status, code=code)
100
+ raise RunaraError(f"{message} ({url.rsplit('/', 1)[-1]})", status=status, code=code)
101
+
102
+
103
+ def request(
104
+ method: str,
105
+ url: str,
106
+ token: str,
107
+ body: dict | None = None,
108
+ *,
109
+ timeout: float = 600.0,
110
+ retries: int = 0,
111
+ ssl_context: ssl.SSLContext | None = None,
112
+ ) -> Any:
113
+ """One request, retried only when it provably did not arrive.
114
+
115
+ `retries` defaults to zero. The caller decides, because only the caller
116
+ knows whether repeating the call is safe — and for a training step it is
117
+ not: a timed-out forward_backward may have already applied its gradients.
118
+ """
119
+ payload = json.dumps(body).encode() if body is not None else None
120
+ attempt = 0
121
+ while True:
122
+ http_request = urllib.request.Request(
123
+ url,
124
+ data=payload,
125
+ method=method,
126
+ headers={
127
+ "Authorization": f"Bearer {token}",
128
+ "Content-Type": "application/json",
129
+ "User-Agent": "runara-python",
130
+ },
131
+ )
132
+ try:
133
+ with urllib.request.urlopen(
134
+ http_request, timeout=timeout, context=ssl_context
135
+ ) as response:
136
+ raw = response.read()
137
+ return json.loads(raw) if raw else {}
138
+ except urllib.error.HTTPError as error:
139
+ try:
140
+ parsed = json.loads(error.read())
141
+ except Exception: # noqa: BLE001 - a non-JSON error body is still an error
142
+ parsed = {"error": {"message": error.reason}}
143
+ # A 503 means the worker is still loading its weights; that is a
144
+ # wait, not a failure, and the request never reached the model.
145
+ if error.code == 503 and attempt < retries:
146
+ attempt += 1
147
+ time.sleep(min(2**attempt, 10))
148
+ continue
149
+ _raise_for(error.code, parsed, url)
150
+ except _CONNECTION_ERRORS as error:
151
+ if attempt < retries:
152
+ attempt += 1
153
+ time.sleep(min(2**attempt, 10))
154
+ continue
155
+ raise RunaraError(f"Could not reach {url.rsplit('/', 2)[0]}: {error}") from error
runara/client.py ADDED
@@ -0,0 +1,286 @@
1
+ """The client. Four primitives against base weights you never have to host.
2
+
3
+ import runara
4
+
5
+ sc = runara.ServiceClient(api_key="rk_live_...")
6
+ tc = sc.create_lora_training_client(base_model="qwen3.5-4b", rank=32)
7
+
8
+ for batch in batches:
9
+ fb = tc.forward_backward(batch) # submitted, not awaited
10
+ tc.optim_step(runara.AdamParams(1e-4)) # submitted straight after
11
+ print(fb.result().loss) # the loop blocks here
12
+
13
+ tc.save_state(name="support-v1")
14
+
15
+ Your data never leaves your machine as text. The cookbook turns whatever you
16
+ have into `Datum`s locally, and only token ids and loss weights are sent.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import os
22
+ import time
23
+ import uuid
24
+ from dataclasses import dataclass
25
+
26
+ from . import _http
27
+ from ._futures import Future, Submitter
28
+ from .types import (
29
+ AdamParams,
30
+ Checkpoint,
31
+ Datum,
32
+ ForwardBackwardResult,
33
+ ModelInfo,
34
+ SampleResult,
35
+ )
36
+
37
+ DEFAULT_BASE_URL = "https://runara.ai/api/v1"
38
+ #: Refresh this far before expiry, so a long call cannot start on a token that
39
+ #: dies mid-flight.
40
+ TOKEN_REFRESH_MARGIN_SECONDS = 120
41
+
42
+
43
+ class ServiceClient:
44
+ """Your account. Opens training sessions and reads what you have saved."""
45
+
46
+ def __init__(self, api_key: str | None = None, base_url: str | None = None) -> None:
47
+ key = api_key or os.environ.get("RUNARA_API_KEY")
48
+ if not key:
49
+ raise ValueError(
50
+ "No API key. Pass api_key=... or set RUNARA_API_KEY. "
51
+ "Create one in the Runara console under Settings."
52
+ )
53
+ self.api_key = key
54
+ self.base_url = (base_url or os.environ.get("RUNARA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
55
+
56
+ # -- catalog -----------------------------------------------------------
57
+
58
+ def list_models(self) -> list[ModelInfo]:
59
+ """Base models open for training, with their per-token prices.
60
+
61
+ A fixed catalog rather than any HuggingFace id: the weights have to be
62
+ already resident on a worker for sessions to share them, which is what
63
+ makes per-token pricing possible at all.
64
+ """
65
+ body = self._control("GET", "/finetune/models")
66
+ return [
67
+ ModelInfo(
68
+ base_model=row["base_model"],
69
+ repository=row["repository"],
70
+ max_rank=row["max_rank"],
71
+ max_seq_len=row["max_seq_len"],
72
+ default_target_modules=row["default_target_modules"],
73
+ train_usd_per_million=row["train_usd_per_million"],
74
+ sample_usd_per_million=row["sample_usd_per_million"],
75
+ )
76
+ for row in body["data"]
77
+ ]
78
+
79
+ def list_checkpoints(self, base_model: str | None = None) -> list[Checkpoint]:
80
+ path = "/finetune/checkpoints"
81
+ if base_model:
82
+ path += f"?base_model={base_model}"
83
+ body = self._control("GET", path)
84
+ return [Checkpoint(**row) for row in body["data"]]
85
+
86
+ # -- sessions ----------------------------------------------------------
87
+
88
+ def create_lora_training_client(
89
+ self,
90
+ base_model: str,
91
+ rank: int = 32,
92
+ *,
93
+ alpha: int | None = None,
94
+ target_modules: list[str] | None = None,
95
+ method: str = "lora",
96
+ request_id: str | None = None,
97
+ ) -> "TrainingClient":
98
+ """Open a session and get a client for it.
99
+
100
+ `request_id` makes this idempotent. One is generated if you do not
101
+ supply it, so a retry after a timeout returns the session you already
102
+ have rather than opening a second one you would also be billed for.
103
+ """
104
+ payload = {
105
+ "request_id": request_id or f"sdk-{uuid.uuid4().hex}",
106
+ "base_model": base_model,
107
+ "rank": rank,
108
+ "method": method,
109
+ }
110
+ if alpha is not None:
111
+ payload["alpha"] = alpha
112
+ if target_modules is not None:
113
+ payload["target_modules"] = target_modules
114
+
115
+ body = self._control("POST", "/finetune/sessions", payload)
116
+ return TrainingClient(
117
+ service=self,
118
+ session_id=body["session_id"],
119
+ worker_url=body["worker_url"].rstrip("/"),
120
+ token=body["session_token"],
121
+ token_expires_at=body["expires_at"],
122
+ # The worker is rented for minutes at an address nobody owns, so
123
+ # there is no public certificate for it. The control plane, which
124
+ # we authenticate normally, tells us exactly which certificate it
125
+ # will present; we trust that one and refuse anything else.
126
+ worker_cert_pem=body["worker_cert_pem"],
127
+ )
128
+
129
+ # -- plumbing ----------------------------------------------------------
130
+
131
+ def _control(self, method: str, path: str, body: dict | None = None):
132
+ # The control plane is retried: these calls are rare, and the one that
133
+ # mutates anything is idempotent on request_id.
134
+ return _http.request(
135
+ method, self.base_url + path, self.api_key, body, timeout=60.0, retries=2
136
+ )
137
+
138
+
139
+ @dataclass
140
+ class _SessionToken:
141
+ value: str
142
+ expires_at: int
143
+
144
+ def stale(self, now_ms: float) -> bool:
145
+ return self.expires_at - now_ms < TOKEN_REFRESH_MARGIN_SECONDS * 1000
146
+
147
+
148
+ class TrainingClient:
149
+ """One training session. The four primitives, and the loop is yours."""
150
+
151
+ def __init__(
152
+ self,
153
+ service: ServiceClient,
154
+ session_id: str,
155
+ worker_url: str,
156
+ token: str,
157
+ token_expires_at: int,
158
+ worker_cert_pem: str,
159
+ ) -> None:
160
+ self.service = service
161
+ self.session_id = session_id
162
+ if not worker_url.startswith("https://"):
163
+ # Never negotiable. This connection carries the customer's
164
+ # training tokens, and a plaintext worker_url would hand them to
165
+ # anyone on the path while everything still appeared to work.
166
+ raise ValueError(f"worker_url must be https, got {worker_url!r}")
167
+ self.worker_url = worker_url
168
+ self._token = _SessionToken(token, token_expires_at)
169
+ self._pinned = _http._PinnedWorker(worker_cert_pem)
170
+ self._submitter = Submitter()
171
+
172
+ # -- the primitives ----------------------------------------------------
173
+
174
+ def forward_backward(
175
+ self, data: list[Datum], loss_fn: str = "cross_entropy"
176
+ ) -> Future[ForwardBackwardResult]:
177
+ """Accumulate gradients for one batch. Returns immediately.
178
+
179
+ Submit this and `optim_step` back to back without awaiting: the worker
180
+ applies calls for a session in the order they arrive, so the network
181
+ round trip overlaps your next batch of tokenization instead of
182
+ stalling the GPU.
183
+ """
184
+ payload = {"data": [datum.to_wire() for datum in data], "loss_fn": loss_fn}
185
+
186
+ def run() -> ForwardBackwardResult:
187
+ body = self._call("forward_backward", payload)
188
+ return ForwardBackwardResult(
189
+ loss=body["loss"],
190
+ metrics=body.get("metrics", {}),
191
+ seq_count=body.get("seq_count", len(data)),
192
+ token_count=body.get("token_count", 0),
193
+ )
194
+
195
+ return self._submitter.submit(run)
196
+
197
+ def optim_step(self, params: AdamParams) -> Future[int]:
198
+ """Apply the accumulated gradients. Returns the new step number."""
199
+
200
+ def run() -> int:
201
+ return self._call("optim_step", {"adam": params.to_wire()})["step"]
202
+
203
+ return self._submitter.submit(run)
204
+
205
+ def sample(
206
+ self,
207
+ prompts: list[list[int]],
208
+ max_tokens: int = 64,
209
+ temperature: float = 1.0,
210
+ ) -> Future[SampleResult]:
211
+ """Generate from the adapter as it stands, without ending the session."""
212
+
213
+ def run() -> SampleResult:
214
+ body = self._call(
215
+ "sample",
216
+ {"prompts": prompts, "max_tokens": max_tokens, "temperature": temperature},
217
+ )
218
+ return SampleResult(
219
+ sequences=body["sequences"], token_count=body.get("token_count", 0)
220
+ )
221
+
222
+ return self._submitter.submit(run)
223
+
224
+ def save_state(self, name: str) -> Future[dict]:
225
+ """Save the adapter. Blocks on everything you submitted before it.
226
+
227
+ Ordering matters here more than anywhere: saving before your last
228
+ optim_step has been applied would write a checkpoint one step behind
229
+ what you think you trained. The worker's per-session ordering gives
230
+ that for free, which is why this goes through the same queue.
231
+ """
232
+
233
+ def run() -> dict:
234
+ return self._call("save_state", {"name": name})
235
+
236
+ return self._submitter.submit(run)
237
+
238
+ # -- session -----------------------------------------------------------
239
+
240
+ def status(self) -> dict:
241
+ return self.service._control("GET", f"/finetune/sessions/{self.session_id}")
242
+
243
+ def close(self) -> None:
244
+ """End the session and release its slot on the worker.
245
+
246
+ Worth doing explicitly: an abandoned session holds an adapter slot
247
+ until the watchdog reclaims it half an hour later.
248
+ """
249
+ try:
250
+ self.service._control("DELETE", f"/finetune/sessions/{self.session_id}")
251
+ finally:
252
+ self._submitter.close()
253
+ # The pinned certificate lives in a temp file; remove it.
254
+ self._pinned.close()
255
+
256
+ def __enter__(self) -> "TrainingClient":
257
+ return self
258
+
259
+ def __exit__(self, *_exc) -> None:
260
+ self.close()
261
+
262
+ # -- plumbing ----------------------------------------------------------
263
+
264
+ def _call(self, action: str, payload: dict) -> dict:
265
+ token = self._fresh_token()
266
+ # retries=0: a forward_backward that timed out may already have applied
267
+ # its gradients, and sending it again would train on the batch twice.
268
+ return _http.request(
269
+ "POST",
270
+ f"{self.worker_url}/v1/sessions/{self.session_id}/{action}",
271
+ token,
272
+ payload,
273
+ retries=0,
274
+ ssl_context=self._pinned.context,
275
+ )
276
+
277
+ def _fresh_token(self) -> str:
278
+ if not self._token.stale(time.time() * 1000):
279
+ return self._token.value
280
+ body = self.service._control(
281
+ "POST", f"/finetune/sessions/{self.session_id}/token"
282
+ )
283
+ self._token = _SessionToken(body["session_token"], body["expires_at"])
284
+ # The worker can move between refreshes in principle; follow it.
285
+ self.worker_url = body.get("worker_url", self.worker_url).rstrip("/")
286
+ return self._token.value
runara/types.py ADDED
@@ -0,0 +1,111 @@
1
+ """The wire types.
2
+
3
+ A ``Datum`` is the whole of what leaves your machine for a training call:
4
+ token ids and a per-token loss weight. Not your text, not your filenames, not
5
+ your dataset. The cookbook builds these locally from whatever you have, and
6
+ you can print one before sending it.
7
+
8
+ The alignment convention is the part worth reading twice. ``token_ids`` is the
9
+ input and ``target_tokens`` is what the model should predict at each position,
10
+ already shifted so that position *i* of one lines up with position *i* of the
11
+ other. The cookbook does that shift for you. If you build data by hand and get
12
+ it wrong, nothing errors: the model trains toward the wrong token and the loss
13
+ curve looks entirely normal.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from dataclasses import dataclass, field
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Datum:
23
+ """One training example."""
24
+
25
+ token_ids: list[int]
26
+ target_tokens: list[int]
27
+ #: 1.0 for a token to train on, 0.0 to ignore. Prompt tokens are usually 0.
28
+ weights: list[float]
29
+
30
+ def __post_init__(self) -> None:
31
+ if not self.token_ids:
32
+ raise ValueError("Datum has no tokens")
33
+ if not (len(self.token_ids) == len(self.target_tokens) == len(self.weights)):
34
+ raise ValueError(
35
+ "token_ids, target_tokens and weights must be the same length; "
36
+ f"got {len(self.token_ids)}, {len(self.target_tokens)}, {len(self.weights)}. "
37
+ "They describe the same positions, already shifted."
38
+ )
39
+
40
+ @property
41
+ def trained_tokens(self) -> int:
42
+ """Tokens that carry loss. This is what you are billed for."""
43
+ return sum(1 for weight in self.weights if weight > 0)
44
+
45
+ def to_wire(self) -> dict:
46
+ return {
47
+ "token_ids": self.token_ids,
48
+ "target_tokens": self.target_tokens,
49
+ "weights": self.weights,
50
+ }
51
+
52
+
53
+ @dataclass(frozen=True)
54
+ class AdamParams:
55
+ """Optimizer settings for one step. The schedule is yours to decide."""
56
+
57
+ learning_rate: float
58
+ beta1: float = 0.9
59
+ beta2: float = 0.95
60
+ eps: float = 1e-8
61
+ weight_decay: float = 0.0
62
+
63
+ def to_wire(self) -> dict:
64
+ return {
65
+ "learning_rate": self.learning_rate,
66
+ "beta1": self.beta1,
67
+ "beta2": self.beta2,
68
+ "eps": self.eps,
69
+ "weight_decay": self.weight_decay,
70
+ }
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class ForwardBackwardResult:
75
+ loss: float
76
+ metrics: dict
77
+ seq_count: int
78
+ #: Trained tokens in this batch — the billable quantity.
79
+ token_count: int
80
+
81
+
82
+ @dataclass(frozen=True)
83
+ class SampleResult:
84
+ sequences: list[list[int]]
85
+ token_count: int
86
+
87
+
88
+ @dataclass(frozen=True)
89
+ class Checkpoint:
90
+ checkpoint_id: str
91
+ name: str
92
+ kind: str
93
+ step: int
94
+ base_model: str
95
+ base_model_repository: str
96
+ rank: int
97
+ size_bytes: int
98
+ files: list[dict] = field(default_factory=list)
99
+ created_at: int = 0
100
+ expires_at: int | None = None
101
+
102
+
103
+ @dataclass(frozen=True)
104
+ class ModelInfo:
105
+ base_model: str
106
+ repository: str
107
+ max_rank: int
108
+ max_seq_len: int
109
+ default_target_modules: list[str]
110
+ train_usd_per_million: float
111
+ sample_usd_per_million: float
@@ -0,0 +1,115 @@
1
+ Metadata-Version: 2.4
2
+ Name: runara
3
+ Version: 0.1.0
4
+ Summary: Fine-tune open models on Runara. You write the training loop.
5
+ Author: Runara
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://runara.ai
8
+ Project-URL: Source, https://github.com/Runaraai/runara-python
9
+ Keywords: llm,fine-tuning,lora,training
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
14
+ Requires-Python: >=3.10
15
+ Description-Content-Type: text/markdown
16
+ Provides-Extra: cookbook
17
+ Requires-Dist: transformers>=4.45; extra == "cookbook"
18
+ Provides-Extra: dev
19
+ Requires-Dist: pytest>=8.0; extra == "dev"
20
+
21
+ # runara
22
+
23
+ Fine-tune open models without hosting them. You write the training loop; we
24
+ hold the base weights and run the forward and backward passes.
25
+
26
+ ```bash
27
+ pip install runara runara-cookbook
28
+ ```
29
+
30
+ ```python
31
+ import runara
32
+ from runara_cookbook import renderers
33
+
34
+ sc = runara.ServiceClient(api_key="rk_live_...")
35
+ tc = sc.create_lora_training_client(base_model="qwen3.5-4b", rank=32)
36
+
37
+ renderer = renderers.get("qwen3_5", tokenizer=tc.get_tokenizer())
38
+ rows = [json.loads(line) for line in open("my_tickets.jsonl")] # your disk
39
+
40
+ for epoch in range(3):
41
+ for chunk in batches(rows, 8):
42
+ data = [renderer.to_datum(row["messages"]) for row in chunk]
43
+ fb = tc.forward_backward(data) # submitted, not awaited
44
+ tc.optim_step(runara.AdamParams(1e-4)) # submitted straight after
45
+ print(fb.result().loss) # the loop blocks here
46
+
47
+ tc.save_state(name="support-v1")
48
+ ```
49
+
50
+ ## Your data does not leave your machine
51
+
52
+ `open(...)` runs on your computer. The cookbook tokenizes locally and builds a
53
+ per-token loss mask, so what crosses the wire is a list of integers and a list
54
+ of floats — no text, no filenames, no schema. A two-turn conversation is about
55
+ 900 bytes of that.
56
+
57
+ You can check this yourself before sending anything:
58
+
59
+ ```python
60
+ datum = renderer.to_datum(messages)
61
+ print(datum.token_ids) # integers
62
+ print(datum.weights) # 0.0 for the prompt, 1.0 for what you train on
63
+ ```
64
+
65
+ What we do keep is the adapter you write with `save_state`, plus token counts
66
+ and loss values for billing and the charts in the console.
67
+
68
+ ## Why the loop is yours
69
+
70
+ There is no job to submit and no config to fill in. You decide the batching,
71
+ the schedule, when to stop, and what the loss means. That is more work than a
72
+ managed API and it is the point: it is the difference between tuning a model
73
+ and filling in a form.
74
+
75
+ `forward_backward` and `optim_step` both return immediately. Submit them back
76
+ to back and collect later — the worker applies calls for a session in the
77
+ order they arrive, so the round trip overlaps your next batch of tokenization
78
+ instead of stalling the GPU.
79
+
80
+ ## What you get out
81
+
82
+ ```python
83
+ for checkpoint in sc.list_checkpoints():
84
+ print(checkpoint.name, checkpoint.size_bytes, checkpoint.base_model)
85
+ ```
86
+
87
+ Checkpoints are standard PEFT adapters — `adapter_config.json` and
88
+ `adapter_model.safetensors` — so they load in vLLM, SGLang or transformers
89
+ without conversion. Download them from the console, or serve them on Runara
90
+ alongside the base model.
91
+
92
+ ## Errors worth catching
93
+
94
+ | | |
95
+ |---|---|
96
+ | `runara.InsufficientBalance` | The organization is out of credit. |
97
+ | `runara.SessionClosed` | The session ended, or is ending because the balance ran out. |
98
+ | `runara.RunaraError` | Everything else, with `.status` and `.code`. |
99
+
100
+ A training call is never retried automatically. One that timed out may already
101
+ have applied its gradients, and sending it again would train on the same batch
102
+ twice.
103
+
104
+ ## Checked against the reference
105
+
106
+ The renderers are verified to produce byte-identical tokens, targets and loss
107
+ masks to `tinker-cookbook` for the same conversation and tokenizer. Chat
108
+ templating is the part of fine-tuning that goes wrong silently, so it is
109
+ checked against an independent implementation rather than only against itself.
110
+
111
+ ## Installing
112
+
113
+ The client has no dependencies at all — it is stdlib, so installing it cannot
114
+ conflict with whatever `torch`, `transformers` or `numpy` versions your
115
+ training code already pins. The heavy dependencies live in `runara-cookbook`.
@@ -0,0 +1,13 @@
1
+ runara/__init__.py,sha256=vWCwHRD9i8ExBjoY2EKDH_vt685LDOxZpoBjBLEKMVE,939
2
+ runara/_futures.py,sha256=LocdNSqEGAb-gY6FeW5J7N8IEvOfUFysCPjO8g3Dv7g,2394
3
+ runara/_http.py,sha256=Q2x16Sybfrjxz-5DpNH9EyeaYw195cH4tzNtyO_sQ6A,6035
4
+ runara/client.py,sha256=p1oT8qmYtB_B2pURT4DAWi0NbqgnDNFFna4uHj1_Iv4,10604
5
+ runara/types.py,sha256=Lrc4d3HjaO9eSBjLrQP52y98526p60SJPsXgyc9MMTM,3206
6
+ runara_cookbook/__init__.py,sha256=5R4tThzuaCZQWW05iQacr365aU7jnFpu1j5AQ2J0GO0,357
7
+ runara_cookbook/data.py,sha256=8wlWJp12Gg_DfZ5u_HB7eD2JTFfB4-TzrHbUxVDhpUg,3322
8
+ runara_cookbook/renderers/__init__.py,sha256=T46yfddq5e2jImr-1DAo8zF3bZ4UbDgUuPnzAFI_1XQ,1462
9
+ runara_cookbook/renderers/base.py,sha256=Gs1GgLcHvgd8ZXYajGlFBbBjzp9iuidmogvneKz5sr8,8460
10
+ runara-0.1.0.dist-info/METADATA,sha256=PkIgngt9Dg6uAYXNtmg3mAPeyy2wgKSOlIm78Li-ltA,4276
11
+ runara-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
12
+ runara-0.1.0.dist-info/top_level.txt,sha256=JWRLhgKrXdMvtrLSXitBlr_-9PbMN4FNA-EJS7zwzkQ,23
13
+ runara-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ runara
2
+ runara_cookbook
@@ -0,0 +1,11 @@
1
+ """Helpers for fine-tuning on Runara: chat templates, data loading, batching.
2
+
3
+ Open source on purpose. This is the code that decides what your tokens look
4
+ like before they are sent, so it should be code you can read.
5
+ """
6
+
7
+ from . import data, renderers
8
+ from .renderers import TrainOnWhat
9
+
10
+ __version__ = "0.1.0"
11
+ __all__ = ["data", "renderers", "TrainOnWhat"]
@@ -0,0 +1,88 @@
1
+ """Reading your data, on your machine.
2
+
3
+ Nothing here talks to Runara. These helpers open files you already have and
4
+ hand the rows to a renderer; what leaves your machine is whatever the renderer
5
+ produced, which is token ids and floats.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import random
12
+ from pathlib import Path
13
+ from typing import Iterator, Sequence
14
+
15
+ from runara.types import Datum
16
+
17
+ from .renderers.base import Message, Renderer, TrainOnWhat
18
+
19
+
20
+ def read_jsonl(path: str | Path) -> list[dict]:
21
+ """Read a JSONL file from your disk. One JSON object per line."""
22
+ rows: list[dict] = []
23
+ with Path(path).open() as handle:
24
+ for number, line in enumerate(handle, start=1):
25
+ line = line.strip()
26
+ if not line:
27
+ continue
28
+ try:
29
+ rows.append(json.loads(line))
30
+ except json.JSONDecodeError as error:
31
+ # Name the line rather than the content: an error message is a
32
+ # place training data leaks into logs by accident.
33
+ raise ValueError(f"{path} line {number} is not valid JSON") from error
34
+ if not rows:
35
+ raise ValueError(f"{path} has no rows")
36
+ return rows
37
+
38
+
39
+ def conversations(rows: Sequence[dict], key: str = "messages") -> list[list[Message]]:
40
+ """Pull the chat turns out of raw rows, checking the shape once up front."""
41
+ out: list[list[Message]] = []
42
+ for index, row in enumerate(rows):
43
+ messages = row.get(key)
44
+ if not isinstance(messages, list) or not messages:
45
+ raise ValueError(f"row {index} has no {key!r} list")
46
+ for message in messages:
47
+ if not isinstance(message, dict) or "role" not in message or "content" not in message:
48
+ raise ValueError(
49
+ f"row {index}: every message needs a 'role' and 'content'"
50
+ )
51
+ out.append(messages)
52
+ return out
53
+
54
+
55
+ def build_data(
56
+ renderer: Renderer,
57
+ conversation_list: Sequence[Sequence[Message]],
58
+ train_on_what: TrainOnWhat = TrainOnWhat.LAST_ASSISTANT_MESSAGE,
59
+ max_tokens: int | None = None,
60
+ ) -> list[Datum]:
61
+ """Render every conversation into a Datum, dropping ones that are too long.
62
+
63
+ Dropped rather than truncated: a truncated conversation ends mid-sentence,
64
+ and training the model to stop there teaches it to do the same.
65
+ """
66
+ data: list[Datum] = []
67
+ for messages in conversation_list:
68
+ rendered = renderer.build_supervised_example(messages, train_on_what)
69
+ if max_tokens is not None and len(rendered.tokens) > max_tokens:
70
+ continue
71
+ data.append(renderer.to_datum(messages, train_on_what))
72
+ return data
73
+
74
+
75
+ def batches(items: Sequence[Datum], size: int, shuffle: bool = False, seed: int = 0) -> Iterator[list[Datum]]:
76
+ """Yield fixed-size batches. The last one may be smaller."""
77
+ if size < 1:
78
+ raise ValueError("batch size must be at least 1")
79
+ order = list(range(len(items)))
80
+ if shuffle:
81
+ random.Random(seed).shuffle(order)
82
+ for start in range(0, len(order), size):
83
+ yield [items[index] for index in order[start : start + size]]
84
+
85
+
86
+ def token_count(data: Sequence[Datum]) -> int:
87
+ """Trained tokens across a dataset — what one epoch will cost."""
88
+ return sum(datum.trained_tokens for datum in data)
@@ -0,0 +1,60 @@
1
+ """Chat templates per model family.
2
+
3
+ Pick the renderer that matches your base model. Using the wrong one trains on
4
+ a format the model is never prompted with at inference, which costs quality
5
+ with no error and nothing in the loss curve to show for it.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from .base import (
11
+ Message,
12
+ RenderedExample,
13
+ Renderer,
14
+ Tokenizer,
15
+ TrainOnWhat,
16
+ to_datum,
17
+ )
18
+
19
+ #: Families whose chat template the base Renderer handles directly. A family
20
+ #: that needs special handling gets its own subclass and an entry here.
21
+ _REGISTRY: dict[str, type[Renderer]] = {
22
+ "qwen3": Renderer,
23
+ "qwen3_5": Renderer,
24
+ "llama3": Renderer,
25
+ "generic": Renderer,
26
+ }
27
+
28
+
29
+ def get(name: str, tokenizer: Tokenizer) -> Renderer:
30
+ """Build the renderer for a model family."""
31
+ try:
32
+ cls = _REGISTRY[name]
33
+ except KeyError:
34
+ raise ValueError(
35
+ f"No renderer named {name!r}. Available: {', '.join(sorted(_REGISTRY))}. "
36
+ "Use 'generic' if your tokenizer carries its own chat template."
37
+ ) from None
38
+ return cls(tokenizer)
39
+
40
+
41
+ def register(name: str, cls: type[Renderer]) -> None:
42
+ """Add a renderer for a family we do not ship."""
43
+ _REGISTRY[name] = cls
44
+
45
+
46
+ def available() -> list[str]:
47
+ return sorted(_REGISTRY)
48
+
49
+
50
+ __all__ = [
51
+ "Message",
52
+ "RenderedExample",
53
+ "Renderer",
54
+ "Tokenizer",
55
+ "TrainOnWhat",
56
+ "available",
57
+ "get",
58
+ "register",
59
+ "to_datum",
60
+ ]
@@ -0,0 +1,203 @@
1
+ """Turning a conversation into tokens and a loss mask.
2
+
3
+ This is the part of fine-tuning that is easy to get wrong and never tells you.
4
+ Two mistakes in particular:
5
+
6
+ **The shift.** A language model predicts the *next* token, so the targets are
7
+ the inputs moved along by one. `to_datum` does that once, correctly. Doing it
8
+ twice — or not at all — trains the model toward the wrong position, and the
9
+ loss still falls, just toward something useless.
10
+
11
+ **The template.** Every model family wraps a conversation in its own control
12
+ tokens, and training on a format the model does not see at inference quietly
13
+ costs you quality. Which is why the renderer builds the same token sequence
14
+ the model will actually be prompted with, rather than something close to it.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from dataclasses import dataclass
20
+ from enum import Enum
21
+ from typing import Protocol, Sequence
22
+
23
+ from runara.types import Datum
24
+
25
+ Message = dict # {"role": "user" | "assistant" | "system", "content": str}
26
+
27
+
28
+ class TrainOnWhat(str, Enum):
29
+ """Which tokens carry loss.
30
+
31
+ The default trains on the last assistant message only, which is what you
32
+ want for most supervised fine-tuning: you are teaching the model to answer,
33
+ not to produce the questions it was asked.
34
+ """
35
+
36
+ LAST_ASSISTANT_MESSAGE = "last_assistant_message"
37
+ ALL_ASSISTANT_MESSAGES = "all_assistant_messages"
38
+ ALL_TOKENS = "all_tokens"
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class RenderedExample:
43
+ """Tokens and their per-token weights, before the shift."""
44
+
45
+ tokens: list[int]
46
+ weights: list[float]
47
+
48
+ def __post_init__(self) -> None:
49
+ if len(self.tokens) != len(self.weights):
50
+ raise ValueError(
51
+ f"tokens and weights must be the same length; "
52
+ f"got {len(self.tokens)} and {len(self.weights)}"
53
+ )
54
+
55
+
56
+ def to_datum(rendered: RenderedExample) -> Datum:
57
+ """Shift once, and only once.
58
+
59
+ `token_ids[i]` is the input at position *i*; `target_tokens[i]` is what the
60
+ model should produce there. Because a model predicts the next token, that
61
+ target is the *following* token of the original sequence — so inputs drop
62
+ the last token and targets drop the first.
63
+
64
+ The weights follow the targets, not the inputs: a weight says "score the
65
+ prediction at this position", and the prediction being scored at position
66
+ *i* is of the original token *i+1*. Using `weights[:-1]` instead would
67
+ shift the mask one place against the targets, so the model would be
68
+ trained on the prompt's final token and not on the answer's final token —
69
+ an error of exactly one position, with no symptom at all.
70
+ """
71
+ if len(rendered.tokens) < 2:
72
+ raise ValueError("need at least two tokens to form an input and a target")
73
+ return Datum(
74
+ token_ids=rendered.tokens[:-1],
75
+ target_tokens=rendered.tokens[1:],
76
+ weights=rendered.weights[1:],
77
+ )
78
+
79
+
80
+ class Tokenizer(Protocol):
81
+ """The slice of a HuggingFace tokenizer a renderer needs."""
82
+
83
+ def encode(self, text: str, add_special_tokens: bool = ...) -> list[int]: ...
84
+
85
+ def apply_chat_template(
86
+ self, conversation: Sequence[Message], tokenize: bool = ..., **kwargs
87
+ ) -> str: ...
88
+
89
+
90
+ class Renderer:
91
+ """Base class. A family-specific renderer overrides the template calls."""
92
+
93
+ def __init__(self, tokenizer: Tokenizer) -> None:
94
+ self.tokenizer = tokenizer
95
+
96
+ # -- what subclasses provide ------------------------------------------
97
+
98
+ def render_prefix(self, messages: Sequence[Message]) -> str:
99
+ """The prompt text the model would be given for these messages."""
100
+ return self.tokenizer.apply_chat_template(
101
+ list(messages), tokenize=False, add_generation_prompt=True
102
+ )
103
+
104
+ def render_full(self, messages: Sequence[Message]) -> str:
105
+ """The whole conversation, including the final answer."""
106
+ return self.tokenizer.apply_chat_template(list(messages), tokenize=False)
107
+
108
+ # -- the usable surface ------------------------------------------------
109
+
110
+ def build_supervised_example(
111
+ self,
112
+ messages: Sequence[Message],
113
+ train_on_what: TrainOnWhat = TrainOnWhat.LAST_ASSISTANT_MESSAGE,
114
+ ) -> RenderedExample:
115
+ """Tokens plus a 0/1 mask, in the format this model is served in."""
116
+ if not messages:
117
+ raise ValueError("no messages to render")
118
+
119
+ if train_on_what is TrainOnWhat.ALL_TOKENS:
120
+ tokens = self.tokenizer.encode(
121
+ self.render_full(messages), add_special_tokens=False
122
+ )
123
+ return RenderedExample(tokens, [1.0] * len(tokens))
124
+
125
+ if train_on_what is TrainOnWhat.ALL_ASSISTANT_MESSAGES:
126
+ return self._mask_each_assistant_turn(messages)
127
+
128
+ return self._mask_final_answer(messages)
129
+
130
+ def to_datum(
131
+ self,
132
+ messages: Sequence[Message],
133
+ train_on_what: TrainOnWhat = TrainOnWhat.LAST_ASSISTANT_MESSAGE,
134
+ ) -> Datum:
135
+ """Render and shift in one call. What you send to `forward_backward`."""
136
+ return to_datum(self.build_supervised_example(messages, train_on_what))
137
+
138
+ # -- masking -----------------------------------------------------------
139
+
140
+ def _mask_final_answer(self, messages: Sequence[Message]) -> RenderedExample:
141
+ """Train on the last message only, with everything before it masked.
142
+
143
+ The split is done on *text* and then tokenized separately, rather than
144
+ tokenizing once and guessing a boundary. Guessing is where off-by-one
145
+ mask errors come from, and they are invisible: the model simply learns
146
+ a little of the prompt along with the answer.
147
+ """
148
+ prefix_text = self.render_prefix(messages[:-1])
149
+ full_text = self.render_full(messages)
150
+ if not full_text.startswith(prefix_text):
151
+ raise ValueError(
152
+ "this model's chat template does not extend its own prompt; "
153
+ "the renderer for this family needs to override _mask_final_answer"
154
+ )
155
+
156
+ prompt = self.tokenizer.encode(prefix_text, add_special_tokens=False)
157
+ # Trailing whitespace is trimmed because chat templates append a
158
+ # newline after the stop token, and generation ends *at* the stop
159
+ # token. Training on what follows it spends signal teaching the model
160
+ # to emit something it will never be asked to produce. Verified
161
+ # against tinker-cookbook's qwen3 renderer, which trims the same token.
162
+ completion_text = full_text[len(prefix_text) :].rstrip()
163
+ completion = self.tokenizer.encode(completion_text, add_special_tokens=False)
164
+ if not completion:
165
+ raise ValueError("the final message rendered to no tokens")
166
+
167
+ return RenderedExample(
168
+ tokens=prompt + completion,
169
+ weights=[0.0] * len(prompt) + [1.0] * len(completion),
170
+ )
171
+
172
+ def _mask_each_assistant_turn(self, messages: Sequence[Message]) -> RenderedExample:
173
+ """Train on every assistant turn, masking user and system turns.
174
+
175
+ Boundaries come from rendering the conversation one message longer
176
+ each time and taking the difference. Using the *generation prompt* as
177
+ the running prefix instead looks natural and is wrong: after an
178
+ assistant turn it ends with a dangling header that the next render
179
+ does not extend, so the split silently stops lining up.
180
+
181
+ The assistant's own header falls inside the trained span here, unlike
182
+ the single-answer case which masks it. That is deliberate — across a
183
+ multi-turn conversation the model has to learn where its turns begin.
184
+ """
185
+ tokens: list[int] = []
186
+ weights: list[float] = []
187
+ previous = ""
188
+ for index, message in enumerate(messages):
189
+ current = self.render_full(messages[: index + 1])
190
+ if not current.startswith(previous):
191
+ raise ValueError(
192
+ "this chat template does not extend its own output; "
193
+ "this family needs its own renderer"
194
+ )
195
+ chunk = self.tokenizer.encode(
196
+ current[len(previous) :], add_special_tokens=False
197
+ )
198
+ tokens.extend(chunk)
199
+ weights.extend(
200
+ [1.0 if message.get("role") == "assistant" else 0.0] * len(chunk)
201
+ )
202
+ previous = current
203
+ return RenderedExample(tokens, weights)