vantage-core 0.1.0__py3-none-any.whl

vantage_core/__init__.py

@@ -0,0 +1,20 @@
+"""vantage-core — RuntimeAI check-ride CLI and portable decision artifact."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from vantage_core.decision import (
+    SCHEMA_ID,
+    build_decision_object,
+    payload_sha256,
+    validate_decision_object,
+)
+
+__all__ = [
+    "SCHEMA_ID",
+    "__version__",
+    "build_decision_object",
+    "payload_sha256",
+    "validate_decision_object",
+]

vantage_core/__main__.py

@@ -0,0 +1,6 @@
+from vantage_core.cli import cli_entry, main
+
+__all__ = ["cli_entry", "main"]
+
+if __name__ == "__main__":
+    cli_entry()

vantage_core/cli.py

@@ -0,0 +1,255 @@
+"""vantage-core CLI — check-ride run + decision schema helpers."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from vantage_core import SCHEMA_ID, __version__, validate_decision_object
+from vantage_core.decision import SCHEMA_ID as _SCHEMA
+
+
+def _load_env() -> None:
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return
+    load_dotenv(Path.cwd() / ".env")
+    home = os.environ.get("VANTAGE_HOME")
+    if home:
+        load_dotenv(Path(home) / ".env")
+        load_dotenv(Path(home) / "server" / ".env")
+    # Monorepo convenience when present
+    try:
+        from vantage_core.monorepo_run import find_server_root
+
+        root = find_server_root()
+        if root is not None:
+            load_dotenv(root.parent / ".env")
+            load_dotenv(root / ".env")
+    except Exception:
+        pass
+
+
+def _print_decision(decision: dict[str, Any], *, as_json: bool) -> None:
+    passed = bool(decision.get("passed"))
+    score = decision.get("out_of_10")
+    cost = decision.get("est_usd")
+    cost_s = f"~${cost:.4f}" if isinstance(cost, (int, float)) else "n/a"
+    verdict = "PASS" if passed else "FAIL"
+    score_s = f"{float(score):.1f}" if isinstance(score, (int, float)) else "n/a"
+
+    if as_json:
+        print(json.dumps(decision, indent=2))
+    else:
+        print(f"score  {score_s} / 10   ·   {cost_s}   ·   {verdict}")
+        print(f"session  {decision.get('session_id')}")
+        gate = decision.get("pass_gate") if isinstance(decision.get("pass_gate"), dict) else {}
+        if gate.get("headline"):
+            print(f"gate  {gate['headline']}")
+        print(f"scorecard  re-run with --json  ({SCHEMA_ID})")
+        if decision.get("status") != "ended" and decision.get("error"):
+            print(f"status {decision.get('status')}: {decision.get('error')}", file=sys.stderr)
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    _load_env()
+
+    use_monorepo = (
+        bool(getattr(args, "monorepo", False))
+        or (os.getenv("VANTAGE_USE_MONOREPO") or "").strip() in ("1", "true", "yes")
+    )
+
+    if use_monorepo and not args.contract:
+        from vantage_core.monorepo_run import bootstrap_server, run_checkride as mono_run
+
+        try:
+            server = bootstrap_server()
+        except RuntimeError as exc:
+            print(str(exc), file=sys.stderr)
+            return 2
+        if not server._openrouter_api_key():
+            print("OPENROUTER_API_KEY not configured.", file=sys.stderr)
+            return 2
+        try:
+            decision = mono_run(
+                server,
+                scenario_id=args.scenario,
+                model=args.model,
+                turns=args.turns,
+                timeout_s=args.timeout,
+                fail_under=float(args.fail_under),
+                runner_version=__version__,
+            )
+        except Exception as exc:
+            print(f"vantage-core run failed: {exc}", file=sys.stderr)
+            return 1
+        _print_decision(decision, as_json=args.json)
+        return 0 if decision.get("passed") else 1
+
+    # Standalone path (default)
+    from vantage_core.contract import contract_from_library_id, load_contract
+    from vantage_core.llm_openrouter import openrouter_api_key
+    from vantage_core.runner import run_checkride
+
+    if not openrouter_api_key():
+        print(
+            "OPENROUTER_API_KEY not configured. Export it or put it in .env.",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        if args.contract:
+            contract = load_contract(args.contract)
+        elif args.scenario:
+            contract = contract_from_library_id(
+                args.scenario,
+                fail_under=float(args.fail_under),
+                turns=args.turns,
+                model=args.model,
+            )
+        else:
+            print("Provide --contract PATH or --scenario ID", file=sys.stderr)
+            return 2
+
+        decision = run_checkride(
+            contract,
+            model=args.model,
+            fail_under=float(args.fail_under) if args.fail_under is not None else None,
+            turns=args.turns,
+            timeout_s=args.timeout,
+            runner_version=__version__,
+        )
+    except Exception as exc:
+        print(f"vantage-core run failed: {exc}", file=sys.stderr)
+        return 1
+
+    _print_decision(decision, as_json=args.json)
+    return 0 if decision.get("passed") else 1
+
+
+def cmd_schema(_args: argparse.Namespace) -> int:
+    pkg_dir = Path(__file__).resolve().parent
+    schema_path = pkg_dir / "schemas" / "decision_object.v1.json"
+    if not schema_path.is_file():
+        schema_path = pkg_dir.parent / "schemas" / "decision_object.v1.json"
+    print(f"schema  {_SCHEMA}")
+    print(f"contract_schema  runtimeai.contract/v1")
+    print(f"version  {__version__}")
+    if schema_path.is_file():
+        print(f"json_schema  {schema_path}")
+    print(
+        "fields  contract + scorecard.pass_gate + usd.est_eval + exit + "
+        "integrity.payload_sha256"
+    )
+    from vantage_core.library import list_library_ids
+
+    print(f"library  {', '.join(list_library_ids())}")
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    # Decision JSON or contract YAML/JSON
+    suffix = path.suffix.lower()
+    if suffix in (".yaml", ".yml") or (
+        suffix == ".json" and "contract" in path.name.lower()
+    ):
+        try:
+            from vantage_core.contract import load_contract
+
+            contract = load_contract(path)
+        except Exception as exc:
+            print(f"INVALID contract  {path}: {exc}", file=sys.stderr)
+            return 1
+        print(f"VALID contract  {path}  ({contract.schema} · {contract.id} · {contract.mode})")
+        return 0
+
+    try:
+        data: Any = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        print(f"failed to read JSON: {exc}", file=sys.stderr)
+        return 2
+    # Heuristic: contract JSON vs decision JSON
+    if isinstance(data, dict) and data.get("schema") == "runtimeai.contract/v1":
+        try:
+            from vantage_core.contract import resolve_contract
+
+            contract = resolve_contract(data, source_path=path)
+        except Exception as exc:
+            print(f"INVALID contract  {path}: {exc}", file=sys.stderr)
+            return 1
+        print(f"VALID contract  {path}  ({contract.schema} · {contract.id})")
+        return 0
+
+    errors = validate_decision_object(data)
+    if errors:
+        print(f"INVALID  {path}  ({len(errors)} error(s))", file=sys.stderr)
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        return 1
+    print(f"VALID  {path}  ({SCHEMA_ID})")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="vantage-core",
+        description=(
+            "RuntimeAI check-ride CLI. Emits a portable "
+            f"{SCHEMA_ID} decision artifact. Standalone — no monorepo required."
+        ),
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    run_p = sub.add_parser("run", help="Run a local contract or bundled library scenario")
+    run_p.add_argument(
+        "--contract",
+        help="Path to runtimeai.contract/v1 YAML or JSON",
+    )
+    run_p.add_argument(
+        "--scenario",
+        help="Bundled library scenario id (e.g. de_sql_optimization_v1)",
+    )
+    run_p.add_argument("--model", default="openai/gpt-4o-mini")
+    run_p.add_argument("--turns", type=int, default=None, help="Override contract/library turns")
+    run_p.add_argument("--fail-under", type=float, default=7.0)
+    run_p.add_argument("--timeout", type=float, default=180.0)
+    run_p.add_argument("--json", action="store_true")
+    run_p.add_argument(
+        "--monorepo",
+        action="store_true",
+        help="Force monorepo server path (dev parity; needs Vantage clone)",
+    )
+    run_p.set_defaults(func=cmd_run)
+
+    schema_p = sub.add_parser("schema", help="Show frozen decision + contract schema ids")
+    schema_p.set_defaults(func=cmd_schema)
+
+    val_p = sub.add_parser("validate", help="Validate a decision JSON or contract YAML/JSON")
+    val_p.add_argument("path", help="Path to decision or contract file")
+    val_p.set_defaults(func=cmd_validate)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "command", None) == "run":
+        if not args.contract and not args.scenario:
+            parser.error("run requires --contract or --scenario")
+    return int(args.func(args))
+
+
+def cli_entry() -> None:
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    cli_entry()

