generic-ml-wrapper 0.1.0__tar.gz

generic_ml_wrapper-0.1.0/.coveragerc

@@ -0,0 +1,4 @@
+# Make coverage record file paths relative to the repo root, so the Cobertura
+# report resolves against sonar.sources (src/) in SonarQube Cloud.
+[run]
+relative_files = true

generic_ml_wrapper-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto

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

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel superseded runs on the same ref (e.g. rapid pushes to a PR).
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+# CI is a thin caller of nox (see noxfile.py), run through uv from the committed
+# uv.lock -- so the check here is byte-for-byte the local gate AND every build-time
+# input is pinned: GitHub Actions by commit SHA, uv by [tool.uv] required-version,
+# and nox by the lock (`uv run --frozen nox`). A dependency -- or a tool that runs
+# the gate -- can only move via a deliberate `uv lock --upgrade` or a SHA bump.
+# lint/typecheck/imports/coverage are version-independent (their own single jobs, no
+# --python filter, which would silently drop a session declaring no interpreter);
+# tests fan out across the interpreter matrix.
+env:
+  UV_CACHE_DIR: ${{ github.workspace }}/.uv-cache
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Run tests (nox from the lock)
+        run: uv run --frozen nox --python ${{ matrix.python-version }} -s tests
+
+  lint:
+    name: lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Lint + format check (nox from the lock)
+        run: uv run --frozen nox -s lint
+
+  typecheck:
+    name: typecheck (pyright)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Type check (nox from the lock)
+        run: uv run --frozen nox -s typecheck
+
+  import-contracts:
+    name: architecture contracts (import-linter)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Check architecture contracts (nox from the lock)
+        run: uv run --frozen nox -s imports
+
+  coverage:
+    name: coverage (>=80%)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Tests with coverage floor (nox from the lock)
+        run: uv run --frozen nox -s coverage
+
+  # A single, stable check that rolls up every gate job, so branch protection can
+  # require "ci" instead of every matrix + gate job name.
+  ci:
+    name: ci
+    runs-on: ubuntu-latest
+    needs: [test, lint, typecheck, import-contracts, coverage]
+    if: ${{ always() }}
+    steps:
+      - name: All gate jobs passed
+        run: |
+          results="${{ needs.test.result }} ${{ needs.lint.result }} ${{ needs.typecheck.result }} ${{ needs.import-contracts.result }} ${{ needs.coverage.result }}"
+          echo "gate results: $results"
+          for r in $results; do
+            if [ "$r" != "success" ]; then
+              echo "a gate job did not pass"
+              exit 1
+            fi
+          done
+          echo "all gate jobs passed"

generic_ml_wrapper-0.1.0/.github/workflows/pr-hygiene.yml

@@ -0,0 +1,47 @@
+name: PR hygiene
+
+# Server-side enforcement of the "no AI attribution" rule. The commit-msg hook
+# (tools/hooks/check-commit-msg.sh) covers commit messages locally, but hooks are
+# opt-in and `--no-verify`-bypassable, and a PR's title/body live only on GitHub.
+# This required check gives the rule teeth: it scans the PR title, body, AND every
+# commit message in the PR, with the SAME regex the local hook uses.
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  no-ai-attribution:
+    name: no AI attribution
+    runs-on: ubuntu-latest
+    env:
+      # Kept byte-for-byte in sync with tools/hooks/check-commit-msg.sh.
+      PATTERN: 'co-authored-by:[[:space:]]*.*(claude|copilot|chatgpt|gpt-|anthropic|openai)|generated with[[:space:]]+\[?(claude|copilot|chatgpt)|🤖[[:space:]]*generated'
+    steps:
+      - name: Check PR title and body
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+          BODY: ${{ github.event.pull_request.body }}
+        run: |
+          if printf '%s\n%s' "$TITLE" "$BODY" | grep -qiE "$PATTERN"; then
+            echo "::error::PR title or body contains AI attribution -- please remove it."
+            exit 1
+          fi
+          echo "OK: no AI attribution in PR title/body."
+
+      - name: Check commit messages
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          msgs=$(gh api --paginate \
+            "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/commits" \
+            --jq '.[].commit.message')
+          if printf '%s' "$msgs" | grep -qiE "$PATTERN"; then
+            echo "::error::A commit message contains AI attribution -- please amend it."
+            exit 1
+          fi
+          echo "OK: no AI attribution in commit messages."

generic_ml_wrapper-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+# Publish to PyPI via Trusted Publishing (OIDC) when a GitHub Release is published.
+# No token or secret: PyPI trusts this exact repo + workflow + environment, and
+# GitHub mints a short-lived OIDC credential for the upload. Every build-time input
+# is pinned (Actions by commit SHA, uv by [tool.uv] required-version).
+name: release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        run: uv publish --trusted-publishing always

