feat: Contract Testing & Integration Test CI

[saurabhjain1592]

Summary

Implements contract testing and CI integration for the Python SDK, addressing issue #5.

Problem

The SDK experienced three consecutive bug cycles in one week:

• Datetime parsing failures (nanoseconds unhandled)
• Missing authorization headers in generate_plan
• Policy name extraction returning None

Root cause: Test suites relied on mocked responses that didn't reflect actual Agent API structures.

Solution

• Contract Testing Suite - 19 tests validating SDK models against real API response fixtures
• JSON Fixtures - Recorded API responses for health, query, blocked, plan, and policy scenarios
• CI Integration Workflow - GitHub Actions for contract tests, integration tests, and demo validation
• Fixture Infrastructure - load_json_fixture() helper and recording script

Changes

File	Change
tests/test_contract.py	19 contract tests for all response types
tests/fixtures/*.json	6 JSON fixtures from API contract
.github/workflows/integration.yml	CI workflow for integration testing
tests/conftest.py	Fixture loading utilities
scripts/record_fixtures.py	Script to record fixtures from staging
pyproject.toml	Version bump to 0.2.0
CHANGELOG.md	Release notes for 0.2.0

Test Coverage

Contract Tests (19 tests)

• Health response structure validation
• Successful query response parsing
• Blocked query (PII) response parsing
• Plan generation response parsing
• Gateway Mode policy context parsing
• Datetime with nanoseconds handling
• Rate limit info parsing
• Connector list parsing
• Edge cases (empty, minimal, unknown fields)

CI Workflow Jobs

1. contract-tests - Runs on every PR
2. integration-tests - Runs on merge to main (with staging secrets)
3. demo-scripts - Validates all example scripts
4. community-stack-tests - E2E with Docker Agent (manual trigger)

Test Plan

• All 143 existing tests pass
• 19 new contract tests pass
• Demo scripts compile successfully
• Linting passes (ruff check .)
• CI workflow runs successfully

Fixes #5

To resolve the problem, add an explicit permissions section at the root of the workflow file (.github/workflows/integration.yml). This ensures all jobs in the workflow are run with the minimum necessary privileges on the GITHUB_TOKEN. The best practice is to set permissions: { contents: read } unless specific jobs need something else (e.g., writing pull requests or issues). In this workflow, all jobs only need to read code, so adding the following near the top of the file is appropriate:

permissions:
  contents: read

This line should be inserted after the name: Integration Tests and before the on: block (typically at line 2). No further changes are needed, as none of the jobs appear to need broader permissions.

---

To fix the problem, add a permissions key at the root level of the workflow file (just below the name: and before the on: block). This root-level permissions block will apply to all jobs, unless a job-level override is specified. The majority of jobs shown do not perform any actions that require write access, so the minimum permission of contents: read is appropriate, as suggested by CodeQL. This grants read-only access to repository contents, which is sufficient for typical test and validation workflows.

• Add the following block near the top of the file:

  permissions:
    contents: read
  

• This should go after the name: Integration Tests line (line 1) and before the on: block (line 3).
• No extra imports or dependencies are required.

---

To fix this issue, we should add a permissions block to the demo-scripts job in .github/workflows/integration.yml that restricts the GITHUB_TOKEN permissions to the minimum required for the steps listed. Since all the steps only require reading repository contents (for actions/checkout) and do not write to GitHub, the minimal permission of contents: read is sufficient.

This addition should be made at the same indentation level as runs-on (i.e., a job-level key, not inside steps). No additional methods/imports/definitions are needed.

---

The best way to fix the problem is to add a permissions key at the top level of the workflow (recommended), or individually to any jobs that require a unique set of permissions. For this workflow, there is no evidence of any requirement for write access -- the workflow only runs tests and scripts using repository code and secrets. Therefore, the global default permissions: contents: read should be set at the top level, immediately after the name line, to ensure all jobs run with the minimum required permissions, following the principle of least privilege.

Steps:

• Add a line such as permissions: followed by contents: read as mapping to the root level (after the name).
• No further code or import changes are required.

---