umbra-py 0.1.0__tar.gz

umbra_py-0.1.0/.claude/hooks/session-start.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# SessionStart hook for Claude Code on the web (and other remote coding agents).
+#
+# A fresh remote container has `uv` and the CLI linters on PATH but does NOT have
+# umbra-py itself installed, so `pytest`, `mypy`, and the `umbra` CLI all fail
+# until the package is installed editable. This hook closes that gap so an agent
+# can run the exact checks CI runs (see .github/workflows/ci.yml) from the first
+# turn — no "command not found", no import-skipped tests.
+#
+# It installs every extra so the FULL offline suite runs rather than
+# import-skipping the viz / serve / convert / load / agent modules — mirroring
+# CI's `test-all-extras` job, the one place every module actually executes and
+# where the coverage gate is measured.
+#
+# Runs synchronously (no `{"async": true}` line) so the environment is ready
+# before the first agent turn — preventing a race where a check runs before its
+# dependencies exist. Idempotent and non-interactive: safe to re-run on
+# resume/clear/compact, and `uv` no-ops when nothing changed.
+set -euo pipefail
+
+# Only bother in a remote environment (Claude Code on the web). Local sessions
+# manage their own venv per AGENTS.md §3.
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# `--system` matches CI: install into the container's Python rather than a venv.
+# The extras list mirrors ci.yml's `test-all-extras` job so nothing import-skips.
+uv pip install --system -e ".[dev,all,dask,mcp,serve,ai,langchain,llamaindex]"
+
+echo "umbra-py installed editable with all extras — ruff / mypy / pytest ready." >&2

umbra_py-0.1.0/.claude/settings.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(uv pip install:*)",
+      "Bash(uv venv:*)",
+      "Bash(ruff check:*)",
+      "Bash(ruff format:*)",
+      "Bash(mypy:*)",
+      "Bash(pytest:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(pre-commit run:*)",
+      "Bash(umbra:*)",
+      "Bash(umbra-py:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)",
+      "Bash(git add:*)"
+    ]
+  }
+}

umbra_py-0.1.0/.dockerignore

