feat: RFC-005 Step 9 — PIP request builder types

[beonde]

Summary

RFC-005 Step 9: Add PIP (PDP Integration Profile) request builder types for SDK consumers building custom PEP integrations.

What's New

New file capiscio_sdk/pip.py with:

Request Types (RFC-005 §5)

• PIPRequest — top-level decision request container
• SubjectAttributes — agent identity (DID, badge_jti, IAL, trust_level)
• ActionAttributes — operation + capability_class (null in badge-only mode)
• ResourceAttributes — target resource identifier
• ContextAttributes — txn_id, enforcement_mode, envelope fields (null until RFC-008)
• EnvironmentAttributes — workspace, pep_id, timestamp

Response Types (RFC-005 §6)

• PIPResponse — decision, decision_id, obligations, reason, TTL
• Obligation — type + params with from_dict()/to_dict() roundtrip

Enforcement Mode

• EnforcementMode enum: OBSERVE, GUARD, DELEGATE, STRICT
• stricter_than() comparison following RFC-008 §10.5 total order
• from_env() reads CAPISCIO_ENFORCEMENT_MODE (defaults to OBSERVE)

Constants

• PIP_VERSION = "capiscio.pip.v1"
• DECISION_ALLOW, DECISION_DENY, DECISION_OBSERVE

Design Decisions

• Dataclasses (not Pydantic) — matches the pattern in badge.py, connect.py
• Envelope fields serialize as JSON null, not absent — per RFC-005 §5.1
• txn_id auto-populated as UUID v7 (Python 3.14+) with UUID v4 fallback
• Thin data layer only — no business logic, no PDP client, no enforcement
• Obligation.params validated as dict in from_dict() (non-dict dropped to None)

Tests

44 unit tests covering:

• Constants and version values
• EnforcementMode: all 4 values, ordering, from_env (default, valid, invalid, empty)
• All attribute types: to_dict serialization, defaults
• PIPRequest: auto-population of txn_id and time, preservation of explicit values, idempotency, full roundtrip
• Obligation: to_dict, from_dict, invalid params type handling
• PIPResponse: is_allow/is_deny, to_dict, from_dict, roundtrip, non-dict obligation filtering

Full unit suite: 392 pass, 10 pre-existing failures (unrelated modules).

RFC Reference

capiscio-rfcs/docs/005-policy-definition-distribution-enforcement.md §5, §6, §7.1

Implementation guide: internal-docs/engineering/rfc005-pip-implementation-guide.md v1.5, Step 9

[github-actions]

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

[github-actions]

✅ All checks passed! Ready for review.

[Copilot]

Pull request overview

Adds RFC-005 “PDP Integration Profile” (PIP) request/response builder types to the Python SDK so SDK consumers can construct decision requests and interpret PDP responses without pulling in enforcement/client logic.

Changes:

• Introduces capiscio_sdk/pip.py with dataclass-based PIP request/response types, constants, and EnforcementMode helpers.
• Re-exports the new PIP types/constants from capiscio_sdk/__init__.py for top-level SDK consumption.
• Adds a comprehensive unit test suite for serialization, env parsing, ordering, and roundtrips.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
capiscio_sdk/pip.py	New PIP dataclasses/constants and EnforcementMode utilities for RFC-005 requests/responses.
capiscio_sdk/init.py	Re-exports PIP types/constants as part of the public SDK surface.
tests/unit/test_pip.py	Unit tests validating PIP serialization/roundtrip behavior and enforcement mode parsing/order.

[github-actions]

✅ SDK server contract tests passed (test_server_integration.py). Cross-product scenarios are validated in capiscio-e2e-tests.

[github-actions]

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

[github-actions]

✅ All checks passed! Ready for review.

[github-actions]

✅ SDK server contract tests passed (test_server_integration.py). Cross-product scenarios are validated in capiscio-e2e-tests.

[codecov]

Codecov Report

❌ Patch coverage is 99.26471% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
capiscio_sdk/pip.py	99.25%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!