cq-sdk 0.1.0__tar.gz

cq_sdk-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,84 @@
+name: Bug Report
+description: Report a bug or an unexpected behavior
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report!
+        Please read the [Contributing Guidelines](CONTRIBUTING.md) before submitting.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the bug here.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: Steps to Reproduce
+      description: |
+        Provide clear steps to reproduce the behavior.
+        Please include code snippets, configurations, or detailed commands if relevant.
+      placeholder: |
+        1. Install cq-python '...'
+        2. Run code '....'
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+      placeholder: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: A clear and concise description of what actually happened.
+      placeholder: What actually happened?
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Provide details about your environment.
+      value: |
+        - **OS:** [e.g. macOS, Windows, Linux] (and version)
+        - **Python Version:** [e.g. 3.12]
+        - **cq-python Version:** [e.g. 0.1.0]
+        - **Other relevant libraries/versions:**
+      render: markdown
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Log Output
+      description: |
+        If applicable, paste any relevant log and terminal output, error messages, or screenshots.
+        Please wrap code blocks in triple backticks (```).
+      render: shell
+    validations:
+      required: false
+  - type: checkboxes
+    id: self-checklist
+    attributes:
+      label: Self-Checklist
+      options:
+        - label: I have read the [Contributing Guidelines](CONTRIBUTING.md).
+          required: true
+        - label: I have searched the existing issues and found no duplicate.
+          required: true
+        - label: I have provided a clear and concise description of the bug.
+          required: true
+        - label: I have provided clear steps to reproduce the bug.
+          required: true
+        - label: I have provided details about my environment.
+          required: true

cq_sdk-0.1.0/.github/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/mozilla-ai/cq-python/security/policy
+    about: Please report security vulnerabilities responsibly.

cq_sdk-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,54 @@
+name: Feature Request
+description: Suggest an idea or enhancement for the project.
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an idea!
+        Please read the [Contributing Guidelines](CONTRIBUTING.md) before submitting.
+  - type: textarea
+    id: problem-description
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of the problem you're trying to solve. e.g. "I'm always frustrated when [...]"
+      placeholder: Describe the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: solution-description
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+      placeholder: Describe the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+      placeholder: Describe alternatives.
+    validations:
+      required: false
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context or screenshots about the feature request here.
+      placeholder: Any additional information.
+    validations:
+      required: false
+  - type: checkboxes
+    id: self-checklist
+    attributes:
+      label: Self-Checklist
+      options:
+        - label: I have read the [Contributing Guidelines](CONTRIBUTING.md).
+          required: true
+        - label: I have searched the existing issues and found no duplicate.
+          required: true
+        - label: I have provided a clear and concise description of the problem.
+          required: true
+        - label: I have provided a clear and concise description of the proposed solution.
+          required: true

cq_sdk-0.1.0/.github/ISSUE_TEMPLATE/task.yaml

@@ -0,0 +1,37 @@
+name: Task
+description: Create a simple task or to-do item
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for simple tasks, improvements, or to-do items that don't fit the bug report or feature request categories.
+        Please read the [Contributing Guidelines](CONTRIBUTING.md) before submitting.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the task.
+      placeholder: What needs to be done?
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Add any other context, references, or details about the task.
+    validations:
+      required: false
+  - type: checkboxes
+    id: self-checklist
+    attributes:
+      label: Self-Checklist
+      options:
+        - label: I have read the [Contributing Guidelines](CONTRIBUTING.md).
+          required: true
+        - label: I have searched the existing issues and found no duplicate.
+          required: true
+        - label: I have provided a clear and concise description of the task.
+          required: true
+        - label: I have provided a clear and concise description of the proposed solution.
+          required: true

cq_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - directory: "/"
+    package-ecosystem: "pip"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "maintenance"
+
+  - directory: "/"
+    package-ecosystem: "github-actions"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "maintenance"

cq_sdk-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Description
+<!-- What does this PR do? -->
+
+
+## PR Type
+<!-- Delete the types that don't apply -->
+
+- New Feature
+- Bug Fix
+- Refactor
+- Documentation
+- Infrastructure
+
+## Relevant issues
+<!-- e.g. "Fixes #123" -->
+
+## Checklist
+<!-- If this checklist is deleted from the PR submission it will be immediately closed -->
+- [ ] I understand the code I am submitting.
+- [ ] I have added unit tests that prove my fix/feature works
+- [ ] I have run this code locally and verified it fixes the issue.
+- [ ] New and existing tests pass locally
+- [ ] Documentation was updated where necessary
+- [ ] I have read and followed the [contribution guidelines](https://github.com/mozilla-ai/cq-python/blob/main/CONTRIBUTING.md)

cq_sdk-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Fetch skill prompt
+        run: make fetch-skill
+
+      - name: Check required artifacts
+        run: test -f src/cq/protocol/skill.md || { echo "Missing skill.md — run make fetch-skill"; exit 1; }
+
+      - name: Lint
+        run: |
+          uv sync --group dev
+          make lint
+
+  test:
+    name: Test
+    needs: [lint]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Test
+        run: |
+          uv sync --group dev
+          make test

cq_sdk-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload to PyPI
+        if: github.event_name == 'release'
+        uses: pypa/gh-action-pypi-publish@release/v1

cq_sdk-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.idea/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.so
+.coverage
+htmlcov/
+tmp/

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

@@ -0,0 +1,34 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args:
+          - "--fix=lf"
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.8
+    hooks:
+      - id: ruff
+        args:
+          - "--fix"
+          - "--exit-non-zero-on-fix"
+      - id: ruff-format
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        exclude: uv\.lock$
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.10.7
+    hooks:
+      - id: uv-lock

cq_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

cq_sdk-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the team at mozilla.ai. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

cq_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to cq
+
+Thank you for your interest in contributing to cq. This guide explains how to get involved.
+
+---
+
+## **Guidelines for Contributions**
+
+### Ground Rules
+
+- Review issue discussion fully before starting work. Engage in the thread first when an issue is under discussion.
+- PRs must build on agreed direction where ones exist. If there is no agreed direction, seek consensus from the core maintainers.
+- PRs with "drive-by" unrelated changes or untested refactors will be closed.
+- Untested or failing code is not eligible for review.
+- PR description **must** follow the PR template and explain **what** changed, **why**, and **how to test**.
+- Links to related issues are required.
+- Duplicate PRs will be automatically closed.
+- Only have 1-2 PRs open at a time. Any further PRs will be closed.
+
+**Maintainers reserve the right to close issues and PRs that do not align with the library roadmap.**
+
+### Code Clarity and Style
+
+- **Readability first:** Code must be self-documenting—if it is not self-explanatory, it should include clear, concise comments where logic is non-obvious.
+- **Consistent Style:** Follow existing codebase style (e.g., function naming, Go conventions)
+- **No dead/debug code:** Remove commented-out blocks, leftover debug statements, unrelated refactors
+- Failure modes must be documented and handled with robust error handling.
+
+### Testing Requirements
+
+- **Coverage:** All new functionality must include unit tests covering both happy paths and relevant edge cases.
+- **Passing tests:** All linting and formatting checks must pass (see below on how to run).
+- **No silent failures:** Tests should fail loudly on errors. No placeholder tests.
+
+### Scope and Size
+
+- **One purpose per PR:** No kitchen-sink PRs mixing bugfixes, refactors, and features.
+- **Small, reviewable chunks:** If your PR is too large to review in under 30 minutes, break it up into chunks.
+- Each chunk must be independently testable and reviewable
+- If you can't explain why it can't be split, expect an automatic request for refactoring.
+- Pull requests that are **large** (>500 LOC changed) or span multiple subsystems will be closed with automatic requests for refactoring.
+- If the PR is to implement a new feature, please first make a GitHub issue to suggest the feature and allow for discussion. We reserve the right to close feature implementations and request discussion via an issue.
+
+## How to Contribute
+
+### **Browse Existing Issues** 🔍
+- Check the Issues page to see if there are any tasks you'd like to tackle.
+- Look for issues labeled **`good first issue`** if you're new to the project—they're a great place to start.
+
+### **Report Issues** 🐛
+- **Bugs:** Please use our [Bug Report template](.github/ISSUE_TEMPLATE/bug_report.yaml) to provide clear steps to reproduce and environment details.
+- **Search First:** Before creating a new issue, please search existing issues to see if your topic has already been discussed.
+- Provide as much detail as possible, including the steps to reproduce the issue and expected vs. actual behavior.
+
+### **Suggest Features** 🚀
+- **Features:** Please use our [Feature Request template](.github/ISSUE_TEMPLATE/feature_request.yaml) to describe the problem your idea solves and your proposed solution.
+- Share why the feature is important and any alternative solutions you've considered.
+- If the PR is to implement a new feature, please first make a GitHub issue to suggest the feature and allow for discussion.
+
+## Before You Start
+
+- **Search for duplicates.** Check [existing issues](https://github.com/mozilla-ai/cq-python/issues) and [open pull requests](https://github.com/mozilla-ai/cq-python/pulls) before starting work.
+- **Discuss major changes first.** Open an issue before starting work on: new features, API changes, architectural changes, breaking changes, or new dependencies. This avoids wasted effort and helps maintainers provide early guidance.
+- **Set up your development environment.** See the [README](README.md) for prerequisites, installation, and how to run tests and linters.
+
+## Making Changes
+
+### Branch Naming
+
+Use descriptive branch names with one of these prefixes:
+
+| Prefix      | Use case              |
+|-------------|-----------------------|
+| `feature/`  | New features          |
+| `fix/`      | Bug fixes             |
+| `refactor/` | Code improvements     |
+| `docs/`     | Documentation changes |
+| `chore/`    | Maintenance tasks     |
+
+### Tests and Commits
+
+- Write tests for every change. Bug fixes should include a test that reproduces the issue.
+- Write clear commit messages that explain *why* the change was made, not just *what* changed.
+- Keep commits atomic; each commit should represent one logical change.
+
+## Submitting Your Contribution
+
+1. Fork the repository and clone your fork.
+2. Add the upstream remote: `git remote add upstream https://github.com/mozilla-ai/cq-python.git`
+3. Create a branch from `main` following the naming conventions above.
+4. Make your changes, including tests.
+5. Push your branch to your fork and open a pull request against `main`.
+
+Your PR description should include:
+
+- What changed and why.
+- How to test the change.
+- Links to related issues (use `Fixes #123` or `Closes #456` to auto-close them).
+
+## Review Process
+
+- Expect an initial response within 5 business days.
+- Simple fixes typically take around 1 week to merge; complex features may take 2-3 weeks.
+- Address review comments with new commits rather than force-pushing during review. This makes it easier for reviewers to see incremental changes.
+- Pull requests with no activity for 30 or more days may be closed. You are welcome to reopen or re-submit if you return to the work.
+
+## Your First Contribution
+
+- Look for issues labeled [`good-first-issue`](https://github.com/mozilla-ai/cq-python/labels/good-first-issue) or [`help-wanted`](https://github.com/mozilla-ai/cq-python/labels/help-wanted).
+- Comment on the issue to claim it so others know you are working on it.
+- Ask questions early; maintainers are happy to help.
+- Start small. A well-scoped first PR is easier to review and merge.
+
+## Code of Conduct
+
+This project follows Mozilla's [Community Participation Guidelines](https://www.mozilla.org/about/governance/policies/participation/).
+
+See our full [Code of Conduct](CODE_OF_CONDUCT.md) for details.
+
+## Security
+
+If you discover a security vulnerability, do **not** open a public issue. See [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
+
+## License
+
+By contributing code to this project, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE), the same license that covers the project.