feat: add support triage consumer contract

[Deathcharge]

Summary\n- add a bounded, privacy-first support-ticket triage reference consumer using the public Responses API adapter\n- reject malformed or unexpected model tool output before application use\n- discard model-written summaries and return a deterministic local queue/urgency label\n- document authentication, privacy, limits, compatibility, ownership, live conformance, and rollback boundaries\n- add deterministic HTTP, credential, privacy-adversarial, and negative contract coverage\n\n## Verification\n- python -m ruff format --check .\n- python -m ruff check .\n- python -m mypy unified_llm tests examples\n- python -m pytest (130 passed)\n- python -m build --no-isolation\n- python -m twine check dist/*\n- wheel smoke-installed and imported from an isolated virtual environment\n- hosted CI green on Python 3.10, 3.11, 3.12, and 3.13; packaging jobs green\n\n## Review resolution\nCommit 95a35a addresses all four automated findings: deterministic summary privacy, typed missing-key failure, accurate external-adoption status, and explicit POST contract assertion.\n\n## Release boundary\nThis proves the repository-level consumer contract. It does not claim a live deployment or external Samsarix adoption; those remain explicit publication gates.

[coderabbitai]

Summary by CodeRabbit

• New Features

  • Added a runnable support-ticket triage example using a strict routing schema.
  • Added validated triage results with queue, urgency, summary, and provider metadata.
  • Added privacy-conscious configuration and credential handling.

• Documentation

  • Documented the consumer contract, safety requirements, compatibility, verification, and rollback guidance.
  • Linked the support-triage example from the README and changelog.
  • Updated the roadmap with adoption and live-validation milestones.

• Tests

  • Added coverage for request construction, tool-call parsing, validation, metadata, credentials, and public API usage.

Walkthrough

Adds a support-ticket triage reference consumer with a strict function schema, bounded client settings, validated model output, provider metadata, contract documentation, and deterministic public-API tests.

Changes

Support triage consumer

Layer / File(s)	Summary
Triage contract and documentation examples/support_triage.py, examples/__init__.py, docs/CONSUMER_CONTRACT.md, README.md, CHANGELOG.md, ROADMAP.md	Defines the routing schema and immutable TriageDecision result. Documents the public contract, validation rules, lifecycle, verification, ownership, compatibility, and rollback details.
Bounded triage execution examples/support_triage.py	Configures the OpenAI Responses client with bounded settings. Validates ticket input, tool-call count, JSON shape, enums, summary content, and response metadata. Adds the asynchronous entry point.
Public contract verification tests/test_consumer_contract.py	Tests public imports, request construction, successful parsing, metadata propagation, credential handling, and malformed response rejection.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant triage_ticket
  participant UnifiedLLM
  participant OpenAIResponsesProvider
  User->>triage_ticket: ticket text
  triage_ticket->>UnifiedLLM: create completion request
  UnifiedLLM->>OpenAIResponsesProvider: send bounded Responses request
  OpenAIResponsesProvider-->>UnifiedLLM: one route_support_ticket call
  UnifiedLLM-->>triage_ticket: tool-call response and metadata
  triage_ticket-->>User: validated TriageDecision

Loading

Possibly related PRs

• Deathcharge/unified-llm#3: Introduced response, tool-call, and request bounds used by the consumer.
• Deathcharge/unified-llm#4: Introduced the OpenAIResponsesProvider and UnifiedLLM APIs used by the consumer and tests.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding a support-triage consumer contract.
Description check	✅ Passed	The description directly explains the support-triage consumer, validation, documentation, testing, and release boundaries.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/support-triage-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/support_triage.py`:
- Around line 73-75: Enforce the privacy boundary in the support-ticket triage
flow before constructing and printing TriageDecision: do not trust the
model-provided summary from the classification response. Replace it with locally
generated templated text or pass it through an approved deterministic redaction
policy, while preserving the existing structure and length validation; add an
adversarial test covering a secret-like summary value.
- Line 117: Update the client setup around build_client to read OPENAI_API_KEY
with os.getenv instead of direct environment indexing, then raise
ConfigurationError when the key is absent before constructing the provider. Add
a CLI-path test covering an unset OPENAI_API_KEY and asserting the typed
configuration error.

In `@ROADMAP.md`:
- Around line 20-21: Update the current disposition in ROADMAP.md to explicitly
state that no external canonical consumer has adopted the contract, resolving
the conflict between the product-integration statement and the repository-only
evidence boundary. Preserve the existing repository evidence and future adoption
guidance.

In `@tests/test_consumer_contract.py`:
- Around line 18-21: Update the handler in the consumer contract test to record
request.method alongside the existing URL, authorization, and payload fields,
then assert the recorded method is "POST" in the relevant test assertions.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3c94ed68-52cc-486d-a104-7002636a2706

📥 Commits

Reviewing files that changed from the base of the PR and between 402b9f7 and d9f0bcd.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• ROADMAP.md
• docs/CONSUMER_CONTRACT.md
• examples/__init__.py
• examples/support_triage.py
• tests/test_consumer_contract.py