adrails 0.2.3__tar.gz

adrails-0.2.3/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

adrails-0.2.3/NOTICE

@@ -0,0 +1,7 @@
+AdRails (adsops)
+Copyright 2026 The AdRails authors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+It is provided AS IS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND. Operating
+advertising accounts with automated agents can spend real money; see
+deploy/GUARD.md for what the spend guard can and cannot do.

adrails-0.2.3/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: adrails
+Version: 0.2.3
+Summary: AdRails: open-source Google Ads MCP server with hard spend guardrails. Agents read freely and write only through a reviewed desired-state file.
+Author: adsops contributors
+License: Apache-2.0
+Project-URL: Homepage, https://adrails.dev
+Project-URL: Source, https://github.com/antonioac1/adrails
+Keywords: mcp,advertising,google-ads,agents,guardrails
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: google
+Requires-Dist: google-auth>=2.0; extra == "google"
+Dynamic: license-file
+
+# AdRails (adrails.dev)
+
+**Guardrails for AI agents running your ads: an open-source, self-hosted Google Ads MCP server.**
+
+Website and docs: https://adrails.dev · MCP Registry: `dev.adrails/adrails` · plain-text summary for agents: https://adrails.dev/llms.txt
+
+AdRails is a local MCP server for Google Ads. An agent may read campaigns, status and search
+terms as often as it likes; every write has to land in a reviewed desired-state file on disk,
+get diffed against live state, and clear caps that live in a policy file no AdRails tool writes.
+The Python package and module are still named `adsops` — that is the name you install and run.
+
+Three things it does differently:
+
+- **Your keys.** It runs on your machine against your own Google Cloud project and Google Ads
+  credentials. Nothing is hosted: the only endpoint the package talks to is the Google Ads API,
+  and credentials are read from the sources you configure (a service-account JSON file, a static
+  token, or a secret-manager lookup).
+- **Your caps.** Caps live in a policy file that no AdRails tool writes; with `require_plan_id`
+  on, every commit must quote a fresh, single-use `plan_id` issued for that exact plan; and a
+  change that adds spend exposure is refused while the scheduled guard's heartbeat is stale.
+- **Pay per call in sats.** Optional hosted add-ons, Lightning-first, metered per call in sats —
+  coming soon. Nothing in this release contacts any hosted service.
+
+## Testing
+
+```bash
+python3 -m adsops --selftest           # 430 unit checks, everything mocked
+python3 tests/qa_invariants.py         # 200 random sequences against a simulated Google Ads account
+python3 tests/qa_inputs.py             # hostile policy/state/config inputs (NaN, Infinity, bad dates, bad UTF-8, ...)
+python3 tests/qa_secrets.py            # canary tokens injected everywhere; none may reach output or logs
+```
+The QA suites were written adversarially by a separate agent with no write access to `adsops/`, and every finding was fixed
+or documented as intended behaviour.
+
+## What AdRails cannot guarantee
+
+Read this before pointing it at a live account.
+
+- **It is a threshold with automatic pause attempts, not a hard spend ceiling.** The guard
+  compares spend with numbers you wrote and issues pause operations. That is containment, not
+  billing control.
+- **Google can deliver up to 2x the average daily budget on a given day.** A daily budget is an
+  average, not a maximum, and a pause is an API call that can be rejected or land late.
+- **Reporting is delayed.** The spend figures AdRails reads are minutes to hours behind delivery.
+- **The guard only acts when it is scheduled and the machine is awake.** A chat-session MCP
+  process is not a monitor: while the machine sleeps no checks run, spend keeps moving, and the
+  heartbeat goes stale.
+- **An agent with shell access as the same user can bypass any local tool.** AdRails constrains
+  the tool calls it serves, not the machine underneath. Sandbox the agent if that matters to you.
+- **Wrong negative keywords can suppress good traffic.** Negatives are append-only here, so a
+  bad one is also awkward to withdraw.
+- **You are responsible for your account and your spend.** Keep platform-side billing limits as
+  the real ceiling.
+
+## Quickstart
+
+**1. Install.**
+
+```bash
+# from GitHub (PyPI release coming soon)
+pipx install git+https://github.com/antonioac1/adrails     # console script: adsops-mcp
+# or run without installing:
+uvx --from git+https://github.com/antonioac1/adrails adsops-mcp --config /absolute/path/config.json
+```
+
+No other dependencies. Service-account tokens are signed with your system `openssl`
+when `google-auth` isn't installed (install `google-auth` if you prefer it).
+
+The core is stdlib-only. Check it offline (everything mocked, no network):
+
+```bash
+python3 -m adsops --selftest      # or: deploy/smoke_docker.sh
+```
+
+**2. Write a config.** Every account, credential source and path lives here; paths are
+`~`-expanded at load time.
+
+```json
+{
+  "tenant": "your-tenant",
+  "meter_log": "~/.adsops/meter.jsonl",
+  "audit_log": "~/.adsops/audit.jsonl",
+  "plan_ledger": "~/.adsops/plans.jsonl",
+  "lock_dir": "~/.adsops/locks",
+  "guard_heartbeat": "~/.adsops/guard.heartbeat",
+  "credentials": {"google_ads": {"type": "service_account",
+      "sources": [{"kind": "file", "path": "~/.adsops/sa.json"}]}},
+  "google_ads": {"api_version": "v24", "end_field": "end_date_time", "login_customer_id": null},
+  "commit_policy": {"require_clean_git": true, "allow_commit": true, "allow_set": true},
+  "accounts": [{"key": "main", "platform": "google_ads", "customer_id": "000-000-0000",
+      "campaigns": [{"key": "search_core", "state_file": "~/ads/search_core.json",
+                     "policy_file": "~/ads/search_core.policy.json"}]}]
+}
+```
+
+`commit_policy` defaults to `require_clean_git: true` and `allow_commit: false`, so commits and
+`adsops_set` stay off until you turn them on.
+
+**3. Write the policy file** for the campaign (next section), and commit both files to git so
+`git diff` is the change review.
+
+**4. Register the server** in your MCP client. Diagnostics go to stderr; the server speaks
+JSON-RPC 2.0 over stdio, one object per line.
+
+```json
+{
+  "mcpServers": {
+    "adrails": {
+      "command": "python3",
+      "args": ["-m", "adsops", "--config", "/absolute/path/config.json"]
+    }
+  }
+}
+```
+
+**5. Schedule the guard.** A chat session cannot watch spend, so the pause-only spend check runs
+from your OS scheduler every 15 minutes. Templates for launchd, systemd and cron live in
+`deploy/`; render the placeholders (`__PYTHON__`, `__CONFIG__`, `__PKG__`, `__LOGDIR__`) and read
+`deploy/GUARD.md` before installing:
+
+```bash
+PY=$(command -v python3); CFG=/absolute/path/config.json
+PKG=/absolute/dir/containing/adsops; LOGDIR="$HOME/.adsops/logs"
+mkdir -p "$LOGDIR"
+sed -e "s|__PYTHON__|$PY|g" -e "s|__CONFIG__|$CFG|g" \
+    -e "s|__PKG__|$PKG|g" -e "s|__LOGDIR__|$LOGDIR|g" \
+    deploy/launchd/com.adsops.guard.plist.template \
+    > ~/Library/LaunchAgents/com.adsops.guard.plist
+plutil -lint ~/Library/LaunchAgents/com.adsops.guard.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.adsops.guard.plist
+```
+
+The command all three units run is `PYTHONPATH=$PKG $PY -m adsops --config $CFG guard-all`.
+
+## Use it from Grok, Claude Code, Cursor or any MCP client
+
+AdRails is a local stdio server, so every client registers the same command. There is no hosted URL, by design.
+
+```bash
+pip install git+https://github.com/antonioac1/adrails@v0.2.2
+
+# Claude Code
+claude mcp add adrails -- python3 -m adsops --config /absolute/path/config.json
+# Grok CLI (it also reads ~/.claude.json, .cursor/mcp.json and .mcp.json)
+grok mcp add adrails -- python3 -m adsops --config /absolute/path/config.json
+```
+
+Cursor or a project `.mcp.json`:
+
+```json
+{"mcpServers":{"adrails":{"command":"python3","args":["-m","adsops","--config","/absolute/path/config.json"]}}}
+```
+
+Claude Desktop: install the `.mcpb` bundle from the [latest release](https://github.com/antonioac1/adrails/releases/latest).
+More: https://adrails.dev/docs/mcp-clients/
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `adsops_campaigns` | Lists the campaigns this deployment may operate: keys, accounts, state files, and the active commit policy. |
+| `adsops_status` | Live read for one campaign: status, end date, daily budget, spend today and lifetime, negative count, whether caps come from the policy file, and the guard heartbeat's age. |
+| `adsops_terms` | Clicked search terms for the last N days (1–90, default 14): term, matched keyword, clicks, cost. |
+| `adsops_plan` | Pure diff of the desired-state file against live state; writes nothing. Returns the operations, notes, `ops_count`, the exposure increases it found, and a single-use **`plan_id`** with its expiry. |
+| `adsops_apply` | Validate-only unless `commit=true`. A commit needs `commit_policy.allow_commit`, a clean git-tracked state file, a fresh guard heartbeat when the change adds exposure, and the **`plan_id`** from `adsops_plan` when the policy requires it. |
+| `adsops_set` | Proposes a budget / status / end-date / negatives change with a short `reason`; checks it against policy caps and live state, writes the state file and commits it to git. `dry_run=true` returns a **`plan_id`** instead of writing; `apply=true` needs that `plan_id` when the policy requires it. |
+| `adsops_guard` | Reads spend and pauses the campaign if the daily or lifetime threshold is crossed. Pause only: it never enables, raises a budget or edits keywords. Validate-only unless `commit=true`. |
+| `adsops_usage` | Metering summary for the tenant: calls, errors, units, ops and median latency per tool. |
+
+## The policy file
+
+One policy file per campaign, referenced by `policy_file` in the config. AdRails only ever reads
+it: no tool writes caps, and `adsops_set` refuses `guards` and `allow_enable` outright. If the
+state file also carries caps they are ignored — the policy file always wins, and `adsops_status`
+says so.
+
+```json
+{
+  "customer_id": "000-000-0000",
+  "campaign_id": 1000000000,
+  "guards": {
+    "max_daily_budget_usd": 40,
+    "min_daily_budget_usd": 5,
+    "max_end_date": "2026-12-31",
+    "lifetime_spend_pause_usd": 900,
+    "daily_spend_pause_usd": 60,
+    "max_ops_per_run": 12
+  },
+  "allow_enable": false,
+  "max_guard_age_min": 30,
+  "require_plan_id": true,
+  "plan_ttl_s": 900
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `customer_id` | Account the campaign lives in; compared with the state file after stripping dashes. A mismatch is refused. |
+| `campaign_id` | The one campaign this policy governs; must match the state file exactly. |
+| `guards.max_daily_budget_usd` | Required. Upper bound of the daily budget, and the budget ceiling checked at plan time. |
+| `guards.min_daily_budget_usd` | Optional. Lower bound of the daily budget; must not exceed the maximum. |
+| `guards.max_end_date` | Required, `YYYY-MM-DD`. Latest end date any plan may set. |
+| `guards.lifetime_spend_pause_usd` | Required. Lifetime spend at which the guard issues a pause. |
+| `guards.daily_spend_pause_usd` | Required. Today's spend at which the guard issues a pause. |
+| `guards.max_ops_per_run` | Required integer. Most operations one run may emit; more is refused. |
+| `allow_enable` | Default `false`. Whether a plan may ever set the campaign to `ENABLED`. |
+| `max_guard_age_min` | Default `null` (check off). When set, any change that adds spend exposure is refused unless the guard heartbeat is younger than this. |
+| `require_plan_id` | Default `false`. When `true`, apply/commit and `adsops_set` with `apply=true` must quote a `plan_id`. |
+| `plan_ttl_s` | Default `900`, range 60–86400. How long an issued `plan_id` stays usable; each one is consumed once. |
+
+A missing or malformed field is an error that names the field, not a silent default.
+
+## Desired-state file
+
+One JSON file per campaign, referenced by `state_file`. It says what the campaign should look
+like; the server computes the diff.
+
+```json
+{
+  "customer_id": "000-000-0000",
+  "campaign_id": 1000000000,
+  "campaign_name": "Search - Core",
+  "status": "PAUSED",
+  "end_date": "2026-11-30",
+  "daily_budget_usd": 20,
+  "negatives_add": [
+    {"text": "free", "match_type": "BROAD"},
+    {"text": "cheap", "match_type": "PHRASE"}
+  ],
+  "guards": {
+    "max_end_date": "2026-12-31",
+    "min_daily_budget_usd": 5,
+    "max_daily_budget_usd": 40,
+    "lifetime_spend_pause_usd": 900,
+    "daily_spend_pause_usd": 60,
+    "max_ops_per_run": 12
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `customer_id` | Account the campaign lives in; dashes are stripped before use. |
+| `campaign_id` / `campaign_name` | The one campaign this file owns. Both must match live state or the run aborts. |
+| `status` | Desired status, `ENABLED` or `PAUSED`. `ENABLED` additionally requires `allow_enable` in the policy. |
+| `end_date` | Desired end date, `YYYY-MM-DD`, bounded by `guards.max_end_date` and not in the past. |
+| `daily_budget_usd` | Desired daily budget, bounded by the min/max guard band. |
+| `negatives_add` | Append-only list of `{text, match_type}`; match type is `BROAD`, `PHRASE` or `EXACT`. Nothing here removes a keyword. |
+| `guards` | Read only when the campaign has no `policy_file` (legacy mode). With a policy file configured, these are ignored. |
+
+Keep these files in git. That is what makes "reviewed desired state" real: `git diff` is the
+change review, and `require_clean_git` makes the server refuse to act on uncommitted edits.
+
+## Works with Google's official read-only `google-ads-mcp`
+
+Run both servers side by side in the same MCP client. Google's server answers ad-hoc GAQL
+exploration and never writes; AdRails is the only write path. The agent reads with the official
+server, proposes a change to a desired-state or policy file, and applies it through
+`adsops_plan` / `adsops_apply` — with caps, a validate pass, an account lock, and an audit line
+in between. Both speak JSON-RPC over stdio, so one `.mcp.json` entry each is the whole setup.
+
+## License
+
+Apache-2.0.