capiscio-sdk 0.2.0__tar.gz

capiscio_sdk-0.2.0/.github/markdown-link-check-config.json

@@ -0,0 +1,6 @@
+{
+  "retryOn429": true,
+  "retryCount": 5,
+  "fallbackRetryDelay": "30s",
+  "aliveStatusCodes": [200, 429]
+}

capiscio_sdk-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Documentation Validation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  # Build and validate documentation (no deployment)
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install mkdocs-material \
+                      "mkdocstrings[python]>=0.24" \
+                      mkdocs-git-revision-date-localized-plugin
+      
+      - name: Validate documentation build
+        run: mkdocs build --strict
+      
+      - name: Check for broken links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          folder-path: 'docs'
+          config-file: '.github/markdown-link-check-config.json'
+        continue-on-error: true
+      
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-build
+          path: site/
+          retention-days: 7
+      
+      - name: Add success comment
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '✅ Documentation validation passed!\n\n> Unified docs will be deployed from [capiscio-docs](https://github.com/capiscio/capiscio-docs) repo.'
+            })
+

capiscio_sdk-0.2.0/.github/workflows/pr-checks.yml

@@ -0,0 +1,192 @@
+name: PR Checks
+
+on:
+  pull_request:
+    branches:
+      - main
+      - develop
+  push:
+    branches:
+      - main
+      - develop
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      
+      - name: Run linting (ruff)
+        run: |
+          ruff check .
+        continue-on-error: true
+      
+      - name: Run type checking (mypy)
+        run: |
+          mypy capiscio_sdk
+        continue-on-error: true
+      
+      - name: Run unit tests
+        run: |
+          pytest tests/unit/ -v --tb=short --cov=capiscio_sdk --cov-report=xml --cov-report=term
+      
+      - name: Run integration tests
+        run: |
+          pytest tests/integration/ -v --tb=short
+      
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+  
+  security-scan:
+    name: Security Scan
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      
+      - name: Run safety check
+        run: |
+          safety check --json || true
+        continue-on-error: true
+      
+      - name: Run bandit security scan
+        run: |
+          bandit -r capiscio_sdk -f json -o bandit-report.json || true
+        continue-on-error: true
+      
+      - name: Upload bandit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bandit-report
+          path: bandit-report.json
+  
+  build-check:
+    name: Build Check
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Check package with twine
+        run: python -m twine check dist/*
+      
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  
+  docs-check:
+    name: Documentation Check
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install mkdocs-material "mkdocstrings[python]>=0.24"
+      
+      - name: Build documentation
+        run: mkdocs build --strict
+      
+      - name: Check for broken links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          folder-path: 'docs'
+          config-file: '.github/markdown-link-check-config.json'
+        continue-on-error: true
+  
+  all-checks-passed:
+    name: All Checks Passed
+    needs: [test, security-scan, build-check, docs-check]
+    runs-on: ubuntu-latest
+    if: always()
+    
+    steps:
+      - name: Check if all jobs passed
+        run: |
+          if [ "${{ needs.test.result }}" != "success" ] || \
+             [ "${{ needs.build-check.result }}" != "success" ] || \
+             [ "${{ needs.docs-check.result }}" != "success" ]; then
+            echo "Some required checks failed"
+            exit 1
+          fi
+          echo "All required checks passed!"
+      
+      - name: Add PR comment
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '✅ All checks passed! Ready for review.'
+            })

capiscio_sdk-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,117 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'  # Trigger on version tags like v0.1.0, v1.0.0, etc.
+
+jobs:
+  # Run full test suite before publishing
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      
+      - name: Run tests
+        run: |
+          pytest tests/ -v --tb=short
+  
+  build-and-publish:
+    needs: test  # Only publish if tests pass
+    runs-on: ubuntu-latest
+    
+    permissions:
+      contents: write  # For creating release
+      id-token: write  # Required for trusted publishing
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for changelog
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+      
+      - name: Extract version from tag
+        id: get_version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
+          echo "Publishing version: $VERSION"
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Check package
+        run: python -m twine check dist/*
+      
+      - name: Publish to PyPI
+        id: pypi-publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Using trusted publishing - no password needed
+          # Configure at https://pypi.org/manage/account/publishing/
+          skip-existing: true
+          verbose: true
+      
+      - name: Create GitHub Release
+        if: success()  # Only create release if PyPI publish succeeded
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          body: |
+            # CapiscIO SDK ${{ steps.get_version.outputs.VERSION }}
+            
+            ## Installation
+            
+            ```bash
+            pip install capiscio-sdk==${{ steps.get_version.outputs.VERSION }}
+            ```
+            
+            Or upgrade:
+            
+            ```bash
+            pip install --upgrade capiscio-sdk
+            ```
+            
+            ## What's Changed
+            
+            See [CHANGELOG.md](https://github.com/capiscio/capiscio-sdk-python/blob/main/CHANGELOG.md) for detailed changes.
+            
+            ## Documentation
+            
+            - [Getting Started](https://docs.capisc.io/sdk-python/getting-started/quickstart/)
+            - [Configuration Guide](https://docs.capisc.io/sdk-python/guides/configuration/)
+            - [API Reference](https://docs.capisc.io/sdk-python/api/)
+            
+            ---
+            
+            **Full Changelog**: https://github.com/capiscio/capiscio-sdk-python/compare/${{ github.event.before }}...${{ github.ref_name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

capiscio_sdk-0.2.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Distribution / packaging
+pip-wheel-metadata/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environment variables
+.env
+.env.local
+
+# Documentation
+docs/_build/
+site/
+

capiscio_sdk-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13.8

capiscio_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-10
+
+### Added
+- **Comprehensive Integration Tests (26 tests)**
+  - Real A2A SDK integration testing with official types
+  - All Part types tested: TextPart, FilePart (bytes/URI), DataPart, mixed parts
+  - Both role values tested: user, agent
+  - Optional fields tested: contextId, taskId, metadata
+  - Edge cases: empty text, long text (10KB), Unicode/special characters
+  - Security patterns: XSS attempts, SQL injection, oversized messages (100+ parts), null bytes
+  - Malformed messages: invalid roles, empty messageId, empty parts array
+  - Coverage: All tests passing in ~1.27 seconds
+
+- **GitHub Actions CI/CD**
+  - `pr-checks.yml`: Comprehensive PR validation (Python 3.10-3.13, linting, type checking, tests, security scanning)
+  - Enhanced `publish.yml`: Now runs full test suite before publishing to PyPI
+  - `docs.yml`: Automated documentation deployment (GitHub Pages, Cloudflare Pages)
+
+- **Foundation Layer**
+  - Core types: `ValidationResult`, `ValidationIssue`, `ValidationSeverity`, `RateLimitInfo`, `CacheEntry`
+  - Error hierarchy: 7 exception classes for different security scenarios
+  - Configuration system with 4 presets: `development()`, `production()`, `strict()`, `from_env()`
+
+- **Validators**
+  - `MessageValidator`: Validates A2A v0.3.0 message structure
+    - Required fields: `messageId` (non-empty string), `role` (enum), `parts` (array)
+    - Optional fields: `contextId`, `taskId`, `metadata`
+    - Supports all Part types: `TextPart`, `FilePart` (FileWithBytes/FileWithUri), `DataPart`
+    - Part validation: kind discriminator ("text"|"file"|"data") with type-specific validation
+  - `ProtocolValidator`: Validates protocol version, headers, and message types
+
+- **Infrastructure**
+  - `ValidationCache`: TTL-based in-memory cache with invalidation support
+  - `RateLimiter`: Token bucket algorithm with per-identifier rate limiting
+  - Configurable cache size and TTL
+
+- **Security Executor**
+  - `CapiscIOSecurityExecutor`: Main wrapper for agent executors
+  - Three integration patterns:
+    - Minimal: `secure(agent)` - one-liner integration
+    - Explicit: `CapiscIOSecurityExecutor(agent, config)` - full control
+    - Decorator: `@secure_agent(config)` - pythonic decorator pattern
+  - Configurable fail modes: `block`, `monitor`, `log`
+  - Request rate limiting with identifier-based buckets
+  - Validation result caching for performance
+
+- **Documentation**
+  - Complete rewrite of all examples to use official A2A SDK types
+  - Updated configuration guide with correct A2A message fields
+  - Comprehensive quickstart with real-world integration examples
+  - API reference documentation
+  - Apache 2.0 license, Contributing guidelines, Security policy
+
+### Technical Details
+- Python 3.10+ support (tested on 3.10, 3.11, 3.12, 3.13)
+- Type hints with `py.typed` marker
+- Pydantic models for validation
+- Token bucket rate limiting algorithm
+- TTL-based caching with LRU eviction
+- Delegate pattern for attribute access
+
+### Test Coverage
+- **Total: 150 tests, 99.3% passing (149 passing, 1 skipped)**
+  - Unit tests: 124 tests (including 14 MessageValidator tests)
+  - Integration tests: 26 tests (all passing)
+  - Skipped: 1 module (test_executor.py - covered by integration tests)
+
+### Release Notes
+This is an **early 0.1.0 release**. While the middleware has comprehensive test coverage (150 tests) and validates all official A2A message structures correctly, it has not yet been battle-tested in production environments. We recommend:
+
+- ✅ **Safe for**: Development environments, testing, evaluation
+- ⚠️ **Use with monitoring**: Staging environments, non-critical production
+- ❌ **Not yet ready for**: Mission-critical production without extensive internal testing
+
+**Planned for v1.0**: Load testing, stress testing, concurrent request testing, performance benchmarking, production hardening based on real-world feedback
+
+### Installation
+```bash
+pip install capiscio-sdk==0.1.0
+```
+
+---
+
+## [Unreleased]
+
+### Planned for v0.2.0
+- Signature verification (crypto validation)
+- Agent card validation
+- Upstream agent testing
+- Integration tests
+- End-to-end tests
+- Performance benchmarks
+
+### Planned for v1.0.0
+- Full A2A v1.0 compliance
+- Production-ready hardening
+- Performance optimizations
+- Comprehensive documentation
+- CI/CD pipeline
+- PyPI release
+
+---
+
+[0.1.0]: https://github.com/capiscio/capiscio-sdk-python/releases/tag/v0.1.0
+