tiltmeter 0.1.0__py3-none-any.whl

tiltmeter/__init__.py

@@ -0,0 +1,5 @@
+"""Tiltmeter: an early-warning system for the APIs your AI agents depend on."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

tiltmeter/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m tiltmeter``."""
+
+from tiltmeter.cli import main
+
+if __name__ == "__main__":
+    main()

tiltmeter/cli.py

@@ -0,0 +1,331 @@
+"""The ``tiltmeter`` command.
+
+Exit codes, so CI can gate on drift:
+
+* 0: no drift (info-only changes and new baselines included)
+* 1: warning-level drift
+* 2: breaking drift
+* 3: a check could not run (network error, bad status, invalid JSON) and nothing broke
+* 4: usage or configuration error
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from collections.abc import Coroutine, Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any, Final, NoReturn
+
+import typer
+from rich.console import Console
+
+from tiltmeter import __version__
+from tiltmeter.config import DEFAULT_CONFIG_FILE, EXAMPLE_CONFIG
+from tiltmeter.core.models import CheckResult, Severity, max_severity
+from tiltmeter.errors import TiltmeterError
+
+if TYPE_CHECKING:
+    from tiltmeter.service import DriftService
+
+EXIT_OK: Final = 0
+EXIT_WARNING: Final = 1
+EXIT_BREAKING: Final = 2
+EXIT_CHECK_FAILED: Final = 3
+EXIT_USAGE: Final = 4
+
+STATE_IGNORE_LINE: Final = ".tiltmeter/"
+
+app = typer.Typer(
+    name="tiltmeter",
+    help="Catch API schema drift before your AI agents do.",
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_enable=False,
+)
+out = Console(highlight=False)
+err = Console(stderr=True, highlight=False)
+
+ConfigOption = Annotated[
+    Path,
+    typer.Option(
+        "--config", "-c", envvar="TILTMETER_CONFIG", help="Path to the configuration file."
+    ),
+]
+JsonOption = Annotated[bool, typer.Option("--json", help="Print JSON instead of tables.")]
+EndpointsOption = Annotated[
+    list[str] | None,
+    typer.Option("--endpoint", "-e", help="Only these endpoint ids (repeatable)."),
+]
+NoLLMOption = Annotated[bool, typer.Option("--no-llm", help="Skip Claude explanations.")]
+NoNotifyOption = Annotated[bool, typer.Option("--no-notify", help="Do not send notifications.")]
+
+
+def exit_code_for(results: Sequence[CheckResult]) -> int:
+    """Breaking beats a failed check, which beats a warning."""
+    worst = max_severity(result.max_severity for result in results)
+    if worst is Severity.BREAKING:
+        return EXIT_BREAKING
+    if any(result.error for result in results):
+        return EXIT_CHECK_FAILED
+    if worst is Severity.WARNING:
+        return EXIT_WARNING
+    return EXIT_OK
+
+
+def _fail(message: str, code: int = EXIT_USAGE) -> NoReturn:
+    err.print(f"[bold red]error:[/] {message}", markup=True, highlight=False)
+    raise typer.Exit(code)
+
+
+def _service(config: Path) -> DriftService:
+    from tiltmeter.service import DriftService  # deferred: keeps --help fast
+
+    try:
+        return DriftService.from_config_file(config)
+    except TiltmeterError as exc:
+        _fail(str(exc))
+
+
+@contextmanager
+def _opened(config: Path) -> Iterator[DriftService]:
+    service = _service(config)
+    try:
+        yield service
+    finally:
+        asyncio.run(service.aclose())
+
+
+def _run[T](coroutine: Coroutine[Any, Any, T]) -> T:
+    try:
+        return asyncio.run(coroutine)
+    except TiltmeterError as exc:
+        _fail(str(exc))
+
+
+async def _pause(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+def _print_json(data: Any) -> None:
+    sys.stdout.write(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+def _emit(results: Sequence[CheckResult], as_json: bool) -> None:
+    if as_json:
+        _print_json([result.model_dump(mode="json") for result in results])
+    else:
+        from tiltmeter.console import render_results
+
+        render_results(out, results)
+
+
+def _version(value: bool) -> None:
+    if value:
+        out.print(f"tiltmeter {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=_version, is_eager=True, help="Show the version."),
+    ] = False,
+) -> None:
+    """Catch API schema drift before your AI agents do.
+
+    Tiltmeter calls the APIs you declare in tiltmeter.yaml, learns the shape of
+    their JSON responses, and tells you (or your agents) when it changes.
+    """
+
+
+@app.command()
+def init(
+    path: Annotated[Path, typer.Argument(help="Where to write the config.")] = Path(
+        DEFAULT_CONFIG_FILE
+    ),
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing file.")] = False,
+) -> None:
+    """Write a starter tiltmeter.yaml."""
+    if path.exists() and not force:
+        _fail(f"{path} already exists (use --force to overwrite it)")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(EXAMPLE_CONFIG, encoding="utf-8")
+    out.print(f"[green]✓[/] wrote {path}")
+    gitignore = path.parent / ".gitignore"
+    if gitignore.exists() or (path.parent / ".git").exists():
+        existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+        if STATE_IGNORE_LINE not in existing.splitlines():
+            prefix = "" if not existing or existing.endswith("\n") else "\n"
+            with gitignore.open("a", encoding="utf-8") as handle:
+                handle.write(f"{prefix}{STATE_IGNORE_LINE}\n")
+            out.print(f"[green]✓[/] added {STATE_IGNORE_LINE} to {gitignore}")
+    out.print("Next: edit the endpoints, then run [bold]tiltmeter check[/].")
+
+
+@app.command()
+def check(
+    config: ConfigOption = Path(DEFAULT_CONFIG_FILE),
+    endpoint: EndpointsOption = None,
+    as_json: JsonOption = False,
+    no_llm: NoLLMOption = False,
+    no_notify: NoNotifyOption = False,
+) -> None:
+    """Check endpoints once. The exit code tells CI how bad the drift is."""
+
+    async def run() -> list[CheckResult]:
+        async with _service(config) as service:
+            return await service.check(endpoint, explain=not no_llm, notify=not no_notify)
+
+    results = _run(run())
+    _emit(results, as_json)
+    raise typer.Exit(exit_code_for(results))
+
+
+@app.command()
+def watch(
+    config: ConfigOption = Path(DEFAULT_CONFIG_FILE),
+    interval: Annotated[
+        float, typer.Option("--interval", "-i", min=5, help="Seconds between rounds.")
+    ] = 300.0,
+    endpoint: EndpointsOption = None,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Print one JSON line per check (JSON Lines).")
+    ] = False,
+    no_llm: NoLLMOption = False,
+    no_notify: NoNotifyOption = False,
+) -> None:
+    """Check endpoints forever, every --interval seconds. Stop with Ctrl+C."""
+
+    async def run() -> None:
+        async with _service(config) as service:
+            while True:
+                results = await service.check(endpoint, explain=not no_llm, notify=not no_notify)
+                if as_json:
+                    for result in results:
+                        sys.stdout.write(result.model_dump_json() + "\n")
+                    sys.stdout.flush()
+                else:
+                    from tiltmeter.console import render_results
+
+                    render_results(out, results)
+                await _pause(interval)
+
+    try:
+        _run(run())
+    except KeyboardInterrupt:
+        err.print("stopped")
+
+
+@app.command()
+def history(
+    endpoint_id: Annotated[str | None, typer.Argument(help="Only this endpoint.")] = None,
+    config: ConfigOption = Path(DEFAULT_CONFIG_FILE),
+    limit: Annotated[int, typer.Option("--limit", "-n", min=1, max=10_000)] = 20,
+    as_json: JsonOption = False,
+) -> None:
+    """List recent checks, newest first."""
+    with _opened(config) as service:
+        checks = service.history(endpoint_id, limit=limit)
+    if as_json:
+        _print_json([check.model_dump(mode="json") for check in checks])
+        return
+    if not checks:
+        out.print("No checks yet. Run [bold]tiltmeter check[/].")
+        return
+    from tiltmeter.console import history_table
+
+    out.print(history_table(checks))
+
+
+@app.command()
+def show(
+    check_id: Annotated[int, typer.Argument(help="Check id, as listed by `history`.")],
+    config: ConfigOption = Path(DEFAULT_CONFIG_FILE),
+    as_json: JsonOption = False,
+) -> None:
+    """Show one check: its changes and explanation."""
+    with _opened(config) as service:
+        result = service.get_check(check_id)
+    if result is None:
+        _fail(f"no check with id {check_id}")
+    if as_json:
+        _print_json(result.model_dump(mode="json"))
+    else:
+        from tiltmeter.console import render_result
+
+        render_result(out, result, show_id=True)
+
+
+@app.command()
+def schema(
+    endpoint_id: Annotated[str, typer.Argument(help="Endpoint id from the config.")],
+    config: ConfigOption = Path(DEFAULT_CONFIG_FILE),
+) -> None:
+    """Print the JSON Schema Tiltmeter has learned for an endpoint."""
+    with _opened(config) as service:
+        try:
+            report = service.schema(endpoint_id)
+        except TiltmeterError as exc:
+            _fail(str(exc))
+    if report.json_schema is None:
+        _fail(f"no baseline for {endpoint_id} yet; run `tiltmeter check` first", EXIT_CHECK_FAILED)
+    _print_json(report.json_schema)
+
+
+@app.command()
+def explain(
+    check_id: Annotated[int, typer.Argument(help="Check id, as listed by `history`.")],
+    config: ConfigOption = Path(DEFAULT_CONFIG_FILE),
+    as_json: JsonOption = False,
+) -> None:
+    """Ask Claude to explain the changes a past check found (needs ANTHROPIC_API_KEY)."""
+
+    async def run() -> CheckResult:
+        async with _service(config) as service:
+            return await service.explain_check(check_id)
+
+    try:
+        result = _run(run())
+    except typer.Exit:
+        raise
+    except Exception as exc:  # API errors from the model provider: no traceback for users
+        _fail(f"explanation failed: {exc}", EXIT_CHECK_FAILED)
+    if as_json:
+        _print_json(result.model_dump(mode="json"))
+    else:
+        from tiltmeter.console import render_result
+
+        render_result(out, result, show_id=True)
+
+
+@app.command()
+def serve(config: ConfigOption = Path(DEFAULT_CONFIG_FILE)) -> None:
+    """Run the MCP server on stdio, for Claude Code, Cursor and other MCP clients."""
+    from tiltmeter.mcp_server.server import run_stdio
+
+    try:
+        run_stdio(config)
+    except TiltmeterError as exc:
+        _fail(str(exc))
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Entry point. Maps usage errors to exit code 4 so they never look like drift."""
+    try:
+        result = app(args=list(argv) if argv is not None else None, standalone_mode=False)
+    except typer.TyperException as exc:
+        show_error = getattr(exc, "show", None)
+        if callable(show_error):
+            show_error()
+        else:
+            err.print(str(exc))
+        no_arguments = type(exc).__name__ == "NoArgsIsHelpError"
+        sys.exit(EXIT_OK if no_arguments else EXIT_USAGE)
+    except typer.Abort:
+        err.print("aborted")
+        sys.exit(130)
+    sys.exit(result if isinstance(result, int) else EXIT_OK)