generic_ml_wrapper-0.1.0/.github/workflows/sonar.yml

@@ -0,0 +1,34 @@
+name: Sonar
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  sonar:
+    name: SonarQube Cloud
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          fetch-depth: 0 # full history so Sonar can attribute new code and blame
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+
+      # Thin caller of nox (see noxfile.py): the `sonar` session writes coverage.xml
+      # (path in sonar-project.properties) that the scan below ingests.
+      - name: Run tests with coverage (nox from the lock)
+        run: uv run --frozen nox -s sonar
+
+      - uses: SonarSource/sonarqube-scan-action@713881670b6b3676cda39549040e2d88c70d582e # v8
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

generic_ml_wrapper-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage / tooling caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.nox/
+.ruff_cache/
+coverage.xml
+
+# Editors / OS / tools
+.idea/
+.vscode/
+.claude/
+.DS_Store
+Thumbs.db
+
+# Secrets — nothing secret belongs in this public repo, but guard anyway
+.env
+*.pem
+*.key
+secrets/
+credentials.toml
+
+# Local bootstrap/publish tooling — never published.
+# secret-audit.sh contains the literal private terms it scans for, so it must
+# not be committed (it would reintroduce the very leak it checks for).
+/setup-repo.sh
+/secret-audit.sh

generic_ml_wrapper-0.1.0/.importlinter

@@ -0,0 +1,40 @@
+[importlinter]
+root_package = generic_ml_wrapper
+
+# Rule 1 — domain purity. The innermost ring models the world; it must not import
+# use cases, ports, the composition root, or any adapter. (The interceptor_chain ->
+# port.outbound.interceptor edge this catches was the sole violation at review time,
+# fixed by defining the Interceptor abstraction in the domain and having the outbound
+# InterceptorPort extend it.)
+[importlinter:contract:domain-purity]
+name = Domain must not import use cases, ports, wiring, or adapters
+type = forbidden
+source_modules =
+    generic_ml_wrapper.application.domain
+forbidden_modules =
+    generic_ml_wrapper.application.usecase
+    generic_ml_wrapper.application.port
+    generic_ml_wrapper.application.wiring
+    generic_ml_wrapper.adapter
+
+# Rule 2 — the application ring (domain + use cases + ports) is independent of the
+# adapter and composition layers. Dependencies point inward, never outward.
+[importlinter:contract:application-ring]
+name = Application ring must not import adapters or the composition root
+type = forbidden
+source_modules =
+    generic_ml_wrapper.application.domain
+    generic_ml_wrapper.application.usecase
+    generic_ml_wrapper.application.port
+forbidden_modules =
+    generic_ml_wrapper.adapter
+    generic_ml_wrapper.application.wiring
+
+# Rule 3 — ports are abstractions; use cases depend on them, never the reverse.
+[importlinter:contract:ports-no-usecases]
+name = Ports must not import use cases
+type = forbidden
+source_modules =
+    generic_ml_wrapper.application.port
+forbidden_modules =
+    generic_ml_wrapper.application.usecase

generic_ml_wrapper-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,57 @@
+# .pre-commit-config.yaml -- the gates that run BEFORE a commit is written.
+#
+# A failing hook rejects the commit, so malformed code can never reach local
+# history (and therefore can never be pushed). The linters are local hooks backed
+# by the project's own .venv, so no extra environment and no network is needed.
+#
+# One-time setup after cloning:
+#   nox -s dev
+#   .venv/bin/pre-commit install
+#   .venv/bin/pre-commit install --hook-type commit-msg
+#
+# Run manually against all files:
+#   .venv/bin/pre-commit run --all-files
+#
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff (lint)
+        entry: .venv/bin/ruff check .
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: lint-imports
+        name: import-linter (architecture contracts)
+        entry: .venv/bin/lint-imports
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: ruff-format
+        name: ruff (format check)
+        entry: .venv/bin/ruff format --check .
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: pyright
+        name: pyright (strict type checking)
+        entry: .venv/bin/pyright --pythonpath .venv/bin/python
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: guard-branch
+        name: branch guard (no commits to main; naming convention)
+        entry: tools/hooks/guard-branch.sh
+        language: script
+        pass_filenames: false
+        always_run: true
+
+      - id: no-ai-attribution
+        name: no AI attribution in commit message
+        entry: tools/hooks/check-commit-msg.sh
+        language: script
+        stages: [commit-msg]

