tabagent 0.1.0__py3-none-any.whl

tabagent/__init__.py

@@ -0,0 +1,57 @@
+"""TabAgent: replace an LLM agent's closed-set decision heads with a cheap tabular classifier.
+
+The framework has three parts, named as in the paper:
+
+* **TabSchema** extracts schema, state and dependency features from an agent's successful trajectories.
+* **TabSynth** adds schema-aligned, label-preserving paraphrase rows where trajectory coverage is thin.
+* **TabHead** is a tabular classifier that scores every candidate of a decision in a single pass.
+
+The library logs progress (onboarding stages, TabSchema discovery, cross-validation folds, downloads) to the
+``tabagent`` logger at INFO level; enable it with ``logging.basicConfig(level=logging.INFO)`` or the CLI's
+``-v``.
+"""
+
+import logging
+
+from tabagent.agent import TabAgent
+from tabagent.api import TabAgentHead, load, onboard
+from tabagent.evaluation import cross_validate, cross_validate_discovery
+from tabagent.scanner import LogCheck, ScanReport, check_logs, scan
+from tabagent.sklearn import TabAgentClassifier, TabAgentRanker, TabAgentRouter, pointwise, scorer
+from tabagent.tabhead import TabHead
+from tabagent.table import DecisionSpec, DecisionTable, LeakageError
+from tabagent.tabschema import Feature, FeatureCard, TabSchema, TabSchemaConfig
+from tabagent.tabschema.verify import verify_head
+from tabagent.tabsynth import TabSynth
+
+__version__ = "0.1.0"
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "DecisionSpec",
+    "DecisionTable",
+    "Feature",
+    "FeatureCard",
+    "LeakageError",
+    "LogCheck",
+    "ScanReport",
+    "TabAgent",
+    "TabAgentClassifier",
+    "TabAgentHead",
+    "TabAgentRanker",
+    "TabAgentRouter",
+    "TabHead",
+    "TabSchema",
+    "TabSchemaConfig",
+    "TabSynth",
+    "check_logs",
+    "cross_validate",
+    "cross_validate_discovery",
+    "load",
+    "onboard",
+    "pointwise",
+    "scan",
+    "scorer",
+    "verify_head",
+]

tabagent/adapters/__init__.py

@@ -0,0 +1,68 @@
+"""Trajectory adapters: read an agent's native logs into TabSchema trajectories and decision points.
+
+An adapter implements ``load(path) -> list[Trajectory]``, ``decision_points(traj, target)``,
+``candidates(dp)``, ``labels(dp)`` and ``components(trajs)``, and exposes ``outcome_keys``. A decision
+point's ``prefix`` holds only what was known before the decision (``{<task fields>, "steps": [{"name": ...,
+...}]}``); ``labels`` may read the full run (for tool shortlisting, the tools the successful run used).
+
+For ``tabagent.scan`` an adapter may also implement ``llm_calls(traj) -> list[LLMCall]``: every LLM call of a
+run, with what it chose, what it was offered, the free text it wrote and the tokens, latency and cost the log
+records (``read_usage`` reads the common shapes), plus ``scan_notes`` on how its logs record them. All the
+adapters below implement it.
+
+* ``OpenAIMessagesAdapter``: chat-message runs (OpenAI, Anthropic Messages API format, LangChain dumps);
+* ``Tau2Adapter``: τ²-bench results files;
+* ``CugaAdapter``: CUGA agent trajectories (the API shortlister built in);
+* ``GenericJsonAdapter``: any log with named steps, with your own candidates and labels;
+* ``detect_adapter(path)``: picks one of the above from the first files.
+
+Every adapter reads files through ``tabagent.adapters.logfiles``: encodings, damaged JSON and JSON Lines,
+linked folders, values nested too deeply, and large inputs read again from their files instead of held in
+memory. Whatever is skipped or repaired is reported in the adapter's ``warnings``, runs of another log format
+included (``detect_adapter(..., on_other_formats="error")`` refuses them with ``MixedFormatsError``).
+``tabagent.check_logs`` (CLI ``tabagent check-logs``) diagnoses a log folder before an onboarding.
+
+At decision time, ``live_prefix(adapter, run, target)`` builds a live run's prefix exactly as in training, and
+``describe_adapter`` / ``adapter_from_description`` record and rebuild the adapter a head was trained with.
+"""
+
+from tabagent.adapters.common import parse_catalog
+from tabagent.adapters.cuga import SHORTLISTER, CugaAdapter
+from tabagent.adapters.detect import detect_adapter, detect_format
+from tabagent.adapters.live import describe as describe_adapter
+from tabagent.adapters.live import from_description as adapter_from_description
+from tabagent.adapters.live import live_prefix, run_before
+from tabagent.adapters.logfiles import LogChangedError, MixedFormatsError
+from tabagent.adapters.openai_messages import (
+    NEXT_TOOL_CALL,
+    TEXT_REPLY,
+    TOOL_SHORTLIST,
+    OpenAIMessagesAdapter,
+    normalize_messages,
+)
+from tabagent.adapters.tau2 import Tau2Adapter
+from tabagent.tabschema.trajectory import GenericJsonAdapter, LLMCall, output_fields, read_usage
+
+__all__ = [
+    "NEXT_TOOL_CALL",
+    "SHORTLISTER",
+    "TEXT_REPLY",
+    "TOOL_SHORTLIST",
+    "CugaAdapter",
+    "GenericJsonAdapter",
+    "LLMCall",
+    "LogChangedError",
+    "MixedFormatsError",
+    "OpenAIMessagesAdapter",
+    "Tau2Adapter",
+    "adapter_from_description",
+    "describe_adapter",
+    "detect_adapter",
+    "detect_format",
+    "live_prefix",
+    "normalize_messages",
+    "output_fields",
+    "parse_catalog",
+    "read_usage",
+    "run_before",
+]

