diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 109960d3..24c638e4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,31 +17,29 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: ${{ matrix.python-version }} + enable-cache: true - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -e .[dev] + - name: Sync dependencies + run: uv sync --extra dev - name: Lint run: | - ruff --version - ruff check . - black --check . + uv run ruff --version + uv run ruff check . + uv run black --check . - name: Type check run: | - mypy --version - mypy neural + uv run mypy --version + uv run mypy neural - name: Run tests env: KALSHI_EMAIL: ${{ secrets.KALSHI_EMAIL || '' }} KALSHI_PASSWORD: ${{ secrets.KALSHI_PASSWORD || '' }} KALSHI_API_BASE: ${{ secrets.KALSHI_API_BASE || 'https://api.elections.kalshi.com' }} - run: | - pytest -q + run: uv run pytest -q diff --git a/.github/workflows/docs-enhanced.yml b/.github/workflows/docs-enhanced.yml index a246ff12..36c5a268 100644 --- a/.github/workflows/docs-enhanced.yml +++ b/.github/workflows/docs-enhanced.yml @@ -40,7 +40,6 @@ on: type: boolean env: - NODE_VERSION: '18' PYTHON_VERSION: '3.11' jobs: @@ -115,45 +114,29 @@ jobs: needs.detect-changes.outputs.docs-changed == 'true' || needs.detect-changes.outputs.examples-changed == 'true' || needs.detect-changes.outputs.config-changed == 'true' - outputs: - cache-hit: ${{ steps.cache.outputs.cache-hit }} steps: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: ${{ env.PYTHON_VERSION }} - cache: 'pip' - - - name: Set up Node.js - uses: actions/setup-node@v4 - with: - node-version: ${{ env.NODE_VERSION }} + enable-cache: true - - name: Cache Python dependencies - id: cache - uses: actions/cache@v3 + - name: Set up Bun + uses: oven-sh/setup-bun@v2 with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} - restore-keys: | - ${{ runner.os }}-pip- - - - name: Install Python dependencies - run: | - python -m pip install --upgrade pip - pip install -e .[dev,docs] + bun-version: latest - - name: Install Mintlify CLI - run: npm install -g @mintlify/cli + - name: Sync Python dependencies + run: uv sync --extra dev --extra docs - name: Verify installations run: | - python --version - npm --version - mintlify --version + uv --version + bun --version + bunx @mintlify/cli@latest --version # Stage 3: API Documentation Generation generate-api-docs: @@ -171,37 +154,36 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: ${{ env.PYTHON_VERSION }} + enable-cache: true - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -e .[dev,docs] + - name: Sync dependencies + run: uv sync --extra dev --extra docs - name: Generate API docs with mkdocstrings id: generate run: | mkdir -p docs/api - python scripts/generate_api_docs.py + uv run python scripts/generate_api_docs.py echo "generated=true" >> $GITHUB_OUTPUT - name: Generate OpenAPI specifications id: openapi run: | - python scripts/generate_openapi_specs.py + uv run python scripts/generate_openapi_specs.py echo "generated=true" >> $GITHUB_OUTPUT - name: Validate generated API docs run: | if [ -f "scripts/validate_api_docs.py" ]; then - python scripts/validate_api_docs.py + uv run python scripts/validate_api_docs.py else echo "validate_api_docs.py not found; skipping strict API docs validation" if [ -f "scripts/validate_docs.py" ]; then - python scripts/validate_docs.py || echo "validate_docs reported issues; continuing for advisory check" + uv run python scripts/validate_docs.py || echo "validate_docs reported issues; continuing for advisory check" fi fi @@ -228,26 +210,25 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: ${{ env.PYTHON_VERSION }} + enable-cache: true - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -e .[dev,docs] + - name: Sync dependencies + run: uv sync --extra dev --extra docs - name: Generate examples documentation id: generate run: | mkdir -p docs/examples/generated - python scripts/generate_examples_docs.py + uv run python scripts/generate_examples_docs.py echo "generated=true" >> $GITHUB_OUTPUT - name: Validate examples run: | - python scripts/validate_examples.py + uv run python scripts/validate_examples.py - name: Upload examples documentation uses: actions/upload-artifact@v4 @@ -272,15 +253,14 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: ${{ env.PYTHON_VERSION }} + enable-cache: true - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -e .[dev,docs] + - name: Sync dependencies + run: uv sync --extra dev --extra docs - name: Download all generated docs uses: actions/download-artifact@v4 @@ -302,7 +282,7 @@ jobs: - name: Validate documentation structure id: validate run: | - if python scripts/validate_docs.py; then + if uv run python scripts/validate_docs.py; then echo "passed=true" >> $GITHUB_OUTPUT else echo "::warning::validate_docs reported issues; continuing as advisory check" @@ -312,13 +292,13 @@ jobs: - name: Check documentation coverage id: coverage run: | - python scripts/check_docstring_coverage.py > coverage-report.txt + uv run python scripts/check_docstring_coverage.py > coverage-report.txt echo "report=coverage-report.txt" >> $GITHUB_OUTPUT - name: Test code examples run: | if [ -f "scripts/test_doc_examples.py" ]; then - python scripts/test_doc_examples.py || \ + uv run python scripts/test_doc_examples.py || \ echo "::warning::Documentation example tests reported issues; continuing as advisory check" else echo "::notice::scripts/test_doc_examples.py not found; skipping example tests" @@ -327,7 +307,7 @@ jobs: - name: Check links and references run: | if [ -f "scripts/check_documentation_links.py" ]; then - python scripts/check_documentation_links.py || \ + uv run python scripts/check_documentation_links.py || \ echo "::warning::Documentation link checks reported issues; continuing as advisory check" else echo "::notice::scripts/check_documentation_links.py not found; skipping link checks" @@ -355,13 +335,10 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Node.js - uses: actions/setup-node@v4 + - name: Set up Bun + uses: oven-sh/setup-bun@v2 with: - node-version: ${{ env.NODE_VERSION }} - - - name: Install Mintlify CLI - run: npm install -g @mintlify/cli + bun-version: latest - name: Download generated docs uses: actions/download-artifact@v4 @@ -381,7 +358,7 @@ jobs: id: preview run: | # Create preview deployment - mintlify deploy --preview \ + bunx @mintlify/cli@latest deploy --preview \ --team neural-sdk \ --key ${{ secrets.MINTLIFY_API_KEY }} \ --branch ${{ github.head_ref }} \ @@ -446,13 +423,10 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Node.js - uses: actions/setup-node@v4 + - name: Set up Bun + uses: oven-sh/setup-bun@v2 with: - node-version: ${{ env.NODE_VERSION }} - - - name: Install Mintlify CLI - run: npm install -g @mintlify/cli + bun-version: latest - name: Download generated docs uses: actions/download-artifact@v4 @@ -477,7 +451,7 @@ jobs: - name: Validate documentation before deployment run: | # Local validation - mintlify dev --no-open & + bunx @mintlify/cli@latest dev --no-open & DEV_PID=$! sleep 15 @@ -496,7 +470,7 @@ jobs: id: deploy run: | # Deploy to production - mintlify deploy \ + bunx @mintlify/cli@latest deploy \ --team neural-sdk \ --key ${{ secrets.MINTLIFY_API_KEY }} @@ -549,16 +523,25 @@ jobs: needs: deploy-production if: always() && needs.deploy-production.result == 'success' steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up uv + uses: astral-sh/setup-uv@v7 + with: + python-version: ${{ env.PYTHON_VERSION }} + enable-cache: true + - name: Check documentation health run: | # Perform health checks on deployed documentation - python scripts/health_check.py --url https://neural-sdk.mintlify.app + uv run python scripts/health_check.py --url https://neural-sdk.mintlify.app - name: Update metrics run: | # Update documentation metrics and monitoring if [ -f "scripts/update_metrics.py" ]; then - python scripts/update_metrics.py + uv run python scripts/update_metrics.py else echo "update_metrics.py not found; skipping metrics update" fi @@ -587,17 +570,23 @@ jobs: - name: Checkout uses: actions/checkout@v4 + - name: Set up uv + uses: astral-sh/setup-uv@v7 + with: + python-version: ${{ env.PYTHON_VERSION }} + enable-cache: true + - name: Generate release documentation run: | if [ -f "scripts/generate_release_docs.py" ]; then - python scripts/generate_release_docs.py --version ${{ github.event.release.tag_name }} + uv run python scripts/generate_release_docs.py --version ${{ github.event.release.tag_name }} else echo "generate_release_docs.py not found; skipping release docs generation" fi - name: Update changelog run: | - python scripts/update_changelog.py --version ${{ github.event.release.tag_name }} + uv run --with gitpython python scripts/update_changelog.py --version ${{ github.event.release.tag_name }} - name: Commit release documentation run: | diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9aedfe30..663c4ead 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -49,17 +49,16 @@ jobs: - 'README.md' - 'CHANGELOG.md' - - name: Set up Python + - name: Set up uv if: steps.changes.outputs.docs == 'true' - uses: actions/setup-python@v5 + uses: astral-sh/setup-uv@v7 with: python-version: "3.11" + enable-cache: true - - name: Install dependencies + - name: Sync dependencies if: steps.changes.outputs.docs == 'true' - run: | - python -m pip install --upgrade pip - pip install -e .[dev,docs] + run: uv sync --extra dev --extra docs - name: Generate API docs with mkdocstrings if: steps.changes.outputs.docs == 'true' @@ -73,7 +72,7 @@ jobs: if: steps.changes.outputs.docs == 'true' run: | mkdir -p docs/examples/generated - python scripts/generate_examples_docs.py + uv run python scripts/generate_examples_docs.py - name: Validate documentation links if: steps.changes.outputs.docs == 'true' @@ -94,7 +93,7 @@ jobs: if: steps.changes.outputs.docs == 'true' run: | # Check for required sections in documentation - python scripts/validate_docs.py + uv run python scripts/validate_docs.py - name: Upload generated docs if: steps.changes.outputs.docs == 'true' @@ -113,26 +112,25 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: "3.11" + enable-cache: true - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -e .[dev] + - name: Sync dependencies + run: uv sync --extra dev - name: Test examples syntax run: | for example in examples/*.py; do echo "Checking syntax of $example" - python -m py_compile "$example" + uv run python -m py_compile "$example" done - name: Validate example imports run: | - python -c " + uv run python -c " import ast import sys from pathlib import Path @@ -163,8 +161,11 @@ jobs: name: generated-docs path: docs/ - - name: Install Mintlify CLI - run: npm install -g @mintlify/cli + - name: Set up Bun + uses: oven-sh/setup-bun@v2 + + - name: Validate Mintlify CLI availability + run: bunx @mintlify/cli@latest --version - name: Validate Mintlify configuration run: | @@ -178,7 +179,7 @@ jobs: # mintlify dev expects docs.json; run preview only when that layout exists. if [ -f "docs.json" ] || [ -f "docs/docs.json" ]; then - timeout 30s mintlify dev --no-open --port 3000 || \ + timeout 30s bunx @mintlify/cli@latest dev --no-open --port 3000 || \ echo "::warning::Documentation preview failed; continuing as advisory check" else echo "::notice::Skipping mintlify dev preview because docs.json is not present" @@ -208,19 +209,15 @@ jobs: fetch-depth: 0 token: ${{ secrets.GITHUB_TOKEN }} - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: "3.11" - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install gitpython + enable-cache: true - name: Auto-update changelog run: | - python scripts/update_changelog.py + uv run --with gitpython python scripts/update_changelog.py - name: Commit changelog updates run: | diff --git a/.github/workflows/pr-docs.yml b/.github/workflows/pr-docs.yml index ab1a2d67..139deb97 100644 --- a/.github/workflows/pr-docs.yml +++ b/.github/workflows/pr-docs.yml @@ -34,32 +34,31 @@ jobs: readme: - 'README.md' - - name: Set up Python + - name: Set up uv if: steps.changes.outputs.code == 'true' || steps.changes.outputs.examples == 'true' - uses: actions/setup-python@v5 + uses: astral-sh/setup-uv@v7 with: python-version: "3.11" + enable-cache: true - - name: Install dependencies + - name: Sync dependencies if: steps.changes.outputs.code == 'true' || steps.changes.outputs.examples == 'true' - run: | - python -m pip install --upgrade pip - pip install -e .[dev,docs] + run: uv sync --extra dev --extra docs - name: Check for docstring coverage if: steps.changes.outputs.code == 'true' run: | - python scripts/check_docstring_coverage.py + uv run python scripts/check_docstring_coverage.py - name: Validate example documentation if: steps.changes.outputs.examples == 'true' run: | - python scripts/validate_examples.py + uv run python scripts/validate_examples.py - name: Check for API documentation updates if: steps.changes.outputs.code == 'true' run: | - python scripts/validate_docs.py + uv run python scripts/validate_docs.py - name: Comment on PR if: always() diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index 439abf49..454996de 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -18,28 +18,26 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: "3.11" + enable-cache: true - - name: Install pip-audit - run: | - python -m pip install --upgrade pip - pip install -e .[dev] pip-audit + - name: Export dependency graph for audit + run: uv export --extra dev --format requirements-txt -o requirements-dev.txt - name: Run pip-audit id: pip_audit continue-on-error: true - run: | - pip-audit -r requirements-dev.txt -f json -o pip-audit.json + run: uvx pip-audit -r requirements-dev.txt -f json -o pip-audit.json - name: Summarize dependency findings if: always() env: PIP_AUDIT_OUTCOME: ${{ steps.pip_audit.outcome }} run: | - python - <<'PY' + uv run python - <<'PY' import json import os from pathlib import Path @@ -72,7 +70,6 @@ jobs: f.write(f"| {pkg} | {ver} | {vuln} |\n") else: f.write("No known vulnerabilities found.\n") - PY cat pip-audit-summary.md >> "$GITHUB_STEP_SUMMARY" @@ -93,28 +90,23 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v7 with: python-version: "3.11" - - - name: Install Bandit - run: | - python -m pip install --upgrade pip - pip install bandit + enable-cache: true - name: Run Bandit id: bandit continue-on-error: true - run: | - bandit -q -r neural -f json -o bandit.json + run: uvx --from bandit bandit -q -r neural -f json -o bandit.json - name: Summarize Bandit findings if: always() env: BANDIT_OUTCOME: ${{ steps.bandit.outcome }} run: | - python - <<'PY' + uv run python - <<'PY' import json import os from pathlib import Path diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d8d524ea..265a461e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,435 +1,107 @@ # Contributing to Neural SDK -This document provides guidelines and instructions for contributing to Neural SDK. +This document provides the default contributor workflow for Neural SDK. -## Table of Contents - -- [Code of Conduct](#code-of-conduct) -- [Getting Started](#getting-started) -- [Development Setup](#development-setup) -- [Making Changes](#making-changes) -- [Pull Request Process](#pull-request-process) -- [Code Standards](#code-standards) -- [Testing Guidelines](#testing-guidelines) -- [Documentation](#documentation) - -## Code of Conduct - -This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to contributors@neural-sdk.dev. - -## Getting Started - -### Prerequisites +## Prerequisites - Python 3.10 or higher - Git -- A Kalshi API account (for testing) - -### Development Setup - -1. **Fork the repository** on GitHub - -2. **Clone your fork**: - ```bash - git clone https://github.com/YOUR_USERNAME/neural.git - cd neural - ``` - -3. **Add upstream remote**: - ```bash - git remote add upstream https://github.com/IntelIP/Neural.git - ``` - -4. **Create virtual environment**: - ```bash - python -m venv venv - source venv/bin/activate # On Windows: venv\Scripts\activate - ``` - -5. **Install development dependencies**: - ```bash - pip install -e ".[dev]" - ``` - -6. **Set up pre-commit hooks** (optional but recommended): - ```bash - pip install pre-commit - pre-commit install - ``` - -## Making Changes - -### Branch Naming Convention +- `uv` +- A Kalshi API account when you need to exercise live-backed integrations -Create a descriptive branch for your work: +## Development Setup -- `feature/your-feature-name` - New features -- `fix/bug-description` - Bug fixes -- `docs/what-you-document` - Documentation updates -- `refactor/what-you-refactor` - Code refactoring -- `test/what-you-test` - Adding or updating tests - -Example: ```bash -git checkout -b feature/add-sentiment-strategy -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - - - -