@sponsio/sdk 0.1.0-alpha.3

package/dist/contract.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fluent contract builder — TS parity for the Python
+ * ``from sponsio import contract`` helper.
+ *
+ * Usage::
+ *
+ *   import { Sponsio, contract } from "@sponsio/sdk";
+ *
+ *   const guard = new Sponsio({
+ *     agentId: "refund_bot",
+ *     contracts: [
+ *       contract("refund policy gate")
+ *         .assume("called `issue_refund`")
+ *         .enforce("must call `check_policy` before `issue_refund`"),
+ *       contract("rate cap")
+ *         .enforce("tool `issue_refund` at most 3 times"),
+ *     ],
+ *   });
+ *
+ * Repeated ``.assume`` / ``.enforce`` calls AND-combine (matching
+ * the Python builder). If ``.assume`` is omitted the contract is
+ * unconditional and the enforcement formula is used as-is. If
+ * ``.assume`` is present the formula is ``A -> E``.
+ *
+ * The builder satisfies ``DetFormula`` structurally, so it can be
+ * passed directly to ``Sponsio({ contracts: [...] })`` — no ``build()``
+ * step required.
+ */
+import { type Formula } from "./core/formula.js";
+import type { DetFormula } from "./core/patterns.js";
+export declare class ContractBuilder implements DetFormula {
+    readonly desc: string;
+    readonly patternName: string;
+    readonly liveness: boolean;
+    private _assumption;
+    private _enforcement;
+    constructor(desc?: string);
+    /** Add an assumption clause (A side). Repeated calls AND-combine. */
+    assume(clause: string | DetFormula): ContractBuilder;
+    /** Add an enforcement clause (E side). Repeated calls AND-combine. */
+    enforce(clause: string | DetFormula): ContractBuilder;
+    /**
+     * The compiled LTL formula. Accessed at `Sponsio` construction time.
+     *
+     * - If both A and E are set: ``G(A -> E)``. We wrap in ``G`` because
+     *   the evaluator runs from ``pos=0``; a bare ``Implies(A, E)`` would
+     *   short-circuit whenever ``A`` was false at step 0 regardless of
+     *   later events. ``G`` lifts the implication to every step so the
+     *   enforcement fires whenever the assumption holds.
+     * - If only E: ``E`` (unconditional; the pattern factories already
+     *   emit safety properties wrapped in ``G`` where needed).
+     * - If neither: throws — every contract needs an enforcement.
+     */
+    get formula(): Formula;
+    private _clone;
+}
+/** Start a fluent contract. Mirrors Python's ``sponsio.contract(desc)``. */
+export declare function contract(desc?: string): ContractBuilder;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,qBAAa,eAAgB,YAAW,UAAU;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAc;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAS;IAEnC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,YAAY,CAAiB;gBAEzB,IAAI,CAAC,EAAE,MAAM;IAMzB,qEAAqE;IACrE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,eAAe;IAOpD,sEAAsE;IACtE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,eAAe;IAOrD;;;;;;;;;;;OAWG;IACH,IAAI,OAAO,IAAI,OAAO,CASrB;IAED,OAAO,CAAC,MAAM;CAMf;AAeD,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAEvD"}

package/dist/contract.js

