tiltmeter 0.1.0__tar.gz

tiltmeter-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# tiltmeter runtime state (baselines, history)
+.tiltmeter/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Local secrets
+.env

tiltmeter-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to Tiltmeter are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Until 1.0,
+a minor release may include breaking changes.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-21
+
+First public release, with the same features as 0.1.0rc1.
+
+## [0.1.0rc1] - 2026-10-21
+
+First release candidate, published to TestPyPI only.
+
+### Added
+
+- Learn the shape of JSON responses from real traffic and compare every check with a
+  rolling baseline of recent responses, with no spec required.
+- Classify changes as breaking, warning or info: removed, newly optional, retyped and newly
+  nullable fields, new enum values, status and content-type changes, latency regressions
+  and new fields, with hints for probable renames.
+- The `tiltmeter` command with `init`, `check`, `watch`, `history`, `show`, `schema`,
+  `explain` and `serve`, and exit codes for CI.
+- An MCP server with `has_drifted`, `get_schema`, `get_changes`, `list_endpoints`,
+  `check_api` and `check_all`, plus endpoint and schema resources.
+- Optional drift explanations written by Claude through LangChain, using structured
+  outputs.
+- Slack and webhook notifications.
+- A local SQLite history with content-addressed shapes and retention.

tiltmeter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agustin Torres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiltmeter-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: tiltmeter
+Version: 0.1.0
+Summary: An early-warning system for the third-party APIs your AI agents depend on: CLI, CI gate and MCP server.
+Project-URL: Homepage, https://github.com/tiltmeter-dev/tiltmeter
+Project-URL: Documentation, https://github.com/tiltmeter-dev/tiltmeter/tree/main/docs
+Project-URL: Changelog, https://github.com/tiltmeter-dev/tiltmeter/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/tiltmeter-dev/tiltmeter/issues
+Project-URL: Source, https://github.com/tiltmeter-dev/tiltmeter
+Author: Agustin Torres
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,api,contract-testing,json-schema,langgraph,mcp,monitoring,schema-drift
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: langchain-anthropic<2,>=1.7
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: langgraph<2,>=1.0
+Requires-Dist: langsmith>=0.3.0
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# Tiltmeter
+
+[![PyPI](https://img.shields.io/pypi/v/tiltmeter.svg)](https://pypi.org/project/tiltmeter/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://github.com/tiltmeter-dev/tiltmeter/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/tiltmeter-dev/tiltmeter/blob/main/LICENSE)
+
+**An early-warning system for the third-party APIs your AI agents depend on.**
+
+
+
+Volcanologists bolt tiltmeters to the ground to sense tiny deformations long before an
+eruption. Tiltmeter does the same for the APIs under your agents. It learns the shape of
+their JSON responses from real traffic, notices when a vendor renames a field, starts
+sending `null` or turns a number into a string, and tells you, your CI and the agents
+themselves before anything goes on tilt.
+
+Typed code crashes loudly when an API changes. Agents don't. They read the new response,
+fill the gaps with guesses, or retry until the budget is gone.
+
+## Highlights
+
+- **Agents can check before they act.** An MCP server lets Claude Code, Cursor, LangChain
+  or any MCP client call `has_drifted` before trusting an API, and `get_schema` to see
+  which fields to expect.
+- **No spec required.** Tiltmeter learns from real responses, so it works with any JSON
+  API, documented or not.
+- **Breaking or harmless, at a glance.** Every change is classified as breaking, warning
+  or info, and a removed field next to a similar new one is flagged as a probable rename.
+- **Explanations on demand.** With an Anthropic API key, Claude explains what changed,
+  the likely cause and what to do about it.
+- **A CI gate with alerts.** Exit codes fail the build on breaking drift. Slack and
+  webhook alerts take one line of config.
+- **Local and private.** One SQLite file and no account. Credentials are expanded at
+  request time and never stored. Response bodies are not stored or sent to the LLM, only
+  their shape.
+
+## Quickstart
+
+```bash
+pip install tiltmeter        # or: uv tool install tiltmeter
+tiltmeter init               # writes tiltmeter.yaml with a public example API
+tiltmeter check              # the first check records the baseline
+```
+
+Run `tiltmeter check` again from cron or CI, or leave `tiltmeter watch` running. This is
+what you get when a vendor renames `phone` and turns `balance` into a string:
+
+```console
+$ tiltmeter check
+✗ billing_customers  200 · 13 ms  BREAKING · 3 changes
+    breaking  type_changed   $.data[*].balance       integer → string
+    breaking  field_removed  $.data[*].phone         string → (absent)  possibly renamed to $.data[*].phone_number
+    info      field_added    $.data[*].phone_number  (absent) → string  possibly replaces $.data[*].phone
+1 endpoint checked · 1 breaking
+$ echo $?
+2
+```
+
+The [getting started guide](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/getting-started.md) runs that exact scenario against a
+fake API on your machine in about five minutes.
+
+## Give your agents a tiltmeter
+
+```bash
+claude mcp add tiltmeter -- tiltmeter serve --config /absolute/path/to/tiltmeter.yaml
+```
+
+Then add a line like this to your agent's instructions:
+
+> Before you rely on a third-party API, call `has_drifted` for it. If it drifted, read the
+> summary and adapt before trusting the response.
+
+| Tool | What it answers |
+|---|---|
+| `has_drifted(endpoint_id, since?)` | Did the responses change at warning level or worse recently? Returns a summary and the changes. |
+| `get_schema(endpoint_id)` | Which fields, types and enum values to expect, as JSON Schema. |
+| `get_changes(endpoint_id?, since?, min_severity?, limit?)` | The change history, newest first. |
+| `list_endpoints()` | Which APIs are watched and how their last check went. |
+| `check_api(endpoint_id, explain?)` | Calls one API now and records the result. |
+| `check_all(explain?)` | Calls every API now. |
+
+Setups for Cursor, Claude Desktop and LangChain agents are in the
+[agents guide](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/agents.md).
+
+## What counts as drift
+
+| Change | Example | Default severity |
+|---|---|---|
+| `field_removed` | `phone` was in every response and is gone | breaking |
+| `field_now_optional` | `email` was always there and is now missing from some objects | breaking |
+| `type_changed` | `balance` went from integer to string | breaking |
+| `nullable_introduced` | `phone` can now be `null` | breaking |
+| `content_type_changed` | the JSON body became an HTML error page | breaking |
+| `status_changed` | 200 to 503 is breaking, 404 to 200 is info, 200 to 202 is a warning | depends |
+| `enum_value_added` | `status` returned `suspended` besides `active` and `past_due` | warning |
+| `latency_regression` | median latency over 3x the baseline and at least 250 ms slower | warning |
+| `field_added` | a new `phone_number` field | info, or warning with `strict: true` |
+
+Override any of them globally or per endpoint with `severity_overrides`.
+
+## Use it in CI
+
+| Exit code | Meaning |
+|---|---|
+| 0 | No drift. Info-only changes and new baselines count as no drift. |
+| 1 | Warning-level drift. |
+| 2 | Breaking drift. |
+| 3 | A check could not run (network error, unexpected status, invalid JSON) and nothing broke. |
+| 4 | Usage or configuration error. |
+
+The baseline lives in `.tiltmeter/`, so keep that folder between runs. The
+[CI guide](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/ci.md) has ready-to-copy jobs for GitHub Actions, GitLab CI and cron.
+
+## How it works
+
+1. **Observe.** A check calls the endpoint and turns the JSON body into a *shape*: for
+   every path, which JSON types appeared, how many objects contained each field and, for
+   fields that look categorical (`active`, `past_due`, `USD`), which values were seen.
+2. **Compare.** The baseline is the merge of the shapes from the last 20 successful
+   checks. Tiltmeter reports only what *contradicts* it: a missing optional field is
+   fine, a field that was in every object and is now gone is not.
+3. **Report once.** The new shape joins the baseline, so the check that sees a change
+   reports it, and from then on it is the new normal.
+
+
+
+The pipeline is a small [LangGraph](https://github.com/langchain-ai/langgraph) graph that
+only sequences the steps. The diff itself is plain, deterministic Python with no LLM in the
+loop. [How it works](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/how-it-works.md) covers the details.
+
+## Configuration
+
+```yaml
+endpoints:
+  - id: stripe_customers
+    url: https://api.stripe.com/v1/customers
+    params:
+      limit: 10
+    headers:
+      Authorization: Bearer ${STRIPE_API_KEY}   # expanded from the environment at request time
+    ignore_paths:
+      - $.data[*].metadata                      # free-form, changes all the time
+
+notify:
+  - type: slack
+    webhook_url: ${SLACK_WEBHOOK_URL}
+```
+
+Every option is described in the [configuration reference](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/configuration.md), and
+[`examples/`](https://github.com/tiltmeter-dev/tiltmeter/blob/main/examples) has a config you can run as is.
+
+## How it compares
+
+- **OpenAPI diff tools** such as oasdiff compare two versions of a spec. They are the right
+  tool when the vendor publishes and maintains one, and they cannot see changes the vendor
+  did not document.
+- **Contract testing** such as Pact needs the provider to run your contracts, which
+  third-party vendors don't do.
+- **Uptime and synthetic monitors** tell you an API is up. You write and maintain the
+  response assertions yourself.
+- **Tiltmeter** learns the contract from real responses, so it needs nothing from the
+  vendor and catches undocumented changes. It also hands what it learns to your agents.
+
+## Privacy and security
+
+- `${VAR}` placeholders are expanded right before a request or notification is sent. The
+  values are never written to disk, sent to the LLM or kept in the LangGraph state, and
+  they are scrubbed from error messages.
+- The history stores shapes, status codes, latencies and changes, never response bodies
+  unless you set `store_samples: true`.
+- Agents can only check the endpoints in your config. They cannot make Tiltmeter call an
+  arbitrary URL.
+
+[SECURITY.md](https://github.com/tiltmeter-dev/tiltmeter/blob/main/SECURITY.md) has the full threat model and how to report a vulnerability.
+
+## Roadmap
+
+- **Auto-fix pull requests.** When a vendor ships a breaking change, an agent built on
+  LangChain Deep Agents finds the affected code in your repository and opens a PR.
+- **Spec and changelog awareness.** Diff vendor OpenAPI specs and changelogs next to
+  observed responses.
+- **Hosted checks** and a team dashboard.
+
+## Documentation
+
+- [Getting started](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/getting-started.md): a five-minute tour on your machine.
+- [Configuration reference](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/configuration.md): every option, placeholders and ignore patterns.
+- [Agents and MCP](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/agents.md): Claude Code, Cursor, Claude Desktop and LangChain.
+- [CI and scheduling](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/ci.md): GitHub Actions, GitLab CI and cron.
+- [How it works](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/how-it-works.md): shapes, baselines, the diff rules and the pipeline.
+- [FAQ and troubleshooting](https://github.com/tiltmeter-dev/tiltmeter/blob/main/docs/faq.md).
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome. [CONTRIBUTING.md](https://github.com/tiltmeter-dev/tiltmeter/blob/main/CONTRIBUTING.md)
+explains how to set up the project and what a good change looks like. Everyone taking
+part is expected to follow the [code of conduct](https://github.com/tiltmeter-dev/tiltmeter/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](https://github.com/tiltmeter-dev/tiltmeter/blob/main/LICENSE)

tiltmeter-0.1.0/README.md

@@ -0,0 +1,214 @@
+# Tiltmeter
+
+[![PyPI](https://img.shields.io/pypi/v/tiltmeter.svg)](https://pypi.org/project/tiltmeter/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**An early-warning system for the third-party APIs your AI agents depend on.**
+
+<!-- pypi-skip-image -->
+![Tiltmeter catching a renamed field and a type change](docs/demo.svg)
+<!-- /pypi-skip-image -->
+
+Volcanologists bolt tiltmeters to the ground to sense tiny deformations long before an
+eruption. Tiltmeter does the same for the APIs under your agents. It learns the shape of
+their JSON responses from real traffic, notices when a vendor renames a field, starts
+sending `null` or turns a number into a string, and tells you, your CI and the agents
+themselves before anything goes on tilt.
+
+Typed code crashes loudly when an API changes. Agents don't. They read the new response,
+fill the gaps with guesses, or retry until the budget is gone.
+
+## Highlights
+
+- **Agents can check before they act.** An MCP server lets Claude Code, Cursor, LangChain
+  or any MCP client call `has_drifted` before trusting an API, and `get_schema` to see
+  which fields to expect.
+- **No spec required.** Tiltmeter learns from real responses, so it works with any JSON
+  API, documented or not.
+- **Breaking or harmless, at a glance.** Every change is classified as breaking, warning
+  or info, and a removed field next to a similar new one is flagged as a probable rename.
+- **Explanations on demand.** With an Anthropic API key, Claude explains what changed,
+  the likely cause and what to do about it.
+- **A CI gate with alerts.** Exit codes fail the build on breaking drift. Slack and
+  webhook alerts take one line of config.
+- **Local and private.** One SQLite file and no account. Credentials are expanded at
+  request time and never stored. Response bodies are not stored or sent to the LLM, only
+  their shape.
+
+## Quickstart
+
+```bash
+pip install tiltmeter        # or: uv tool install tiltmeter
+tiltmeter init               # writes tiltmeter.yaml with a public example API
+tiltmeter check              # the first check records the baseline
+```
+
+Run `tiltmeter check` again from cron or CI, or leave `tiltmeter watch` running. This is
+what you get when a vendor renames `phone` and turns `balance` into a string:
+
+```console
+$ tiltmeter check
+✗ billing_customers  200 · 13 ms  BREAKING · 3 changes
+    breaking  type_changed   $.data[*].balance       integer → string
+    breaking  field_removed  $.data[*].phone         string → (absent)  possibly renamed to $.data[*].phone_number
+    info      field_added    $.data[*].phone_number  (absent) → string  possibly replaces $.data[*].phone
+1 endpoint checked · 1 breaking
+$ echo $?
+2
+```
+
+The [getting started guide](docs/getting-started.md) runs that exact scenario against a
+fake API on your machine in about five minutes.
+
+## Give your agents a tiltmeter
+
+```bash
+claude mcp add tiltmeter -- tiltmeter serve --config /absolute/path/to/tiltmeter.yaml
+```
+
+Then add a line like this to your agent's instructions:
+
+> Before you rely on a third-party API, call `has_drifted` for it. If it drifted, read the
+> summary and adapt before trusting the response.
+
+| Tool | What it answers |
+|---|---|
+| `has_drifted(endpoint_id, since?)` | Did the responses change at warning level or worse recently? Returns a summary and the changes. |
+| `get_schema(endpoint_id)` | Which fields, types and enum values to expect, as JSON Schema. |
+| `get_changes(endpoint_id?, since?, min_severity?, limit?)` | The change history, newest first. |
+| `list_endpoints()` | Which APIs are watched and how their last check went. |
+| `check_api(endpoint_id, explain?)` | Calls one API now and records the result. |
+| `check_all(explain?)` | Calls every API now. |
+
+Setups for Cursor, Claude Desktop and LangChain agents are in the
+[agents guide](docs/agents.md).
+
+## What counts as drift
+
+| Change | Example | Default severity |
+|---|---|---|
+| `field_removed` | `phone` was in every response and is gone | breaking |
+| `field_now_optional` | `email` was always there and is now missing from some objects | breaking |
+| `type_changed` | `balance` went from integer to string | breaking |
+| `nullable_introduced` | `phone` can now be `null` | breaking |
+| `content_type_changed` | the JSON body became an HTML error page | breaking |
+| `status_changed` | 200 to 503 is breaking, 404 to 200 is info, 200 to 202 is a warning | depends |
+| `enum_value_added` | `status` returned `suspended` besides `active` and `past_due` | warning |
+| `latency_regression` | median latency over 3x the baseline and at least 250 ms slower | warning |
+| `field_added` | a new `phone_number` field | info, or warning with `strict: true` |
+
+Override any of them globally or per endpoint with `severity_overrides`.
+
+## Use it in CI
+
+| Exit code | Meaning |
+|---|---|
+| 0 | No drift. Info-only changes and new baselines count as no drift. |
+| 1 | Warning-level drift. |
+| 2 | Breaking drift. |
+| 3 | A check could not run (network error, unexpected status, invalid JSON) and nothing broke. |
+| 4 | Usage or configuration error. |
+
+The baseline lives in `.tiltmeter/`, so keep that folder between runs. The
+[CI guide](docs/ci.md) has ready-to-copy jobs for GitHub Actions, GitLab CI and cron.
+
+## How it works
+
+1. **Observe.** A check calls the endpoint and turns the JSON body into a *shape*: for
+   every path, which JSON types appeared, how many objects contained each field and, for
+   fields that look categorical (`active`, `past_due`, `USD`), which values were seen.
+2. **Compare.** The baseline is the merge of the shapes from the last 20 successful
+   checks. Tiltmeter reports only what *contradicts* it: a missing optional field is
+   fine, a field that was in every object and is now gone is not.
+3. **Report once.** The new shape joins the baseline, so the check that sees a change
+   reports it, and from then on it is the new normal.
+
+<!-- pypi-skip-diagram -->
+```mermaid
+graph TD;
+  start([start]) --> observe
+  observe -. fetch failed .-> persist
+  observe --> load_baseline --> compare
+  compare -. drift worth explaining .-> explain --> persist
+  compare --> persist
+  persist -. a notifier wants it .-> notify --> finish([end])
+  persist --> finish
+```
+<!-- /pypi-skip-diagram -->
+
+The pipeline is a small [LangGraph](https://github.com/langchain-ai/langgraph) graph that
+only sequences the steps. The diff itself is plain, deterministic Python with no LLM in the
+loop. [How it works](docs/how-it-works.md) covers the details.
+
+## Configuration
+
+```yaml
+endpoints:
+  - id: stripe_customers
+    url: https://api.stripe.com/v1/customers
+    params:
+      limit: 10
+    headers:
+      Authorization: Bearer ${STRIPE_API_KEY}   # expanded from the environment at request time
+    ignore_paths:
+      - $.data[*].metadata                      # free-form, changes all the time
+
+notify:
+  - type: slack
+    webhook_url: ${SLACK_WEBHOOK_URL}
+```
+
+Every option is described in the [configuration reference](docs/configuration.md), and
+[`examples/`](examples) has a config you can run as is.
+
+## How it compares
+
+- **OpenAPI diff tools** such as oasdiff compare two versions of a spec. They are the right
+  tool when the vendor publishes and maintains one, and they cannot see changes the vendor
+  did not document.
+- **Contract testing** such as Pact needs the provider to run your contracts, which
+  third-party vendors don't do.
+- **Uptime and synthetic monitors** tell you an API is up. You write and maintain the
+  response assertions yourself.
+- **Tiltmeter** learns the contract from real responses, so it needs nothing from the
+  vendor and catches undocumented changes. It also hands what it learns to your agents.
+
+## Privacy and security
+
+- `${VAR}` placeholders are expanded right before a request or notification is sent. The
+  values are never written to disk, sent to the LLM or kept in the LangGraph state, and
+  they are scrubbed from error messages.
+- The history stores shapes, status codes, latencies and changes, never response bodies
+  unless you set `store_samples: true`.
+- Agents can only check the endpoints in your config. They cannot make Tiltmeter call an
+  arbitrary URL.
+
+[SECURITY.md](SECURITY.md) has the full threat model and how to report a vulnerability.
+
+## Roadmap
+
+- **Auto-fix pull requests.** When a vendor ships a breaking change, an agent built on
+  LangChain Deep Agents finds the affected code in your repository and opens a PR.
+- **Spec and changelog awareness.** Diff vendor OpenAPI specs and changelogs next to
+  observed responses.
+- **Hosted checks** and a team dashboard.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md): a five-minute tour on your machine.
+- [Configuration reference](docs/configuration.md): every option, placeholders and ignore patterns.
+- [Agents and MCP](docs/agents.md): Claude Code, Cursor, Claude Desktop and LangChain.
+- [CI and scheduling](docs/ci.md): GitHub Actions, GitLab CI and cron.
+- [How it works](docs/how-it-works.md): shapes, baselines, the diff rules and the pipeline.
+- [FAQ and troubleshooting](docs/faq.md).
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md)
+explains how to set up the project and what a good change looks like. Everyone taking
+part is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE)

tiltmeter-0.1.0/examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+| File | What it is |
+|---|---|
+| [`tiltmeter.yaml`](tiltmeter.yaml) | A config with three public APIs that need no keys (GitHub, JSONPlaceholder and Open-Meteo), plus commented Stripe and GraphQL endpoints. Run it with `tiltmeter check -c examples/tiltmeter.yaml`. |
+| [`github-action.yml`](github-action.yml) | A scheduled GitHub Actions job that keeps the baseline in the Actions cache and fails on drift. Copy it to `.github/workflows/` in the repository that holds your config. |
+
+The [getting started guide](../docs/getting-started.md) walks through a full drift cycle
+against a fake API on your machine.

tiltmeter-0.1.0/examples/github-action.yml

@@ -0,0 +1,46 @@
+# Check your APIs every hour and fail the job on breaking drift.
+# Copy this file to .github/workflows/tiltmeter.yml in the repository that holds
+# tiltmeter.yaml, and add the secrets your endpoints reference.
+name: API drift
+
+on:
+  schedule:
+    - cron: "17 * * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tiltmeter:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10
+
+      # The baseline lives in .tiltmeter/. Restore the newest copy...
+      - uses: actions/cache/restore@v6
+        with:
+          path: .tiltmeter
+          key: tiltmeter-${{ github.run_id }}
+          restore-keys: tiltmeter-
+
+      # Exit codes: 0 clean, 1 warning, 2 breaking, 3 a check failed, 4 bad config.
+      # Pin the version so a new release never changes your CI without a review.
+      - name: Check APIs
+        run: uvx tiltmeter@0.1.0 check
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          STRIPE_API_KEY: ${{ secrets.STRIPE_API_KEY }}
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+      # ...and save the new one even when the job fails, so each change is reported once.
+      - uses: actions/cache/save@v6
+        if: always()
+        with:
+          path: .tiltmeter
+          key: tiltmeter-${{ github.run_id }}

tiltmeter-0.1.0/examples/tiltmeter.yaml

@@ -0,0 +1,62 @@
+# tiltmeter example: public APIs you can check right away, no keys needed.
+#   tiltmeter check -c examples/tiltmeter.yaml
+version: 1
+
+endpoints:
+  - id: github_repo
+    description: Repository metadata from the GitHub REST API (60 requests/hour without a token)
+    url: https://api.github.com/repos/langchain-ai/langchain
+    headers:
+      Accept: application/vnd.github+json
+
+  - id: jsonplaceholder_users
+    description: Fake user directory from JSONPlaceholder
+    url: https://jsonplaceholder.typicode.com/users
+
+  - id: open_meteo_buenos_aires
+    description: Current weather in Buenos Aires from Open-Meteo
+    url: https://api.open-meteo.com/v1/forecast
+    params:
+      latitude: "-34.61"
+      longitude: "-58.38"
+      current: temperature_2m,wind_speed_10m
+
+  # Credentials come from environment variables and are expanded at request time.
+  # They are never written to disk or sent to the LLM.
+  #
+  # - 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
+  #
+  # GraphQL and other POST APIs work too:
+  #
+  # - id: github_viewer
+  #   method: POST
+  #   url: https://api.github.com/graphql
+  #   headers:
+  #     Authorization: Bearer ${GITHUB_TOKEN}
+  #   body:
+  #     query: "{ viewer { login createdAt } }"
+
+llm:
+  enabled: true            # used only when ANTHROPIC_API_KEY is set
+  model: claude-haiku-5-5
+  effort: low
+
+notify: []
+#  - type: slack
+#    webhook_url: ${SLACK_WEBHOOK_URL}
+#    min_severity: warning
+#  - type: webhook
+#    url: https://example.com/hooks/tiltmeter
+#    headers:
+#      Authorization: Bearer ${HOOK_TOKEN}
+#    min_severity: breaking
+#    on_error: true