generic_ml_wrapper-0.1.0/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md — working rules for this repo
+
+Rules an automated or human contributor must follow. Where a rule can be a
+runnable gate it is one (see `.pre-commit-config.yaml` and `noxfile.py`); prose
+here is the intent behind those gates.
+
+## Process
+
+- **Never commit directly to `main`.** Work on a branch named
+  `feature/… tech/… fix/… release/… docs/… chore/… test/…`. Enforced by
+  `tools/hooks/guard-branch.sh`.
+- **`nox -s green` must pass before every commit** — ruff (lint + format), import
+  contracts, pyright strict, tests + coverage floor. The gate that runs locally is the
+  one CI runs. `main` requires the `ci` and `no AI attribution` checks (branch protection).
+- **Keep changes small and cohesive**, each landing with its tests and leaving the gate
+  green. The pipeline is never red.
+- **No AI/assistant attribution** in commit messages or PRs. Enforced locally by
+  `tools/hooks/check-commit-msg.sh` and server-side by the `pr-hygiene` workflow.
+
+## Architecture
+
+- The design is `docs/DESIGN.md`; do not re-derive it. Follow the hexagon:
+  **dependencies point inward** (domain ← usecase ← ports; adapters depend on
+  ports, never the reverse).
+- **Public-clean by construction.** No personal data, employer, internal hosts, or
+  private protocols in this repo — real content lives only under `~/.gmlw`. Commit with a
+  public identity (a GitHub no-reply address), never a private/work one; the gitignored
+  `secret-audit.sh` gates every publish for private terms and secrets.
+- **Strict typing.** pyright strict, zero errors, over **both `src/` and `tests/`**,
+  pinned to `pyright==1.1.411`. `# type: ignore` only for a provably-safe case that cannot
+  be expressed in the type system, with a comment.

generic_ml_wrapper-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-14
+
+First public release — a metering wrapper around ML coding CLIs.
+
+### Added
+- **Jobs & sessions.** Enter at a **job** you tag; the wrapper mints a named,
+  resumable **session** on the client and persists it. `gmlw start`, `jobs`,
+  `sessions`, `export`.
+- **Four clients** driven the same way: **claude**, **cursor**, **codex**, **vibe**.
+  Which one is config-driven (`[client]`) or `--client`.
+- **Metering relay.** A local, capability-URL-authenticated relay records **per-turn
+  tokens and cost** for the metered clients (claude/codex/vibe) into a SQLite ledger;
+  `gmlw export` reports per-turn rows, per-model totals, and per-session cost.
+- **Status line** for the clients that host one (claude, cursor): git · folder ·
+  model · context% · a client-specific allowance block, plus a per-session and
+  per-job usage footer.
+- **Workflows.** Author a small operating context once (`gmlw workflow new`, a warm
+  create-workflow interview) and launch a job with it; context is compiled from a
+  shared base + your profile + rules + the workflow steps, through an interceptor
+  chain (with opt-in context compression via `generic-ml-cache`).
+- **Durable provenance.** The exact compiled context is written per session
+  (`contexts/<job>/<session>.context.md`); an **opt-in transcript** keeps each metered
+  call's request/response/usage.
+- **Credentials.** Per-workflow secrets stored `0600` and injected into the client's
+  environment at launch (`gmlw creds set`).
+- **Storage.** A single SQLite ledger (`~/.gmlw/ledger.db`, WAL) for jobs, sessions,
+  per-turn usage, and session costs.
+- **Safety.** Validated `JobId` + filesystem containment under an owner-only `~/.gmlw`;
+  never overwriting an unparseable client-settings or credentials file.
+
+### Engineering
+- Hexagonal (ports & adapters), enforced by `import-linter`; strict `ruff` + `pyright`
+  over `src` and `tests`; `nox` gates mirrored by CI across Python 3.11–3.14; a
+  server-side no-AI-attribution check and branch protection.
+
+[Unreleased]: https://github.com/danielslobozian/generic-ml-wrapper/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/danielslobozian/generic-ml-wrapper/releases/tag/v0.1.0

generic_ml_wrapper-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,89 @@
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, please use the repository's **private reporting** channel: go to the **Security** tab and choose **Report a vulnerability**, which opens a confidential advisory visible only to the maintainers — note clearly at the top that it is a **Code of Conduct report**, not a security issue. This keeps the report private without requiring an email address. If you would rather not use that channel, or if a maintainer is the subject of the report, you may report the account or content directly to GitHub through [GitHub's report abuse flow](https://github.com/contact/report-abuse). Please do **not** open a public issue for a Code of Conduct concern.
+
+The maintainers act as this project's Community Moderators. They take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) Warning
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) Temporarily Limited Activities
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) Temporary Suspension
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) Permanent Ban
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).