tabagent/adapters/common.py

@@ -0,0 +1,138 @@
+"""Helpers shared by the trajectory adapters: finding log files and parsing tool catalogs into candidates."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from tabagent.adapters.logfiles import (  # noqa: F401 - re-exported: the adapters' file helpers
+    SKIP_FILES,
+    LogParseError,
+    iter_files,
+    parse_bytes,
+    run_id,
+)
+from tabagent.tabschema.trajectory import Candidate, parse_json, spec_text
+
+_PARAM_KEYS = ("parameters", "input_schema", "inputSchema", "args_schema")
+_SPEC_KEYS = frozenset({"description", "api_name", "function", "properties", *_PARAM_KEYS})
+#: Keys of a JSON Schema (an object's argument schema), never tool names.
+_SCHEMA_KEYS = frozenset(
+    {"type", "required", "items", "enum", "additionalProperties", "$schema", "$defs", "title", "default"}
+)
+
+
+def _is_spec(d: Any) -> bool:
+    return isinstance(d, dict) and (bool(_SPEC_KEYS & d.keys()) or isinstance(d.get("name"), str))
+
+
+def is_tool_schema(d: Any) -> bool:
+    """Whether ``d`` is a tool schema with its parameters (OpenAI, a bare function, the Anthropic Messages API
+    format, MCP, CUGA API docs), as opposed to a ``{"name", "description", "args"}`` candidate record."""
+    return isinstance(d, dict) and (
+        isinstance(d.get("function"), dict) or any(k in d for k in (*_PARAM_KEYS, "properties", "api_name"))
+    )
+
+
+def _arg_names(params: Any) -> list[str]:
+    """Argument names from a parameter schema: the ``properties`` of a JSON Schema, or CUGA's
+    ``[{"name": ...}, ...]``; anything malformed gives no names."""
+    if isinstance(params, dict):
+        props = params.get("properties")
+        if isinstance(props, dict):
+            return [str(a) for a in props]
+        params = props
+    if isinstance(params, list):
+        return [str(a["name"]) for a in params if isinstance(a, dict) and isinstance(a.get("name"), str)]
+    return []
+
+
+def _text(value: Any) -> str:
+    if value is None:
+        return ""
+    return value if isinstance(value, str) else json.dumps(value, default=str, ensure_ascii=False)
+
+
+def tool_candidate(spec: dict[str, Any], name: str = "", volatile_keys: Iterable[str] = ()) -> Candidate:
+    """One tool schema (OpenAI, Anthropic Messages API format, MCP, CUGA API docs) -> ``Candidate``, the
+    schema itself kept as its catalog entry (``Candidate.spec``), without its top-level ``volatile_keys``."""
+    f = spec["function"] if isinstance(spec.get("function"), dict) else spec
+    params = next((f[k] for k in _PARAM_KEYS if k in f), f if "properties" in f else None)
+    raw_name = f.get("name") or f.get("api_name") or name
+    tid = raw_name.strip() if isinstance(raw_name, str) else str(raw_name) if raw_name is not None else ""
+    return Candidate(
+        tid, tid, _text(f.get("description")), ", ".join(_arg_names(params)), spec_text(spec, volatile_keys)
+    )
+
+
+def parse_catalog(catalog: Any, volatile_keys: Iterable[str] = ()) -> dict[str, Candidate]:
+    """A tool catalog in any common shape -> ``{tool id: Candidate}``.
+
+    Accepts a JSON file path; a list of ``Candidate`` objects, tool names or tool schemas (OpenAI
+    ``{"type": "function", "function": {...}}``, bare functions, the Anthropic Messages API format's
+    ``input_schema``, MCP ``inputSchema``); a ``{name: description}`` or ``{name: schema}`` mapping; and
+    CUGA API docs (``{app: {api_name: {...}}}``). Argument hints are the parameter names, comma-joined, and a
+    schema is kept as the candidate's catalog entry (``Candidate.spec``), without its top-level
+    ``volatile_keys``: fields a catalog writes anew in every run (CUGA's ``canary_string``). A tool listed
+    twice keeps its last entry; entries without a name are left out.
+    """
+    if catalog is None:
+        return {}
+    if isinstance(catalog, (str, Path)):
+        p = Path(catalog)
+        if not p.is_file():
+            raise FileNotFoundError(
+                f"tool catalog {str(catalog)[:200]!r}: no such file; pass the path of a JSON file with tool "
+                "schemas, or the catalog itself (a list of schemas or a {name: description} mapping)"
+            )
+        try:
+            data = parse_bytes(p.read_bytes())
+        except LogParseError as e:
+            raise ValueError(f"tool catalog {p}: not valid JSON ({e})") from None
+        return parse_catalog(data, volatile_keys)
+    if isinstance(catalog, dict) and _is_spec(catalog):
+        catalog = [catalog]
+    out: dict[str, Candidate] = {}
+    if isinstance(catalog, dict):
+        for key, v in catalog.items():
+            if isinstance(v, str):
+                out[str(key)] = Candidate(str(key), str(key), v)
+            elif _is_spec(v) or (isinstance(v, dict) and _SCHEMA_KEYS & v.keys()):  # a bare argument schema
+                c = tool_candidate(v, str(key), volatile_keys)
+                out[c.id] = c
+            elif isinstance(v, (dict, list)):  # one level of grouping, e.g. CUGA apps
+                out.update(parse_catalog(v, volatile_keys))
+        return {k: c for k, c in out.items() if k}
+    if not isinstance(catalog, (list, tuple)):
+        return {}
+    for item in catalog:
+        if isinstance(item, Candidate):
+            c = item
+        elif isinstance(item, str):
+            c = Candidate(item.strip(), item.strip())
+        elif isinstance(item, dict):
+            c = tool_candidate(item, volatile_keys=volatile_keys)
+        else:
+            continue
+        if c.id:
+            out[c.id] = c
+    return out
+
+
+def run_catalog(value: Any) -> tuple[dict[str, Candidate], bool]:
+    """The catalog a run's own ``tools`` field records, and whether the field could be read as one: a list or
+    mapping of tools, or JSON text of one (some loggers write the list as a string). Never a file path."""
+    if value is None or value == "" or value == [] or value == {}:
+        return {}, True
+    if isinstance(value, str):
+        value = parse_json(value)
+        if value is None:
+            return {}, False
+    if not isinstance(value, (list, dict)):
+        return {}, False
+    try:
+        return parse_catalog(value), True
+    except (TypeError, ValueError, AttributeError):
+        return {}, False