Development guide

​

Setup

git clone <repository-url> gtm-sdk
cd gtm-sdk

uv sync

uv run gtm --help

​

Everyday commands

uv sync                          # install/lock deps
uv run gtm --help                # list CLI command groups
uv run gtm <GROUP> --help        # list commands in a group
uv run pytest                    # test suite (integration tests excluded)
trunk check --all                # lint + typecheck (ruff, pyright, bandit, ...)
trunk fmt                        # format changed files

​

Linting

trunk check --all                         # everything, whole repo
trunk check --filter=ruff libs/attio/     # reproduce a single tool's finding
trunk fmt cli/main.py                     # format one file

​

Layer rules

• libs/<service>/ wraps one external SDK or API with idiomatic Python types and functions. No libs/<x> module may import from libs/<y>. If two adapters need to coordinate, that coordination belongs in src/.
• src/ is the orchestration layer: multi-step workflows, side effects, and Modal @app.function / @modal.fastapi_endpoint decorators. Adapter modules in libs/ must stay callable in isolation — no orchestration inside libs/.
• cli/ is Typer-only: parse arguments → preflight → call into src/ → render output. No business logic in cli/.

​

Where new code goes

1. External SDK call? New file in libs/<service>/. Wrap one SDK only, no cross-lib imports.
2. Multi-step flow or Modal endpoint? src/<service>/. If the module defines Modal endpoints, add its import to _ENDPOINT_MODULES in src/app.py so the decorators register.
3. User-facing command? cli/<group>/ as a Typer subapp that calls into src/. Wire it into cli/main.py via app.add_typer(...).
4. Standalone data product? data-gen/<product>/. Self-contained and independent of other data products.
5. Webhook handler? webhooks/<name>.py. Each handler is an independent Modal app — do not register it in src/app.py.

​

Testing

uv run pytest                    # unit tests (integration excluded by default)
uv run pytest tests/cli          # one subtree
uv run pytest -m integration     # integration tests (require live credentials)

• Tests mirror the source layout: tests/cli/, tests/libs/, tests/src/, and tests/integration/. Put new tests in the directory that mirrors the code under test.
• Tests that hit live external APIs carry the integration marker, defined in pyproject.toml. The default addopts filter (-m 'not integration') keeps them out of ordinary runs, so uv run pytest never needs credentials.
• Plain assert statements are allowed in tests, but each test file must carry its own # ruff: noqa: S101, ... header — trunk invokes ruff with its own config and never reads pyproject.toml’s per-file-ignores, so a green local ruff check can still land a red CI.

​

Property-based tests

uv run pytest --hypothesis-show-statistics    # dev profile: 50 examples, 400ms deadline
HYPOTHESIS_PROFILE=nightly uv run pytest      # 1000 examples, randomized search

• If the domain is finite and enumerable, check it exhaustively with a loop instead of st.sampled_from. max_examples caps how many values Hypothesis draws, and because the CI profile uses a fixed seed, it draws the same subset on every run — leaving the rest permanently untested. Hypothesis is most valuable on unbounded domains such as arbitrary text.
• Make sure the property is not vacuous. If its interesting branch only runs when a parse succeeds, bare st.text() will almost never reach it. Generate realistic inputs, and call hypothesis.event() so the branch split shows up under --hypothesis-show-statistics.

​

Conventions

• Temporary files go in tmp/ only. The directory is gitignored. Never write scratch output to the repo root or next to source code.
• Anchor script file I/O on the script’s own directory, not the CWD. uv run path/to/script.py does not change the working directory, so relative paths resolve from wherever the command was invoked and can silently write files to the wrong place:
  SCRIPT_DIR = Path(__file__).resolve().parent
  (SCRIPT_DIR / "output.txt").write_text(...)
  
• Scripts under scripts/ are directly executable with uv shebangs where practical. Scripts that need Infisical secrets must show the full flag form in their usage text (--projectId, --token, --env) rather than assuming infisical init has run:
  set -a && source .env.local && set +a
  infisical run --projectId "$INFISICAL_PROJECT_ID" --token "$INFISICAL_TOKEN" --env=<dev|prod> -- <CMD>
  
• Docstrings explain why, not what. Document decisions and gotchas inline, next to the code they affect.
• No summary or investigation .md files. Live documentation belongs in code (docstrings, per-module READMEs); the docs site under docs/ is the only place for prose documentation.

​

Docs site