generic_ml_wrapper-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing
+
+Thanks for your interest in `generic-ml-wrapper`. This is an open project under the
+Apache-2.0 license and contributions are welcome — bug reports, documentation, tests,
+and code alike.
+
+By participating you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Ways to help
+
+- **Report a bug.** Open an issue describing what you ran and what happened. A minimal
+  repro — the exact `gmlw` command, the client, and a failing test if you can — is gold.
+- **Propose a feature.** Open an issue and check [`docs/DESIGN.md`](docs/DESIGN.md)
+  first — the design invariants there are load-bearing, and your idea may already be
+  covered or deliberately out of scope.
+- **Improve the docs.** If something was unclear, a doc fix helps the next person.
+- **Send code.** See below.
+
+## Development setup
+
+You need Python 3.11–3.13 and [`uv`](https://docs.astral.sh/uv/). The gates run through
+[`nox`](https://nox.thea.codes/) with the `uv` backend, from the committed `uv.lock`.
+
+```bash
+git clone https://github.com/danielslobozian/generic-ml-wrapper.git
+cd generic-ml-wrapper
+uv sync --extra dev        # install the project + dev tools into .venv
+# or: nox -s dev           # build the IDE .venv the same way
+pre-commit install         # wire the local git hooks (optional but recommended)
+```
+
+The only runtime dependencies are the sibling
+[`generic-ml-cache`](https://github.com/danielslobozian/generic-ml-cache) packages
+(`-core`, `-adapters`, `-bootstrap`) — used by the context compressor. Dev tooling
+(`pytest`, `ruff`, `pyright`, `import-linter`, `nox`, `pre-commit`) lives in the `dev`
+extra / dependency group and is pinned by the lock.
+
+## The gate
+
+The gates are defined once in [`noxfile.py`](noxfile.py); CI is a thin caller of them,
+so what runs locally is byte-for-byte what runs in CI.
+
+```bash
+nox                # the default gate: lint · imports · typecheck · tests (3.11–3.13)
+nox -s green       # the whole gate in one env: lint · format · imports · pyright · coverage
+nox -s tests       # just the test matrix
+nox -s coverage    # tests with the 80% coverage floor
+```
+
+- **`lint`** — `ruff check` + `ruff format --check` (line length 100, strict rule set).
+- **`typecheck`** — `pyright` in **strict** mode over both `src/` **and** `tests/`
+  (pinned to `pyright==1.1.411`; the 3.11 floor is checked deliberately).
+- **`imports`** — `lint-imports`: the three hexagon contracts in `.importlinter`.
+- **`coverage`** — the suite with an 80% floor.
+
+The suite is **offline and token-free**: no real client is launched, no network call is
+made, and no model is invoked — external boundaries are faked, and `~/.gmlw` is
+redirected to a temp dir for every test. CI runs it on Linux, macOS, and Windows across
+Python 3.11–3.13; make sure it passes locally before opening a PR.
+
+## Coding guidelines
+
+- **Dependencies point inward.** `domain ← usecase ← ports`; adapters depend on ports,
+  never the reverse. This is enforced by `import-linter`, not just convention — see the
+  hexagon in [`docs/DESIGN.md`](docs/DESIGN.md).
+- **The domain is pure.** Entities and domain services do no I/O and import no adapter.
+  A new capability the app *needs* from the world is an outbound **port**, implemented by
+  an adapter and wired in `application/wiring/composition.py`.
+- **Strict typing.** `pyright` strict, zero errors. A `# type: ignore` is only for a
+  provably-safe case that cannot be expressed in the type system, with a comment.
+- **Public-clean by construction.** No personal data, employer, internal hosts, or work
+  identities in the repo — real content lives only under `~/.gmlw`. Commit with a public
+  identity (a GitHub no-reply address), not a private/work one.
+- **Cross-platform.** Don't assume an OS; the CI matrix (incl. Windows) will tell on you.
+- **Match the existing style.** `ruff` formats and lints; run `nox -s lint` (or
+  `ruff check . && ruff format .`).
+
+## Pull request process
+
+1. Branch from `main` — `feature/… tech/… fix/… docs/… chore/… test/…`. Direct pushes to
+   `main` are blocked by branch protection.
+2. Make your change with tests that cover it, keeping `nox -s green` passing.
+3. Update [`CHANGELOG.md`](CHANGELOG.md) under `[Unreleased]`.
+4. Open the pull request and describe the *why*, not just the *what*; link any related
+   issue. CI must be green and the **no-AI-attribution** check must pass — commit messages
+   and PR text must contain no AI/assistant attribution (a hard project rule, enforced
+   both by a local hook and server-side).
+
+See [`GOVERNANCE.md`](GOVERNANCE.md) for how decisions get made.
+
+## Reporting security issues
+
+Please do **not** open a public issue for a vulnerability. Follow
+[`SECURITY.md`](SECURITY.md) instead.