@@ -0,0 +1,97 @@
+/**
+ * Fluent contract builder — TS parity for the Python
+ * ``from sponsio import contract`` helper.
+ *
+ * Usage::
+ *
+ *   import { Sponsio, contract } from "@sponsio/sdk";
+ *
+ *   const guard = new Sponsio({
+ *     agentId: "refund_bot",
+ *     contracts: [
+ *       contract("refund policy gate")
+ *         .assume("called `issue_refund`")
+ *         .enforce("must call `check_policy` before `issue_refund`"),
+ *       contract("rate cap")
+ *         .enforce("tool `issue_refund` at most 3 times"),
+ *     ],
+ *   });
+ *
+ * Repeated ``.assume`` / ``.enforce`` calls AND-combine (matching
+ * the Python builder). If ``.assume`` is omitted the contract is
+ * unconditional and the enforcement formula is used as-is. If
+ * ``.assume`` is present the formula is ``A -> E``.
+ *
+ * The builder satisfies ``DetFormula`` structurally, so it can be
+ * passed directly to ``Sponsio({ contracts: [...] })`` — no ``build()``
+ * step required.
+ */
+import { parseNl } from "./core/nl-parser.js";
+import { And, G, Implies } from "./core/formula.js";
+export class ContractBuilder {
+    desc;
+    patternName = "contract";
+    liveness = false;
+    _assumption;
+    _enforcement;
+    constructor(desc) {
+        this.desc = desc ?? "contract";
+        this._assumption = null;
+        this._enforcement = null;
+    }
+    /** Add an assumption clause (A side). Repeated calls AND-combine. */
+    assume(clause) {
+        const next = this._clone();
+        const f = toFormula(clause, "assume");
+        next._assumption = next._assumption ? new And(next._assumption, f) : f;
+        return next;
+    }
+    /** Add an enforcement clause (E side). Repeated calls AND-combine. */
+    enforce(clause) {
+        const next = this._clone();
+        const f = toFormula(clause, "enforce");
+        next._enforcement = next._enforcement ? new And(next._enforcement, f) : f;
+        return next;
+    }
+    /**
+     * The compiled LTL formula. Accessed at `Sponsio` construction time.
+     *
+     * - If both A and E are set: ``G(A -> E)``. We wrap in ``G`` because
+     *   the evaluator runs from ``pos=0``; a bare ``Implies(A, E)`` would
+     *   short-circuit whenever ``A`` was false at step 0 regardless of
+     *   later events. ``G`` lifts the implication to every step so the
+     *   enforcement fires whenever the assumption holds.
+     * - If only E: ``E`` (unconditional; the pattern factories already
+     *   emit safety properties wrapped in ``G`` where needed).
+     * - If neither: throws — every contract needs an enforcement.
+     */
+    get formula() {
+        if (!this._enforcement) {
+            throw new Error(`contract(${JSON.stringify(this.desc)}): .enforce(...) is required`);
+        }
+        return this._assumption
+            ? new G(new Implies(this._assumption, this._enforcement))
+            : this._enforcement;
+    }
+    _clone() {
+        const next = new ContractBuilder(this.desc);
+        next._assumption = this._assumption;
+        next._enforcement = this._enforcement;
+        return next;
+    }
+}
+function toFormula(clause, which) {
+    if (typeof clause === "string") {
+        const parsed = parseNl(clause);
+        if (!parsed) {
+            throw new Error(`contract().${which}("${clause}"): could not parse NL clause`);
+        }
+        return parsed.formula;
+    }
+    return clause.formula;
+}
+/** Start a fluent contract. Mirrors Python's ``sponsio.contract(desc)``. */
+export function contract(desc) {
+    return new ContractBuilder(desc);
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAgB,MAAM,mBAAmB,CAAC;AAGlE,MAAM,OAAO,eAAe;IACjB,IAAI,CAAS;IACb,WAAW,GAAW,UAAU,CAAC;IACjC,QAAQ,GAAY,KAAK,CAAC;IAE3B,WAAW,CAAiB;IAC5B,YAAY,CAAiB;IAErC,YAAY,IAAa;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,UAAU,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,qEAAqE;IACrE,MAAM,CAAC,MAA2B;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sEAAsE;IACtE,OAAO,CAAC,MAA2B;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,OAAO;QACT,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,CACpE,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,WAAW;YACrB,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YACzD,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;IACxB,CAAC;IAEO,MAAM;QACZ,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,SAAS,SAAS,CAAC,MAA2B,EAAE,KAAa;IAC3D,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,cAAc,KAAK,KAAK,MAAM,+BAA+B,CAC9D,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/core/config-loader.d.ts

@@ -0,0 +1,90 @@
+/**
+ * sponsio.yaml loader for the TypeScript runtime.
+ *
+ * Parses a Python-compatible sponsio.yaml into the shape the
+ * {@link Sponsio} constructor expects: a list of NL-string contracts
+ * plus runtime settings (mode, dashboard).
+ *
+ * Intentionally conservative — this loader understands the **subset**
+ * of the yaml schema that makes sense in TS today:
+ *
+ *   - `runtime.mode` / `runtime.dashboard`
+ *   - `agents.<id>.contracts[]` with either a plain-string `E:` field
+ *     or a top-level `desc:` / direct-string entry. Structured
+ *     `{ pattern, args }` forms that need pack-runtime support
+ *     (token_budget, delegation_depth_limit, loop_detection, …)
+ *     are *skipped with a warning* — the TS runtime does not ship
+ *     pack infrastructure yet.
+ *   - `include:` pack references are skipped with a warning for the
+ *     same reason.
+ *
+ * The loader is therefore a **strict superset of inline TS usage**:
+ * contracts that work when passed as `contracts: string[]` to the
+ * ctor also work when loaded from yaml. More exotic Python-side
+ * features (sto contracts, packs, LTL patterns) are logged and
+ * ignored rather than crashing, so a user can share a single
+ * sponsio.yaml between Python and TS without the TS side refusing
+ * to start.
+ */
+import type { DetFormula } from "./patterns.js";
+export interface LoadedConfig {
+    /**
+     * Det contracts the TS SDK can consume. NL strings get run through
+     * ``parseNl`` in the ctor; pre-built ``DetFormula`` entries (from
+     * structured patterns, raw LTL, or A/E composition) are pushed
+     * straight onto the contract list — no NL parsing required.
+     */
+    contracts: (string | DetFormula)[];
+    /** Sto contract specs — compiled into evaluators by the ctor. */
+    stoSpecs: StoContractSpec[];
+    /** `judge:` block — provider / model / api_key / base_url / fallback. */
+    judge?: JudgeConfigSpec;
+    /** `enforce` | `observe` | undefined (fall through to default). */
+    mode?: "enforce" | "observe";
+    /** Dashboard URL or boolean from yaml, passed through unchanged. */
+    dashboard?: string | boolean;
+    /**
+     * Contracts / packs we couldn't handle. Surfaced so the Sponsio
+     * ctor can warn once without spamming per-contract log lines.
+     */
+    skipped: SkippedItem[];
+}
+export interface SkippedItem {
+    kind: "pack" | "structured-contract" | "sto-contract" | "unknown-contract";
+    detail: string;
+}
+export type StoAtomName = "tone" | "llm_judge" | "relevance" | "semantic_pii_free" | "hallucination_free" | "scope_respect" | "metric_integrity" | "injection_free";
+/**
+ * Spec for a yaml-declared sto contract. The loader stays stateless:
+ * it emits a description of the rule, and the Sponsio ctor wires up
+ * an evaluator against the `judge:` client.
+ */
+export interface StoContractSpec {
+    atom: StoAtomName;
+    desc: string;
+    /** Threshold — score below this counts as a violation. */
+    threshold: number;
+    /** ``tone``: the target tone. ``scope_respect``: the scope blurb.
+     *  Other atoms ignore this. */
+    args: string[];
+    /** Free-form rubric for ``llm_judge``. */
+    promptOverride?: string;
+}
+export interface JudgeConfigSpec {
+    provider?: "openai";
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    fallbackMode?: "allow" | "deny" | "skip";
+}
+/**
+ * Load sponsio.yaml and project it onto the TS runtime's contract
+ * surface. Reads synchronously so it can be called from a ctor.
+ *
+ * @param path       Path to sponsio.yaml (absolute or CWD-relative).
+ * @param agentId    Which agent block to pull contracts from. Falls
+ *                   back to `agents["*"]` (the wildcard block used by
+ *                   packs) if `agentId` is missing.
+ */
+export declare function loadSponsoConfig(path: string, agentId: string): LoadedConfig;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/core/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/core/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAgBhD,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC;IACnC,iEAAiE;IACjE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,yEAAyE;IACzE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,mEAAmE;IACnE,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,cAAc,GAAG,kBAAkB,CAAC;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,WAAW,GACX,WAAW,GACX,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,kBAAkB,GAClB,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB;mCAC+B;IAC/B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;CAC1C;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAsD5E"}