vantage_core/contract.py

@@ -0,0 +1,261 @@
+"""runtimeai.contract/v1 — locally authored check-ride contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONTRACT_SCHEMA = "runtimeai.contract/v1"
+
+
+@dataclass
+class HardCheck:
+    id: str
+    points: int = 5
+    any_of: list[str] = field(default_factory=list)
+    none_of: list[str] = field(default_factory=list)
+    hard_fail: bool = False
+
+
+@dataclass
+class ResolvedContract:
+    schema: str
+    id: str
+    name: str
+    mode: str  # library_replay | custom
+    fail_under: float
+    turns: int
+    model: str | None
+    agent_system: str
+    opening: str
+    followups: list[str]
+    scorer_kind: str  # library:de_sql_optimization_v1 | hard_checks
+    hard_checks: list[HardCheck]
+    library_scenario_id: str | None
+    source_path: Path | None = None
+
+    def content_sha256(self) -> str:
+        payload = {
+            "id": self.id,
+            "mode": self.mode,
+            "agent_system": self.agent_system,
+            "opening": self.opening,
+            "followups": self.followups,
+            "scorer_kind": self.scorer_kind,
+            "hard_checks": [
+                {
+                    "id": c.id,
+                    "points": c.points,
+                    "any_of": c.any_of,
+                    "none_of": c.none_of,
+                    "hard_fail": c.hard_fail,
+                }
+                for c in self.hard_checks
+            ],
+            "library_scenario_id": self.library_scenario_id,
+        }
+        raw = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _load_raw(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    suffix = path.suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        try:
+            import yaml
+        except ImportError as exc:
+            raise RuntimeError(
+                "PyYAML is required for .yaml contracts. "
+                "Install: pip install 'vantage-core[run]' or pip install pyyaml"
+            ) from exc
+        data = yaml.safe_load(text)
+    else:
+        data = json.loads(text)
+    if not isinstance(data, dict):
+        raise ValueError(f"contract root must be a mapping: {path}")
+    return data
+
+
+def _as_str_list(val: Any) -> list[str]:
+    if val is None:
+        return []
+    if isinstance(val, str):
+        return [val]
+    if isinstance(val, list):
+        return [str(x) for x in val if str(x).strip()]
+    raise ValueError(f"expected string or list, got {type(val).__name__}")
+
+
+def _parse_hard_checks(raw: Any) -> list[HardCheck]:
+    if not raw:
+        return []
+    if not isinstance(raw, list):
+        raise ValueError("scorer.checks must be a list")
+    out: list[HardCheck] = []
+    for i, item in enumerate(raw):
+        if not isinstance(item, dict):
+            raise ValueError(f"scorer.checks[{i}] must be an object")
+        cid = str(item.get("id") or f"check_{i}").strip()
+        out.append(
+            HardCheck(
+                id=cid,
+                points=int(item.get("points") or 5),
+                any_of=_as_str_list(item.get("any_of")),
+                none_of=_as_str_list(item.get("none_of")),
+                hard_fail=bool(item.get("hard_fail")),
+            )
+        )
+    return out
+
+
+def resolve_contract(data: dict[str, Any], *, source_path: Path | None = None) -> ResolvedContract:
+    schema = str(data.get("schema") or CONTRACT_SCHEMA).strip()
+    if schema != CONTRACT_SCHEMA:
+        raise ValueError(f"unsupported contract schema {schema!r}; expected {CONTRACT_SCHEMA!r}")
+
+    cid = str(data.get("id") or "").strip()
+    if not cid:
+        raise ValueError("contract.id is required")
+    name = str(data.get("name") or cid).strip()
+    mode = str(data.get("mode") or "").strip().lower()
+    if mode not in ("library_replay", "custom"):
+        raise ValueError("contract.mode must be 'library_replay' or 'custom'")
+
+    fail_under = float(data.get("fail_under") if data.get("fail_under") is not None else 7.0)
+    turns = max(1, min(24, int(data.get("turns") or 1)))
+    model = str(data.get("model") or "").strip() or None
+
+    from vantage_core.library import get_library_scenario
+
+    if mode == "library_replay":
+        lib = data.get("library") if isinstance(data.get("library"), dict) else {}
+        lib_id = str(lib.get("scenario_id") or "").strip()
+        if not lib_id:
+            raise ValueError("library_replay requires library.scenario_id")
+        bundled = get_library_scenario(lib_id)
+        if bundled is None:
+            raise ValueError(
+                f"unknown library.scenario_id {lib_id!r}. "
+                f"Bundled: {', '.join(sorted(_library_ids()))}"
+            )
+        fixture = lib.get("fixture")
+        if fixture is None:
+            opening = bundled.default_opening()
+        else:
+            opening = bundled.opening_template.format(fixture=str(fixture).strip())
+        agent_system = str(lib.get("system_prompt") or bundled.agent_system).strip()
+        followups = _as_str_list(lib.get("followups")) or list(bundled.followups)
+        scorer_kind = f"library:{lib_id}"
+        return ResolvedContract(
+            schema=schema,
+            id=cid,
+            name=name,
+            mode=mode,
+            fail_under=fail_under,
+            turns=turns,
+            model=model,
+            agent_system=agent_system,
+            opening=opening,
+            followups=followups,
+            scorer_kind=scorer_kind,
+            hard_checks=[],
+            library_scenario_id=lib_id,
+            source_path=source_path,
+        )
+
+    # custom
+    agent = data.get("agent") if isinstance(data.get("agent"), dict) else {}
+    agent_system = str(agent.get("system") or "").strip()
+    opening = str(agent.get("opening") or "").strip()
+    if not agent_system or not opening:
+        raise ValueError("custom mode requires agent.system and agent.opening")
+    followups = _as_str_list(agent.get("followups"))
+
+    scorer = data.get("scorer") if isinstance(data.get("scorer"), dict) else {}
+    kind = str(scorer.get("kind") or "hard_checks").strip().lower()
+    if kind.startswith("library:"):
+        lib_id = kind.split(":", 1)[1].strip()
+        if get_library_scenario(lib_id) is None:
+            raise ValueError(f"unknown scorer library id {lib_id!r}")
+        scorer_kind = kind
+        hard_checks: list[HardCheck] = []
+    elif kind == "hard_checks":
+        hard_checks = _parse_hard_checks(scorer.get("checks"))
+        if not hard_checks:
+            raise ValueError("hard_checks scorer requires at least one check")
+        scorer_kind = "hard_checks"
+    elif kind == "heuristic_sql_v1":
+        scorer_kind = "library:de_sql_optimization_v1"
+        hard_checks = []
+    else:
+        raise ValueError(
+            f"unsupported scorer.kind {kind!r}; use hard_checks or library:<id>"
+        )
+
+    return ResolvedContract(
+        schema=schema,
+        id=cid,
+        name=name,
+        mode=mode,
+        fail_under=fail_under,
+        turns=turns,
+        model=model,
+        agent_system=agent_system,
+        opening=opening,
+        followups=followups,
+        scorer_kind=scorer_kind,
+        hard_checks=hard_checks,
+        library_scenario_id=None,
+        source_path=source_path,
+    )
+
+
+def _library_ids() -> list[str]:
+    from vantage_core.library import list_library_ids
+
+    return list_library_ids()
+
+
+def load_contract(path: str | Path) -> ResolvedContract:
+    p = Path(path).expanduser().resolve()
+    if not p.is_file():
+        raise FileNotFoundError(f"contract not found: {p}")
+    return resolve_contract(_load_raw(p), source_path=p)
+
+
+def contract_from_library_id(
+    scenario_id: str,
+    *,
+    fail_under: float = 7.0,
+    turns: int | None = None,
+    model: str | None = None,
+) -> ResolvedContract:
+    """Build a resolved contract from a bundled library scenario id."""
+    from vantage_core.library import get_library_scenario
+
+    bundled = get_library_scenario(scenario_id)
+    if bundled is None:
+        raise ValueError(
+            f"unknown scenario {scenario_id!r}. "
+            f"Bundled: {', '.join(sorted(_library_ids()))} — or pass --contract"
+        )
+    return ResolvedContract(
+        schema=CONTRACT_SCHEMA,
+        id=scenario_id,
+        name=bundled.name,
+        mode="library_replay",
+        fail_under=float(fail_under),
+        turns=max(1, min(24, int(turns if turns is not None else bundled.default_turns))),
+        model=model,
+        agent_system=bundled.agent_system,
+        opening=bundled.default_opening(),
+        followups=list(bundled.followups),
+        scorer_kind=f"library:{scenario_id}",
+        hard_checks=[],
+        library_scenario_id=scenario_id,
+        source_path=None,
+    )

vantage_core/cost.py

@@ -0,0 +1,77 @@
+"""Slim USD estimate for standalone runs."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+# Defaults match server task-cost assumptions.
+_AVG_IN = 1500.0
+_AVG_OUT = 350.0
+
+_RATES: dict[str, dict[str, float]] | None = None
+
+
+def _load_rates() -> dict[str, dict[str, float]]:
+    global _RATES
+    if _RATES is not None:
+        return _RATES
+    try:
+        raw = (resources.files("vantage_core") / "data" / "model_rates_slim.json").read_text(
+            encoding="utf-8"
+        )
+        data = json.loads(raw)
+    except Exception:
+        path = Path(__file__).resolve().parent / "data" / "model_rates_slim.json"
+        data = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+    out: dict[str, dict[str, float]] = {}
+    if isinstance(data, dict):
+        for mid, row in data.items():
+            if not isinstance(row, dict):
+                continue
+            try:
+                out[str(mid)] = {
+                    "input": float(row.get("input_token_rate_usd") or row.get("input") or 0),
+                    "output": float(row.get("output_token_rate_usd") or row.get("output") or 0),
+                }
+            except (TypeError, ValueError):
+                continue
+    _RATES = out
+    return out
+
+
+def _lookup(model: str) -> dict[str, float] | None:
+    rates = _load_rates()
+    mid = (model or "").strip()
+    if mid in rates:
+        return rates[mid]
+    # Tail match: openai/gpt-4o-mini ↔ gpt-4o-mini
+    if "/" in mid:
+        tail = mid.split("/", 1)[1]
+        if tail in rates:
+            return rates[tail]
+    for key, val in rates.items():
+        if key.endswith("/" + mid) or key.endswith(mid):
+            return val
+    return None
+
+
+def estimate_run_cost_usd(run: dict[str, Any]) -> float | None:
+    model = str(run.get("model") or "").strip()
+    rates = _lookup(model)
+    if not rates:
+        return None
+    sim = [e for e in (run.get("events") or []) if isinstance(e, dict) and e.get("kind") == "sim"]
+    # Count agent (protagonist) turns only — same as server task cost.
+    calls = sum(
+        1
+        for e in sim
+        if e.get("role") in ("pm", "salesops", "sales_rep", "assistant")
+        and str(e.get("content") or "").strip()
+    )
+    if calls <= 0:
+        return None
+    usd = calls * (_AVG_IN * rates["input"] + _AVG_OUT * rates["output"])
+    return round(usd, 8)

vantage_core/data/model_rates_slim.json

@@ -0,0 +1,9 @@
+{
+  "openai/gpt-4o-mini": {"input_token_rate_usd": 0.00000015, "output_token_rate_usd": 0.0000006},
+  "openai/gpt-4o": {"input_token_rate_usd": 0.0000025, "output_token_rate_usd": 0.00001},
+  "amazon/nova-micro-v1": {"input_token_rate_usd": 0.000000035, "output_token_rate_usd": 0.00000014},
+  "amazon/nova-lite-v1": {"input_token_rate_usd": 0.00000006, "output_token_rate_usd": 0.00000024},
+  "anthropic/claude-haiku-4.5": {"input_token_rate_usd": 0.000001, "output_token_rate_usd": 0.000005},
+  "anthropic/claude-sonnet-4": {"input_token_rate_usd": 0.000003, "output_token_rate_usd": 0.000015},
+  "google/gemini-2.5-flash": {"input_token_rate_usd": 0.0000003, "output_token_rate_usd": 0.0000025}
+}