tiltmeter/config.py

@@ -0,0 +1,246 @@
+"""The ``tiltmeter.yaml`` file: which endpoints to watch and how.
+
+Values may contain ``${VAR}`` or ``${VAR:-default}`` placeholders. They are kept
+as written in memory and only expanded when a request or notification is sent,
+so secrets never sit in the config objects that get logged or traced.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Annotated, Any, Literal
+from urllib.parse import urlsplit, urlunsplit
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+from tiltmeter.core.models import ChangeKind, Severity
+from tiltmeter.core.paths import PathPattern, PathSyntaxError
+from tiltmeter.errors import ConfigError, UnknownEndpointError
+
+DEFAULT_CONFIG_FILE = "tiltmeter.yaml"
+DEFAULT_MODEL = "claude-haiku-5-5"
+
+type HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+type Effort = Literal["low", "medium", "high", "xhigh", "max"]
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+def _stringify(value: Any) -> Any:
+    """YAML turns ``limit: 3`` into an int; headers and params must be strings."""
+    if isinstance(value, dict):
+        return {str(k): ("" if v is None else str(v)) for k, v in value.items()}
+    return value
+
+
+class EndpointConfig(_Model):
+    """One HTTP endpoint to watch."""
+
+    id: str = Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9_.\-]{0,63}$")
+    url: str
+    method: HttpMethod = "GET"
+    description: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+    params: dict[str, str] = Field(default_factory=dict)
+    body: Any = None
+    timeout: float = Field(default=10.0, gt=0, le=300)
+    retries: int = Field(default=2, ge=0, le=10)
+    sample_size: int = Field(default=1, ge=1, le=20)
+    max_body_bytes: int = Field(default=5_000_000, ge=1_000, le=200_000_000)
+    ignore_paths: list[str] = Field(default_factory=list)
+    strict: bool = False
+    baseline_window: int = Field(default=20, ge=1, le=500)
+    latency_factor: float | None = Field(default=3.0, gt=1)
+    severity_overrides: dict[ChangeKind, Severity] = Field(default_factory=dict)
+    store_samples: bool = False
+
+    @field_validator("method", mode="before")
+    @classmethod
+    def _upper_method(cls, value: Any) -> Any:
+        return value.upper() if isinstance(value, str) else value
+
+    @field_validator("headers", "params", mode="before")
+    @classmethod
+    def _string_values(cls, value: Any) -> Any:
+        return _stringify(value)
+
+    @field_validator("url")
+    @classmethod
+    def _check_url(cls, value: str) -> str:
+        if not value.startswith(("http://", "https://", "${")):
+            raise ValueError("must start with http:// or https:// (or a ${VAR} placeholder)")
+        return value
+
+    @field_validator("ignore_paths")
+    @classmethod
+    def _check_patterns(cls, value: list[str]) -> list[str]:
+        for pattern in value:
+            try:
+                PathPattern(pattern)
+            except PathSyntaxError as exc:
+                raise ValueError(str(exc)) from exc
+        return value
+
+    def display_url(self) -> str:
+        """The URL as written, without query string or fragment (they often hold keys)."""
+        parts = urlsplit(self.url)
+        return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
+
+
+class SlackNotifierConfig(_Model):
+    """Post to a Slack incoming webhook."""
+
+    type: Literal["slack"]
+    webhook_url: str
+    min_severity: Severity = Severity.WARNING
+    on_error: bool = False
+
+
+class WebhookNotifierConfig(_Model):
+    """POST the check result as JSON to any URL."""
+
+    type: Literal["webhook"]
+    url: str
+    headers: dict[str, str] = Field(default_factory=dict)
+    min_severity: Severity = Severity.WARNING
+    on_error: bool = False
+
+    @field_validator("headers", mode="before")
+    @classmethod
+    def _string_values(cls, value: Any) -> Any:
+        return _stringify(value)
+
+
+type NotifierConfig = Annotated[
+    SlackNotifierConfig | WebhookNotifierConfig, Field(discriminator="type")
+]
+
+
+class LLMConfig(_Model):
+    """Optional drift explanations written by Claude."""
+
+    enabled: bool = True
+    model: str = DEFAULT_MODEL
+    effort: Effort | None = "low"
+    max_tokens: int = Field(default=2048, ge=256, le=32_000)
+    timeout: float = Field(default=60.0, gt=0, le=600)
+    min_severity: Severity = Severity.WARNING
+    include_samples: bool = False
+
+
+class Config(_Model):
+    """The whole configuration file."""
+
+    version: Literal[1] = 1
+    state_dir: str = ".tiltmeter"
+    concurrency: int = Field(default=5, ge=1, le=64)
+    keep_checks: int = Field(default=500, ge=10, le=100_000)
+    severity_overrides: dict[ChangeKind, Severity] = Field(default_factory=dict)
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    notify: list[NotifierConfig] = Field(default_factory=list)
+    endpoints: list[EndpointConfig] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _unique_ids(self) -> Config:
+        seen: set[str] = set()
+        for endpoint in self.endpoints:
+            if endpoint.id in seen:
+                raise ValueError(f"duplicate endpoint id {endpoint.id!r}")
+            seen.add(endpoint.id)
+        return self
+
+    @property
+    def endpoint_ids(self) -> list[str]:
+        return [endpoint.id for endpoint in self.endpoints]
+
+    def endpoint(self, endpoint_id: str) -> EndpointConfig:
+        for endpoint in self.endpoints:
+            if endpoint.id == endpoint_id:
+                return endpoint
+        raise UnknownEndpointError(endpoint_id, self.endpoint_ids)
+
+    def select(self, endpoint_ids: Sequence[str] | None = None) -> list[EndpointConfig]:
+        """The endpoints with these ids, in the given order; all of them when empty."""
+        if not endpoint_ids:
+            return list(self.endpoints)
+        return [self.endpoint(endpoint_id) for endpoint_id in dict.fromkeys(endpoint_ids)]
+
+    def overrides_for(self, endpoint: EndpointConfig) -> dict[ChangeKind, Severity]:
+        """Global severity overrides, with the endpoint's own taking precedence."""
+        return {**self.severity_overrides, **endpoint.severity_overrides}
+
+
+def load_config(path: Path) -> Config:
+    """Read and validate a config file, with readable errors."""
+    if not path.is_file():
+        raise ConfigError(f"config file not found: {path} (run `tiltmeter init` to create one)")
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: invalid YAML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: expected a mapping with an `endpoints` list at the top level")
+    try:
+        return Config.model_validate(data)
+    except ValidationError as exc:
+        raise ConfigError(f"{path}: invalid configuration\n{format_validation_error(exc)}") from exc
+
+
+def format_validation_error(exc: ValidationError) -> str:
+    lines = []
+    for error in exc.errors():
+        location = ".".join(str(part) for part in error["loc"]) or "(root)"
+        lines.append(f"  - {location}: {error['msg']}")
+    return "\n".join(lines)
+
+
+def resolve_state_dir(config: Config, config_path: Path) -> Path:
+    """``state_dir`` resolved relative to the config file's folder."""
+    state_dir = Path(config.state_dir).expanduser()
+    if not state_dir.is_absolute():
+        state_dir = config_path.resolve().parent / state_dir
+    return state_dir
+
+
+EXAMPLE_CONFIG = """\
+# tiltmeter configuration. Docs: see README.md
+version: 1
+
+endpoints:
+  # A public API, no credentials needed.
+  - id: github_repo
+    description: Repository metadata from the GitHub REST API
+    url: https://api.github.com/repos/langchain-ai/langchain
+    headers:
+      Accept: application/vnd.github+json
+
+  # Secrets come from environment variables and are expanded at request time.
+  # - id: stripe_customers
+  #   url: https://api.stripe.com/v1/customers
+  #   params:
+  #     limit: 10
+  #   headers:
+  #     Authorization: Bearer ${STRIPE_API_KEY}
+  #   ignore_paths:
+  #     - $.data[*].metadata      # free-form, changes all the time
+  #   severity_overrides:
+  #     field_now_optional: warning
+
+# Explanations written by Claude when drift is detected (needs ANTHROPIC_API_KEY).
+llm:
+  enabled: true
+  model: claude-haiku-5-5
+
+# Where to send alerts.
+notify: []
+#  - type: slack
+#    webhook_url: ${SLACK_WEBHOOK_URL}
+#    min_severity: warning
+#  - type: webhook
+#    url: https://example.com/hooks/tiltmeter
+#    min_severity: breaking
+"""