@volter/twin-togetherai 0.1.0

package/dist/src/togetherai-budget.js

@@ -0,0 +1,130 @@
+// Together AI's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin
+// typed bindings `liveTogetheraiExecute` uses. The MECHANISM — the durable token-keyed ledger,
+// the rolling window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a
+// corrupt ledger — lives ONCE in the vendor-agnostic kernel (`@volter/world-core` →
+// `rateBudget.ts`). Read that module's header for the full rationale AND for the honest list of
+// what the guard does not guarantee.
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN (live-read, 2026-09-16) ──────────────────────────────────────
+// https://docs.together.ai/serverless/rate-limits (read 2026-09-16) publishes NO scalar a client
+// could be bound by: limits are "dynamic" and PER ORGANIZATION and PER MODEL, and the page's own
+// wording is "there are no fixed per-model limits published" — the account's dashboard is the only
+// place the real numbers live. Success responses carry NO rate-limit headers; a 429 carries only
+// `x-ratelimit-reset` (seconds until the window resets), and its error types are
+// `dynamic_request_limited` / `dynamic_token_limited`; a 503 means the dynamic rate is at/below
+// capacity.
+//
+// So this declaration does not model Together's limit, and nothing here is more permissive than
+// the kernel's undeclared fallback: window 60s, ceiling 60, defaultWeight 2 — i.e. 30
+// calls/minute, EXACTLY `DEFAULT_RATE_BUDGET`, with no endpoint priced cheaper than the fallback
+// would price it. Being stricter than the fallback needs no vendor justification; being looser
+// would, and there is none to have.
+//
+// It bounds the 60s AVERAGE; it does not pace (the kernel refuses, it never sleeps). The backstop
+// for a sub-second burst is the cooldown: Together's `x-ratelimit-reset` (documented on the 429)
+// is read off the response and turns into a persisted refusal.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'togetherai';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const TOGETHERAI_BUDGET_WINDOW_MS = 60_000;
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback, because Together publishes no scalar that would
+ * justify more. See the header.
+ */
+export const TOGETHERAI_BUDGET_CEILING = 60;
+/** Seconds. A `x-ratelimit-reset` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const TOGETHERAI_CALL_WEIGHTS = {
+    /** `/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/rerank`,
+     *  `/v1/images/generations`, `/v1/audio/*` — token-metered, where Together's DYNAMIC token
+     *  budget (`dynamic_token_limited`) rather than its request budget is usually what binds. */
+    inference: 6,
+    /** Everything else: files, batches, models, whoami, fine-tunes, endpoints. */
+    other: 2,
+};
+/** THE PACK'S DECLARATION — pure data, the only Together-specific thing in the whole budget. */
+export const TOGETHERAI_RATE_BUDGET = {
+    windowMs: TOGETHERAI_BUDGET_WINDOW_MS,
+    ceiling: TOGETHERAI_BUDGET_CEILING,
+    defaultWeight: TOGETHERAI_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        { match: '^POST /v1/(chat/completions|completions|embeddings|rerank|images/generations)$', weight: TOGETHERAI_CALL_WEIGHTS.inference },
+        { match: '^POST /v1/audio/', weight: TOGETHERAI_CALL_WEIGHTS.inference },
+    ],
+    reason: 'Together publishes NO fixed request limit (docs.together.ai/serverless/rate-limits, read ' +
+        '2026-09-16): limits are DYNAMIC and per organization per model — the page states "there are ' +
+        'no fixed per-model limits published", the real numbers live only on the account dashboard, ' +
+        'and success responses carry no rate-limit headers at all. A 429 carries only ' +
+        '`x-ratelimit-reset` (seconds) with error types `dynamic_request_limited` / ' +
+        '`dynamic_token_limited`; a 503 signals the dynamic rate is at/below capacity. Because no ' +
+        'published figure justifies going higher, the ceiling is pinned at the kernel fallback in ' +
+        'EVERY dimension — 60 units / 60s at defaultWeight 2 = 30 calls/min — and the declaration ' +
+        'buys resolution DOWNWARD, never headroom: the inference endpoints cost 6, so at most 10 land ' +
+        'in a window. The window bounds the 60s AVERAGE and does not pace; the `x-ratelimit-reset` ' +
+        'cooldown is the backstop for a sub-second burst.',
+};
+// Declared at module load, so merely importing this module (which `togetherai-connector.ts`
+// does) is enough to arm the real ceiling.
+declareRateBudget(VENDOR, TOGETHERAI_RATE_BUDGET);
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Together. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function togetheraiCallWeight(method, path) {
+    const { bare, query } = splitQuery(path);
+    // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+    // `execute('post', …)` really does issue a POST and must be priced as one.
+    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+/**
+ * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; NORMALIZED,
+ * because the anchored rules are otherwise trivially evaded: `fetch` upper-cases a known method
+ * before sending, so `execute('post', …)` issues a real WRITE that a `^POST ` rule would price as
+ * a read; and a trailing slash makes a path miss a `$` anchor while most routers treat it as the
+ * same endpoint.
+ */
+function splitQuery(path) {
+    const at = path.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
+            query[k] = v;
+    // Collapse REPEATED slashes as well as a trailing one: `/v1//chat/completions` reaches the same
+    // endpoint on most routers but misses a `^POST /v1/(chat/completions|…)$` rule, which would
+    // price an inference call as a 2-unit read (the groq pack's §9 round one, NIT 14).
+    const raw = (at === -1 ? path : path.slice(0, at)).replace(/\/{2,}/g, '/');
+    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+    return { bare, query };
+}
+/** Where Together's ledger lives. Token-keyed and cwd-independent by default (Together's limits
+ *  are per ORGANIZATION, i.e. per key, so a cwd-scoped ledger would hand the same key a fresh
+ *  allowance in every checkout, worktree and CI matrix leg); pass `root` for world-scoped
+ *  accounting. */
+export function togetheraiBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * Together's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof TogetheraiBudget` in `liveTogetheraiExecute`
+ * means "a budget that accounts against TOGETHER's ledger under TOGETHER's ceiling".
+ */
+export class TogetheraiBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as TogetheraiBudgetError } from '@volter/world-core';

package/dist/src/togetherai-capabilities.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const TOGETHERAI_CAPABILITIES: CapabilitySpec[];
+export declare const TOGETHERAI_AREAS: readonly ["audio", "auth", "batches", "chat", "compute", "conformance", "connector", "embeddings", "endpoints", "errors", "evaluation", "files", "fine_tuning", "images", "models", "protocol", "queue", "rate_limits", "rerank", "streaming", "structured_outputs", "tools", "tci", "usage", "videos", "whoami"];
+export declare function togetheraiCapabilities(): Promise<CapabilityReport>;