cloudcleaner-agent 0.1.0__tar.gz

cloudcleaner_agent-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: cloudcleaner-agent
+Version: 0.1.0
+Summary: Finds idle AWS resources, proves they are unused, and plans a dependency-ordered teardown behind a human approval gate.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/charltonxqh/CloudCleaner
+Keywords: aws,finops,cost-optimization,agent,langgraph,cloud
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: langchain==1.2.15
+Requires-Dist: langgraph==1.1.6
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1.1
+Requires-Dist: langchain-groq>=1.1.3
+Requires-Dist: python-dotenv<2.0.0,>=1.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: boto3>=1.43.86
+Requires-Dist: pygithub>=2.10.0
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: server
+Requires-Dist: fastapi<1.0.0,>=0.115.5; extra == "server"
+Requires-Dist: uvicorn<1.0.0,>=0.29.0; extra == "server"
+Requires-Dist: copilotkit==0.1.96; extra == "server"
+Requires-Dist: ag-ui-langgraph[fastapi]==0.0.43; extra == "server"
+Requires-Dist: ag-ui-protocol==0.1.19; extra == "server"
+Provides-Extra: openai
+Requires-Dist: langchain-openai==1.1.9; extra == "openai"
+Requires-Dist: openai==1.109.1; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic==1.4.1; extra == "anthropic"
+Provides-Extra: tracing
+Requires-Dist: langsmith==0.7.33; extra == "tracing"
+Provides-Extra: all
+Requires-Dist: cloudcleaner-agent[anthropic,openai,server,tracing]; extra == "all"
+
+# CloudCleaner
+
+**Finds AWS resources nobody is using, proves it, works out the order they have
+to be dismantled in, and asks a human before touching anything.**
+
+```bash
+pip install cloudcleaner-agent
+```
+
+The command it installs is `cloudcleaner`.
+
+---
+
+## The problem
+
+**Stopping an EC2 instance does not stop the bill.** Stop releases the compute
+and nothing else — the root volume, any extra volumes, and the public IPv4
+address all keep charging. A stopped `t3.micro` with a 16 GB volume and an
+Elastic IP still costs about **$4.93 a month**, indefinitely.
+
+**Deleting is a dependency puzzle.** You cannot release an Elastic IP while it
+is associated. You cannot delete a volume while it is attached. Volumes created
+with `DeleteOnTermination=false` outlive the instance and bill silently forever.
+AWS reports exactly one blocker per attempt, so the order is discovered by trial
+and error.
+
+CloudCleaner does both parts: it finds the waste, and it works out the sequence.
+
+---
+
+## Try it without an AWS account
+
+A demo account ships with the package, so nothing is read or changed:
+
+```bash
+CLOUDCLEANER_PROVIDER=fixture cloudcleaner scan
+CLOUDCLEANER_PROVIDER=fixture cloudcleaner sweep
+```
+
+```
+RESOURCE                   TYPE   STATE              $/MO
+i-0999prod888              ec2    running          $34.37
+vol-0orphan11              ebs    available         $8.00 *
+i-0abc123def456789         ec2    stopped           $4.93 *
+eipalloc-0unused9          eip    unassociated      $3.65 *
+
+4 resources · $50.95/mo total · $16.58/mo not running but still billing (*)
+```
+
+## Against a real account
+
+```bash
+cloudcleaner doctor        # check credentials and configuration first
+cloudcleaner scan
+cloudcleaner investigate i-0abc123def456789
+```
+
+`CLOUDCLEANER_DRY_RUN` defaults to `true`. Nothing in AWS is modified until you
+set it to `false`.
+
+---
+
+## What an investigation looks like
+
+```
+i-0abc123def456789  payments-poc  (ec2/stopped)  $4.93/mo
+  -> retire (95%, high) Stopped 41 days with average CPU 0.4%, and still
+     billing $4.93/mo for its volume and address.
+
+     1. disassociate_address  eipassoc-0c1b2a3    $0.00  54.211.8.12 is attached
+   ! 2. release_address       eipalloc-0f2e3d4    $3.65  public IPv4 bills hourly
+     3. snapshot_volume       vol-0a9b8c7d6       $0.00  restore point first
+   ! 4. terminate_instance    i-0abc123def456789  $4.93  idle instance
+   ! 5. delete_volume         vol-0a9b8c7d6       $1.28  DeleteOnTermination=false
+
+     3 of 5 steps cannot be undone                       $9.86/mo
+
+  Type 'APPROVE i-0abc123def456789' to run this plan:
+```
+
+The order is computed, not scripted: dependencies are discovered at runtime and
+topologically sorted, so a cycle raises rather than producing a sequence that
+fails halfway.
+
+---
+
+## Commands
+
+| | |
+|---|---|
+| `cloudcleaner scan` | what the account holds and what it costs |
+| `cloudcleaner sweep` | investigate everything, approve nothing |
+| `cloudcleaner investigate <id>` | one resource, with the approval prompt |
+| `cloudcleaner history` | past runs, realised versus simulated savings |
+| `cloudcleaner doctor` | check credentials and configuration |
+| `cloudcleaner serve` | the HTTP API (needs the `[server]` extra) |
+
+---
+
+## Safety
+
+Three independent gates stand between a verdict and a deletion:
+
+1. **The model advises.** It sees only evidence and returns a typed verdict. It
+   can be wrong, and a human can overrule it.
+2. **The policy decides.** Plain Python — protected environments, protected
+   tags, minimum age, risk score. No prompt reaches it, so it cannot be argued
+   with or injected.
+3. **A human commits.** You type the resource id exactly. Never `y/n`.
+
+Every volume is snapshotted before deletion, a restore recipe is written before
+anything runs, and dry-run savings are recorded as **simulated** — never as
+money saved.
+
+---
+
+## Configuration
+
+Read from `.env` in the working directory, upwards from it, or
+`~/.cloudcleaner/.env`.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `GROQ_API_KEY` | — | required unless AI is disabled |
+| `CLOUDCLEANER_PROVIDER` | `aws` | `fixture` runs offline against the demo account |
+| `CLOUDCLEANER_DRY_RUN` | `true` | `false` actually modifies AWS |
+| `CLOUDCLEANER_AI_ENABLED` | `true` | `false` uses the rules engine only; nothing leaves the machine |
+| `CLOUDCLEANER_DATA_DIR` | `./output` or `~/.cloudcleaner` | where the database and logs are written |
+| `AWS_ENDPOINT_URL` | — | point boto3 at LocalStack |
+| `GITHUB_TOKEN` | — | optional; without it, code activity is skipped rather than failing |
+| `METRIC_WINDOW_DAYS` | `7` | CloudWatch lookback |
+
+## Extras
+
+```bash
+pip install cloudcleaner-agent              # the CLI
+pip install 'cloudcleaner-agent[server]'    # plus the HTTP API and web frontend
+pip install 'cloudcleaner-agent[all]'       # plus OpenAI, Anthropic, LangSmith
+```
+
+---
+
+## Coverage
+
+**Today:** EC2 instances, EBS volumes, Elastic IPs, snapshots. CloudWatch usage,
+cost attribution, and GitHub signals — last commit, branch existence, PR status,
+CI runs — so the agent can tell whether the project that owns a resource is
+still alive.
+
+**Not yet:** RDS, NAT gateways, load balancers, ElastiCache, multi-account.
+
+## Requirements
+
+Python 3.12+. AWS credentials with read access plus whichever write permissions
+you intend to use. A Groq API key, free at [console.groq.com](https://console.groq.com),
+unless you run with `CLOUDCLEANER_AI_ENABLED=false`.
+
+MIT licensed.

cloudcleaner_agent-0.1.0/README.md

@@ -0,0 +1,158 @@
+# CloudCleaner
+
+**Finds AWS resources nobody is using, proves it, works out the order they have
+to be dismantled in, and asks a human before touching anything.**
+
+```bash
+pip install cloudcleaner-agent
+```
+
+The command it installs is `cloudcleaner`.
+
+---
+
+## The problem
+
+**Stopping an EC2 instance does not stop the bill.** Stop releases the compute
+and nothing else — the root volume, any extra volumes, and the public IPv4
+address all keep charging. A stopped `t3.micro` with a 16 GB volume and an
+Elastic IP still costs about **$4.93 a month**, indefinitely.
+
+**Deleting is a dependency puzzle.** You cannot release an Elastic IP while it
+is associated. You cannot delete a volume while it is attached. Volumes created
+with `DeleteOnTermination=false` outlive the instance and bill silently forever.
+AWS reports exactly one blocker per attempt, so the order is discovered by trial
+and error.
+
+CloudCleaner does both parts: it finds the waste, and it works out the sequence.
+
+---
+
+## Try it without an AWS account
+
+A demo account ships with the package, so nothing is read or changed:
+
+```bash
+CLOUDCLEANER_PROVIDER=fixture cloudcleaner scan
+CLOUDCLEANER_PROVIDER=fixture cloudcleaner sweep
+```
+
+```
+RESOURCE                   TYPE   STATE              $/MO
+i-0999prod888              ec2    running          $34.37
+vol-0orphan11              ebs    available         $8.00 *
+i-0abc123def456789         ec2    stopped           $4.93 *
+eipalloc-0unused9          eip    unassociated      $3.65 *
+
+4 resources · $50.95/mo total · $16.58/mo not running but still billing (*)
+```
+
+## Against a real account
+
+```bash
+cloudcleaner doctor        # check credentials and configuration first
+cloudcleaner scan
+cloudcleaner investigate i-0abc123def456789
+```
+
+`CLOUDCLEANER_DRY_RUN` defaults to `true`. Nothing in AWS is modified until you
+set it to `false`.
+
+---
+
+## What an investigation looks like
+
+```
+i-0abc123def456789  payments-poc  (ec2/stopped)  $4.93/mo
+  -> retire (95%, high) Stopped 41 days with average CPU 0.4%, and still
+     billing $4.93/mo for its volume and address.
+
+     1. disassociate_address  eipassoc-0c1b2a3    $0.00  54.211.8.12 is attached
+   ! 2. release_address       eipalloc-0f2e3d4    $3.65  public IPv4 bills hourly
+     3. snapshot_volume       vol-0a9b8c7d6       $0.00  restore point first
+   ! 4. terminate_instance    i-0abc123def456789  $4.93  idle instance
+   ! 5. delete_volume         vol-0a9b8c7d6       $1.28  DeleteOnTermination=false
+
+     3 of 5 steps cannot be undone                       $9.86/mo
+
+  Type 'APPROVE i-0abc123def456789' to run this plan:
+```
+
+The order is computed, not scripted: dependencies are discovered at runtime and
+topologically sorted, so a cycle raises rather than producing a sequence that
+fails halfway.
+
+---
+
+## Commands
+
+| | |
+|---|---|
+| `cloudcleaner scan` | what the account holds and what it costs |
+| `cloudcleaner sweep` | investigate everything, approve nothing |
+| `cloudcleaner investigate <id>` | one resource, with the approval prompt |
+| `cloudcleaner history` | past runs, realised versus simulated savings |
+| `cloudcleaner doctor` | check credentials and configuration |
+| `cloudcleaner serve` | the HTTP API (needs the `[server]` extra) |
+
+---
+
+## Safety
+
+Three independent gates stand between a verdict and a deletion:
+
+1. **The model advises.** It sees only evidence and returns a typed verdict. It
+   can be wrong, and a human can overrule it.
+2. **The policy decides.** Plain Python — protected environments, protected
+   tags, minimum age, risk score. No prompt reaches it, so it cannot be argued
+   with or injected.
+3. **A human commits.** You type the resource id exactly. Never `y/n`.
+
+Every volume is snapshotted before deletion, a restore recipe is written before
+anything runs, and dry-run savings are recorded as **simulated** — never as
+money saved.
+
+---
+
+## Configuration
+
+Read from `.env` in the working directory, upwards from it, or
+`~/.cloudcleaner/.env`.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `GROQ_API_KEY` | — | required unless AI is disabled |
+| `CLOUDCLEANER_PROVIDER` | `aws` | `fixture` runs offline against the demo account |
+| `CLOUDCLEANER_DRY_RUN` | `true` | `false` actually modifies AWS |
+| `CLOUDCLEANER_AI_ENABLED` | `true` | `false` uses the rules engine only; nothing leaves the machine |
+| `CLOUDCLEANER_DATA_DIR` | `./output` or `~/.cloudcleaner` | where the database and logs are written |
+| `AWS_ENDPOINT_URL` | — | point boto3 at LocalStack |
+| `GITHUB_TOKEN` | — | optional; without it, code activity is skipped rather than failing |
+| `METRIC_WINDOW_DAYS` | `7` | CloudWatch lookback |
+
+## Extras
+
+```bash
+pip install cloudcleaner-agent              # the CLI
+pip install 'cloudcleaner-agent[server]'    # plus the HTTP API and web frontend
+pip install 'cloudcleaner-agent[all]'       # plus OpenAI, Anthropic, LangSmith
+```
+
+---
+
+## Coverage
+
+**Today:** EC2 instances, EBS volumes, Elastic IPs, snapshots. CloudWatch usage,
+cost attribution, and GitHub signals — last commit, branch existence, PR status,
+CI runs — so the agent can tell whether the project that owns a resource is
+still alive.
+
+**Not yet:** RDS, NAT gateways, load balancers, ElastiCache, multi-account.
+
+## Requirements
+
+Python 3.12+. AWS credentials with read access plus whichever write permissions
+you intend to use. A Groq API key, free at [console.groq.com](https://console.groq.com),
+unless you run with `CLOUDCLEANER_AI_ENABLED=false`.
+
+MIT licensed.

cloudcleaner_agent-0.1.0/cloudcleaner/cli.py

@@ -0,0 +1,239 @@
+"""Command line entry point.
+
+    cloudcleaner scan                     what the account holds, and what it costs
+    cloudcleaner sweep                    investigate everything, approve nothing
+    cloudcleaner investigate <id>         one resource, with an approval prompt
+    cloudcleaner history                  past runs and realised savings
+    cloudcleaner doctor                   check credentials and configuration
+    cloudcleaner serve                    the HTTP API (needs the [server] extra)
+
+Every command is read-only unless you approve something, and even then
+CLOUDCLEANER_DRY_RUN defaults to true.
+"""
+
+import argparse
+import sys
+import uuid
+
+
+def _fmt(amount) -> str:
+    return f"${amount or 0:,.2f}"
+
+
+def cmd_scan(args) -> int:
+    from cloudcleaner.config import DRY_RUN, PROVIDER
+    from cloudcleaner.graph.nodes.detect import detect_node
+
+    scan = detect_node({})
+    rows = (scan.get("inventory") or []) + (scan.get("orphans") or [])
+    if not rows:
+        print("Nothing found. Either the account is empty or the credentials cannot see it.")
+        return 0
+
+    total = sum(r.estimated_monthly_cost or 0 for r in rows)
+    wasted = sum(r.estimated_monthly_cost or 0 for r in rows if r.billing_while_stopped)
+
+    print(f"provider={PROVIDER}  dry_run={DRY_RUN}\n")
+    print(f"{'RESOURCE':<26} {'TYPE':<6} {'STATE':<14} {'$/MO':>8}")
+    for r in sorted(rows, key=lambda r: -(r.estimated_monthly_cost or 0)):
+        flag = " *" if r.billing_while_stopped else ""
+        print(f"{r.resource_id:<26} {r.resource_type:<6} {(r.state or '-'):<14} "
+              f"{_fmt(r.estimated_monthly_cost):>8}{flag}")
+
+    print(f"\n{len(rows)} resources · {_fmt(total)}/mo total · {_fmt(wasted)}/mo not running "
+          f"but still billing (*)")
+    return 0
+
+
+def cmd_sweep(args) -> int:
+    """Assess every candidate. Approves nothing, so it is safe to run anywhere."""
+    from langgraph.types import Command
+
+    from cloudcleaner.config import DRY_RUN, PROVIDER
+    from cloudcleaner.graph.graph import graph
+    from cloudcleaner.graph.nodes.detect import detect_node
+
+    scan = detect_node({})
+    candidates = (scan.get("inventory") or []) + (scan.get("orphans") or [])
+    if not candidates:
+        print("Nothing to investigate.")
+        return 0
+
+    print(f"provider={PROVIDER}  dry_run={DRY_RUN}\n")
+    recoverable = 0.0
+
+    for resource in candidates:
+        config = {"configurable": {"thread_id": str(uuid.uuid4())}}
+        result = graph.invoke({**scan, "resource": resource}, config)
+        if result.get("__interrupt__"):
+            result = graph.invoke(Command(resume=""), config)
+
+        rec, plan = result.get("recommendation"), result.get("plan")
+        saving = sum(s.monthly_saving for s in plan.steps) if plan and plan.steps else 0.0
+        recoverable += saving
+
+        print(f"{resource.resource_id}  {resource.resource_type}/{resource.state}  "
+              f"{_fmt(resource.estimated_monthly_cost)}/mo")
+        if rec:
+            print(f"  -> {rec.action} ({rec.confidence:.0%}, {rec.severity}) {rec.reason}")
+        if plan and plan.blocked:
+            print(f"  -> blocked: {'; '.join(plan.blocked)}")
+        for s in (plan.steps if plan else []):
+            mark = "!" if not s.reversible else " "
+            print(f"   {mark} {s.order}. {s.action:<21} {s.resource_id:<22} "
+                  f"{_fmt(s.monthly_saving):>8}  {s.reason}")
+        print()
+
+    print(f"Recoverable: {_fmt(recoverable)}/month  ({_fmt(recoverable * 12)}/year)")
+    return 0
+
+
+def cmd_investigate(args) -> int:
+    from langgraph.types import Command
+
+    from cloudcleaner.config import DRY_RUN, PROVIDER
+    from cloudcleaner.graph.graph import graph
+    from cloudcleaner.graph.nodes.detect import detect_node
+    from cloudcleaner.graph.render import render_plan
+
+    scan = detect_node({})
+    pool = (scan.get("inventory") or []) + (scan.get("orphans") or [])
+    resource = next((r for r in pool if r.resource_id == args.resource_id), None)
+    if resource is None:
+        print(f"No resource {args.resource_id} in this account.", file=sys.stderr)
+        print("Run `cloudcleaner scan` to see what is visible.", file=sys.stderr)
+        return 1
+
+    print(f"provider={PROVIDER}  dry_run={DRY_RUN}\n")
+    config = {"configurable": {"thread_id": str(uuid.uuid4())}}
+    result = graph.invoke({**scan, "resource": resource, "force_plan": args.force_plan}, config)
+
+    while "__interrupt__" in result:
+        payload = result["__interrupt__"][0].value
+        if not sys.stdin.isatty():
+            print(render_plan(payload).rstrip() + "  [not a terminal, skipped]")
+            result = graph.invoke(Command(resume=""), config)
+            continue
+        result = graph.invoke(Command(resume=input(render_plan(payload))), config)
+
+    rec = result.get("recommendation")
+    if rec:
+        print(f"\nverdict  {rec.action} ({rec.confidence:.0%}, {rec.severity})")
+        print(f"         {rec.reason}")
+    for a in result.get("action_results") or []:
+        print(f"action   {a['action']} {a['resource_id']} -> {a['detail']}")
+    return 0
+
+
+def cmd_history(args) -> int:
+    from cloudcleaner.storage.repository import list_runs, totals
+
+    runs = list_runs(args.limit)
+    if not runs:
+        print("No runs recorded yet.")
+        return 0
+
+    t = totals()
+    print(f"{t['runs']} runs · {t['approved']} approved · {t['kept']} kept")
+    print(f"realised {_fmt(t['realised_monthly'])}/mo   "
+          f"simulated {_fmt(t['simulated_monthly'])}/mo (dry run, not saved)\n")
+
+    for r in runs:
+        outcome = (f"blocked: {r['blocked'][0]}" if r["blocked"]
+                   else f"{r['executed']}/{r['planned_steps']} steps" if r["executed"]
+                   else "no action")
+        print(f"{r['at'][:16]}  {r['resource_id']:<26} {str(r['verdict']):<10} {outcome}")
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    """Check the things that actually stop this working."""
+    from cloudcleaner import config
+
+    ok = True
+    print(f"config file   {config.ENV_FILE or 'none found'}")
+    print(f"data dir      {config.DATA_DIR}")
+    print(f"provider      {config.PROVIDER}")
+    print(f"dry run       {config.DRY_RUN}")
+    print(f"model         {config.GROQ_MODEL if config.AI_ENABLED else 'disabled, rules only'}")
+    print()
+
+    def check(label, passed, hint=""):
+        nonlocal ok
+        ok = ok and passed
+        print(f"[{'ok ' if passed else 'FAIL'}] {label}" + (f"  — {hint}" if not passed else ""))
+
+    check("Groq key", bool(config.GROQ_API_KEY) or not config.AI_ENABLED,
+          "set GROQ_API_KEY, or CLOUDCLEANER_AI_ENABLED=false for rules only")
+
+    if config.PROVIDER == "fixture":
+        print("[ok ] AWS not needed — running against the built-in demo account")
+    else:
+        try:
+            from cloudcleaner.tools.aws.client import get_sts_client
+            who = get_sts_client().get_caller_identity()
+            check(f"AWS account {who['Account']}", True)
+        except Exception as e:
+            check("AWS credentials", False, str(e)[:80])
+
+    check("GitHub token", bool(config.GITHUB_TOKEN),
+          "optional — without it, code activity is skipped, not fatal")
+
+    return 0 if ok else 1
+
+
+def cmd_serve(args) -> int:
+    try:
+        import uvicorn  # noqa: F401
+    except ImportError:
+        print("The HTTP API needs the server extra:\n\n"
+              "    pip install 'cloudcleaner-agent[server]'\n", file=sys.stderr)
+        return 1
+
+    import uvicorn
+    uvicorn.run("cloudcleaner.server:app", host=args.host, port=args.port, reload=args.reload)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="cloudcleaner",
+        description="Find AWS resources nobody is using, prove it, and plan a safe teardown.",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("scan", help="list resources and what they cost").set_defaults(fn=cmd_scan)
+    sub.add_parser("sweep", help="investigate every candidate").set_defaults(fn=cmd_sweep)
+
+    inv = sub.add_parser("investigate", help="investigate one resource")
+    inv.add_argument("resource_id")
+    inv.add_argument("--force-plan", action="store_true",
+                     help="plan a teardown even when the verdict is keep")
+    inv.set_defaults(fn=cmd_investigate)
+
+    hist = sub.add_parser("history", help="past runs and realised savings")
+    hist.add_argument("--limit", type=int, default=20)
+    hist.set_defaults(fn=cmd_history)
+
+    sub.add_parser("doctor", help="check credentials and configuration").set_defaults(fn=cmd_doctor)
+
+    serve = sub.add_parser("serve", help="run the HTTP API")
+    serve.add_argument("--host", default="0.0.0.0")
+    serve.add_argument("--port", type=int, default=8123)
+    serve.add_argument("--reload", action="store_true")
+    serve.set_defaults(fn=cmd_serve)
+
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.fn(args)
+    except KeyboardInterrupt:
+        print("\ninterrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cloudcleaner_agent-0.1.0/cloudcleaner/config.py

@@ -0,0 +1,103 @@
+"""Backend configuration.
+
+Paths are discovered rather than assumed, so the package works from a checkout,
+from any working directory, or installed into site-packages.
+"""
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+SEARCH_DEPTH = 4
+
+
+def find_env_file() -> Path | None:
+    """Locate .env without assuming a git checkout.
+
+    Order: an explicit CLOUDCLEANER_ENV_FILE, then upwards from the working
+    directory, then upwards from this package, then ~/.cloudcleaner/.env. The
+    package walk keeps `uv run` working from inside agent/; the cwd walk is what
+    makes an installed copy usable from anywhere.
+    """
+    explicit = os.getenv("CLOUDCLEANER_ENV_FILE")
+    if explicit:
+        candidate = Path(explicit).expanduser()
+        return candidate if candidate.is_file() else None
+
+    for start in (Path.cwd(), Path(__file__).resolve().parent):
+        for directory in [start, *start.parents][:SEARCH_DEPTH]:
+            candidate = directory / ".env"
+            if candidate.is_file():
+                return candidate
+
+    home = Path.home() / ".cloudcleaner" / ".env"
+    return home if home.is_file() else None
+
+
+ENV_FILE = find_env_file()
+if ENV_FILE:
+    load_dotenv(ENV_FILE)
+
+
+def find_data_dir() -> Path:
+    """Where the database, reasoning log and restore recipes are written.
+
+    Beside the .env when there is one, so a checkout keeps using output/.
+    Otherwise ~/.cloudcleaner, so an installed copy never writes to
+    site-packages.
+    """
+    explicit = os.getenv("CLOUDCLEANER_DATA_DIR")
+    if explicit:
+        return Path(explicit).expanduser()
+    if ENV_FILE:
+        return ENV_FILE.parent / "output"
+    return Path.home() / ".cloudcleaner"
+
+
+DATA_DIR = find_data_dir()
+
+# Back-compat aliases. Prefer DATA_DIR for anything that writes.
+PROJECT_ROOT = ENV_FILE.parent if ENV_FILE else Path.cwd()
+APP_DIR = PROJECT_ROOT
+
+# Top-level constants for simple `from cloudcleaner.config import X` imports.
+AWS_REGION = os.getenv("AWS_REGION", "us-east-1")
+GROQ_API_KEY = os.getenv("GROQ_API_KEY")
+GROQ_MODEL = os.getenv("GROQ_MODEL", "openai/gpt-oss-20b")
+GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
+
+# Point boto3 at LocalStack instead of real AWS when set.
+AWS_ENDPOINT_URL = os.getenv("AWS_ENDPOINT_URL") or None
+
+# "aws" reads the live account; "fixture" runs offline against fixtures/demo.py.
+# Resolved at call time in tools/provider.py, so tests can flip it per-test.
+PROVIDER = os.getenv("CLOUDCLEANER_PROVIDER", "aws").lower()
+
+METRIC_WINDOW_DAYS = int(os.getenv("METRIC_WINDOW_DAYS", "7"))
+
+DRY_RUN = os.getenv("CLOUDCLEANER_DRY_RUN", "true").lower() not in ("false", "0", "no")
+
+# false = rules only; no resource metadata is sent to the LLM.
+AI_ENABLED = os.getenv("CLOUDCLEANER_AI_ENABLED", "true").lower() not in ("false", "0", "no")
+
+
+class Settings:
+    AWS_REGION: str = AWS_REGION
+    GROQ_API_KEY: str | None = GROQ_API_KEY
+    GROQ_MODEL: str = GROQ_MODEL
+    GITHUB_TOKEN: str | None = GITHUB_TOKEN
+
+    # Safety / Actions / Evaluation settings
+    DRY_RUN: bool = DRY_RUN
+    VERIFY_MAX_ATTEMPTS: int = int(os.getenv("CLOUDCLEANER_VERIFY_MAX_ATTEMPTS", "5"))
+    VERIFY_POLL_INTERVAL_SECONDS: float = float(
+        os.getenv("CLOUDCLEANER_VERIFY_POLL_INTERVAL", "2")
+    )
+    ROLLBACK_MAX_RETRIES: int = int(os.getenv("CLOUDCLEANER_ROLLBACK_MAX_RETRIES", "2"))
+    COST_APPROVAL_THRESHOLD_USD: float = float(
+        os.getenv("CLOUDCLEANER_COST_THRESHOLD_USD", "50")
+    )
+
+
+settings = Settings()