@@ -0,0 +1,32 @@
+# Keep the build context small and the image reproducible: ship only the
+# package source + metadata the wheel build needs, never local caches, VCS
+# history, tests, docs, or notebooks.
+.git
+.github
+.gitignore
+.pre-commit-config.yaml
+.ruff_cache
+.mypy_cache
+.pytest_cache
+**/__pycache__
+*.pyc
+.venv
+venv
+build
+dist
+*.egg-info
+tests
+examples
+# The planning docs, but *not* `docs/schemas/`: the wheel force-includes those
+# as package data (`umbra_py/_schemas/`) so `umbra serve` can put the published
+# contracts in its generated OpenAPI document, and an installed package has no
+# checkout to fall back to. Excluding them fails the build outright, which is
+# the honest failure for an image whose /openapi.json would otherwise raise.
+docs/*.md
+docs_src
+mkdocs.yml
+site
+*.db
+*.parquet
+*.pmtiles
+CHANGELOG.md

umbra_py-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Report a problem with umbra-py
+labels: bug
+---
+
+**What happened?**
+A clear description of the bug.
+
+**To reproduce**
+Minimal code (or `umbra ...` command) that triggers it. If it involves a
+specific Umbra item, please include the STAC item URL.
+
+**Expected behavior**
+
+**Environment**
+- umbra-py version:
+- Python version:
+- OS:
+
+**Additional context / traceback**

umbra_py-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest a new feature, workflow, or integration
+labels: enhancement
+---
+
+**Problem you're trying to solve**
+What's hard or impossible to do with umbra-py today?
+
+**Proposed solution**
+A sketch of the API / CLI / workflow you'd like.
+
+**Alternatives considered**
+
+**Additional context**
+Related libraries, Umbra products involved, sample item URLs, etc.

umbra_py-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- What does this PR change and why? Link related issues. -->
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] Tests added or updated (`pytest`)
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] `CHANGELOG.md` updated under **Unreleased** for user-visible changes
+- [ ] Docs / docstrings updated where relevant

umbra_py-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  # Keep workflow actions fresh (checkout, setup-python, setup-uv, ...).
+  # Grouped so a week's bumps arrive as one PR, not five.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # Python deps are open-ended ranges in pyproject.toml, so this mostly
+  # surfaces new majors that fall outside a range — low traffic by design.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]

umbra_py-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,154 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# A superseded push's runs are dead feedback; cancel them.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install package
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Test (offline)
+        run: pytest -q
+
+  # The package ships a py.typed marker, so downstream type checkers trust its
+  # inline annotations. This job verifies they are actually consistent instead
+  # of shipping an unchecked promise. It runs against a core [dev] install (no
+  # optional extras), matching the [tool.mypy] config: the untyped optional
+  # libraries (rasterio, fastapi, sarpy, ...) are import-ignored, so only
+  # umbra-py's own types are checked. This is the surface a bare `pip install
+  # umbra-py` gets; the all-extras surface is checked by the job below.
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install package
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Type check
+        run: mypy
+
+  # The core type-check above import-ignores every optional library, so a
+  # misuse of one that *does* ship stubs (PIL, click, numpy) is invisible to it
+  # -- exactly how `Image.ADAPTIVE`, wrong under Pillow's stubs, reached main
+  # and greeted every stubs-present dev/agent session with a failing mypy line.
+  # This job installs all extras and runs the same mypy, so that surface is
+  # checked on every PR -- the type-check mirror of `test-all-extras`.
+  type-check-all-extras:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install package with all extras
+        run: uv pip install --system -e ".[dev,all,dask,mcp,serve,ai,langchain,llamaindex]"
+
+      # `--python-version 3.12` overrides the config's 3.10 target for this job
+      # only. numpy's shipped stubs use PEP 695 `type` statements, which mypy
+      # refuses to parse below a 3.12 target -- so checking the all-extras
+      # surface at 3.10 dies in numpy's `.pyi`, not in our code. The 3.10 floor
+      # that the py.typed promise is really about stays enforced on umbra-py's
+      # own annotations by the core `type-check` job above (which has no numpy);
+      # the `[attr-defined]`-class misuse this job exists to catch is
+      # target-independent, so nothing is lost by checking the stub surface at
+      # 3.12.
+      - name: Type check (all extras)
+        run: mypy --python-version 3.12
+
+  # The core matrix installs only [dev], so every test needing an optional
+  # extra (viz / load / convert / export) importorskips there — silently.
+  # This job installs everything so those tests actually run on every PR.
+  test-all-extras:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install package with all extras
+        run: uv pip install --system -e ".[dev,all,dask,mcp,serve,ai,langchain,llamaindex]"
+
+      # This is the one job where every module actually runs, so it is also
+      # where coverage is meaningful. The floor guards against regressions; it
+      # sits a couple of points below the current figure so ordinary branch
+      # fluctuation across Python patch releases doesn't turn CI red. The XML
+      # report feeds the Codecov badge in the README.
+      - name: Test (offline, all extras) with coverage
+        run: >-
+          pytest -q
+          --cov=umbra_py
+          --cov-report=term-missing
+          --cov-report=xml
+          --cov-fail-under=88
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7
+        with:
+          files: ./coverage.xml
+          # Never let a coverage-upload hiccup (or an unconfigured Codecov
+          # integration) fail the build — the gate above is the real check.
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}

umbra_py-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,64 @@
+name: Docker
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# A superseded push's build is dead feedback; cancel it.
+concurrency:
+  group: docker-image-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Build the self-hosting `umbra serve` image and smoke-test it end to end,
+  # so a broken Dockerfile / entrypoint fails review instead of a user's first
+  # `docker run`. Everything here is offline: the smoke test serves in live
+  # mode (no index, no S3 walk until an actual /search), so `/` and `/healthz`
+  # answer without any external network.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build image (serve extra)
+        run: docker build --build-arg UMBRA_EXTRAS=serve -t umbra-py:ci .
+
+      - name: CLI passthrough works
+        run: docker run --rm umbra-py:ci --version
+
+      - name: Validate compose file
+        run: docker compose config >/dev/null
+
+      - name: Start the server (live mode -- no external network)
+        run: docker run -d --name umbra-serve -e UMBRA_SERVE_LIVE=1 -p 8000:8000 umbra-py:ci
+
+      - name: Wait for /healthz
+        run: |
+          for _ in $(seq 1 30); do
+            if curl -fsS http://127.0.0.1:8000/healthz >/dev/null; then
+              echo "healthy"; exit 0
+            fi
+            sleep 2
+          done
+          echo "server did not become healthy in time" >&2
+          docker logs umbra-serve || true
+          exit 1
+
+      - name: Landing page is a STAC Catalog
+        run: |
+          curl -fsS http://127.0.0.1:8000/ \
+            | python -c "import sys,json; d=json.load(sys.stdin); assert d['type']=='Catalog'; print('landing OK')"
+
+      - name: /healthz reports a ready live backend
+        run: |
+          curl -fsS http://127.0.0.1:8000/healthz \
+            | python -c "import sys,json; d=json.load(sys.stdin); assert d['ready'] is True and d['backend']=='live', d; print('healthz OK')"
+
+      - name: Server logs
+        if: always()
+        run: docker logs umbra-serve || true
+
+      - name: Cleanup
+        if: always()
+        run: docker rm -f umbra-serve || true

umbra_py-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,150 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # The showcase is built from the `catalog-index` release, not from the repo,
+  # so a freshly published index changes what the site should show while the
+  # commit it deploys from stays identical. Without this the showcase only
+  # refreshes when something unrelated lands on main — and a *first* index
+  # publish leaves site/showcase/ missing (a 404 on a link the docs advertise)
+  # until the next push happens to come along. Rebuild when the index does.
+  workflow_run:
+    workflows: ["Publish catalog index"]
+    types: [completed]
+
+# Only one concurrent Pages deployment; a superseded build is dead feedback.
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Build on every PR (and on main) so a broken docstring cross-reference or
+  # nav entry fails review, not the deploy. `--strict` turns warnings into
+  # errors. The package itself is installed with every extra so mkdocstrings
+  # can import each module it documents.
+  build:
+    runs-on: ubuntu-latest
+    # A failed index publish has no new snapshot to show, so don't redeploy for
+    # it. (Push and pull_request runs carry no workflow_run context and always
+    # proceed.)
+    if: >-
+      github.event_name != 'workflow_run'
+      || github.event.workflow_run.conclusion == 'success'
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install package + docs toolchain
+        run: uv pip install --system -e ".[docs,all,mcp,serve,ai,langchain,llamaindex]"
+
+      - name: Build (strict)
+        run: mkdocs build --strict
+
+      # Build the static, zero-install showcase (a whole-catalog interactive
+      # explorer over the published snapshot plus a gallery of precomputed
+      # change composites) into site/showcase/ so it deploys to GitHub Pages
+      # beside the docs. Main-only (it deploys only from main) and non-blocking:
+      # if the catalog-index release isn't published yet, or the fetch fails, the
+      # docs deploy must still go out, so this step never fails the job
+      # (STRATEGY.md §8 demo/hosting).
+      #
+      # Non-blocking, but never *silent*. This was `continue-on-error`, which
+      # reports the step as having succeeded, so a run that shipped no showcase
+      # at all looked exactly like one that shipped a good one: the docs went
+      # green while the showcase link they advertise served a 404. The failure
+      # is swallowed here instead — deliberately, and with a warning annotation
+      # plus a job-summary note — so the deploy still goes out and the run that
+      # dropped the showcase says so.
+      #
+      # --unified builds ONE explorer page reading catalog.pmtiles directly, so
+      # the landing page leads to the whole catalog with the filters, rather than
+      # to a click-only map and a separate explorer over a gathered slice. It
+      # searches nothing, so no --local/--limit/--max-per-task here.
+      #
+      # --featured 6 renders six change composites, streaming only a downsampled
+      # overview of each scene (the `viz` extra arrives with `[all]` above); a
+      # site whose asset won't render is dropped with a warning, so a bad scene
+      # costs one tile rather than the gallery. That selection *does* read the
+      # index, hence the fetch below.
+      - name: Build catalog showcase
+        if: github.ref == 'refs/heads/main'
+        # Mode A: the model key is held here, at build time, and never reaches
+        # the static site (a secret shipped to a browser is a published secret).
+        # `umbra showcase --narrate` bakes a cached reading per featured site; it
+        # is gated on a key's presence inside the command, so a fork PR (no
+        # secrets) or an unset secret just skips the narrations and still ships
+        # the gallery. Any one of the three keys works — whichever the maintainer
+        # set as a repo secret.
+        env:
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          set +e
+          umbra index fetch &&
+            umbra showcase \
+              --unified \
+              --local \
+              --fetch-pmtiles \
+              --featured 6 \
+              --narrate \
+              --out site/showcase \
+              --updated "$(date -u +%Y-%m-%d)"
+          status=$?
+          set -e
+
+          # A half-written directory would deploy as a broken showcase, which is
+          # worse than none: check for the landing page the build promises, not
+          # just the exit status.
+          if [ "$status" -eq 0 ] && [ -f site/showcase/index.html ]; then
+            echo "Showcase built into site/showcase/."
+            exit 0
+          fi
+          rm -rf site/showcase
+          note="The docs deployed without site/showcase/, so \
+          https://umbra-py.space/showcase/ will 404 until a run \
+          rebuilds it. Usual cause: the rolling 'catalog-index' release has no \
+          catalog.db yet, so 'umbra index fetch' 404s — check the 'Publish \
+          catalog index' workflow."
+          echo "::warning title=Showcase not built::${note}"
+          {
+            echo "### :warning: Showcase not built"
+            echo
+            echo "${note}"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  # Publish to GitHub Pages, but only from main — never from a PR. Requires
+  # Pages to be enabled for the repository (Settings → Pages → Source: GitHub
+  # Actions); until then this job is skipped/red without affecting PR CI.
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

umbra_py-0.1.0/.github/workflows/live-canary.yml

@@ -0,0 +1,62 @@
+name: Live catalog canary
+
+# Umbra's open-data catalog is an external dependency that drifts: bucket
+# layout, sidecar naming, asset keys (models.py already handles two naming
+# generations). The offline suite can't see that drift, so this runs the
+# `-m network` integration tests against the live catalog on a schedule.
+# A failure here usually means "Umbra changed something", not "a PR broke
+# it" — it opens (or comments on) a tracking issue instead of failing PRs.
+
+on:
+  schedule:
+    - cron: "43 5 * * 1" # Mondays 05:43 UTC, ahead of the index publish
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  live-tests:
+    runs-on: ubuntu-latest
+    # Don't hit Umbra's bucket from forks; schedules there stay off anyway.
+    if: github.repository == 'reesehammer/umbra-py'
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install package with all extras
+        run: uv pip install --system -e ".[dev,all]"
+
+      - name: Run live tests against Umbra's public catalog
+        run: pytest -m network -q
+
+      - name: Open or update a tracking issue on failure
+        if: failure()
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          run_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          body="The scheduled \`pytest -m network\` run against Umbra's public
+          catalog failed on $(date -u +%Y-%m-%d) — likely catalog drift
+          (bucket layout, sidecar naming, asset keys) rather than a code
+          regression. See the [failed run]($run_url)."
+          existing=$(gh issue list --state open \
+            --search 'Live catalog canary failed in:title' \
+            --json number --jq '.[0].number')
+          if [ -n "$existing" ]; then
+            gh issue comment "$existing" --body "$body"
+          else
+            gh issue create --title "Live catalog canary failed" --body "$body"
+          fi