feat(ai): add pyoaev support for AI adversarial exposure validation (#295)

[SamuelHassine]

Summary

• Adds ai_request_marker / ai_target_endpoint signature types and a shared deterministic per-inject canary marker helper (pyoaev/signatures/ai_marker.py).
• Adds inject_expectation.ai_expectations_for_source(source_id) to poll agentless DETECTION / PREVENTION expectations for AI defense collectors.
• Adds an AiTargetManager (CRUD for AI Target assets) wired on the client as client.ai_target.
• Adds an ARTIFICIAL_INTELLIGENCE security domain so AI red-team contracts can be bucketed under the AI security domain.

These are the SDK building blocks for the AI adversarial exposure validation domain (AI red-team injector + AI guardrail collector + openaev backend).

Dependency / merge order

Dependency root of the feature. Merge and release before:

• injectors-python: ai-redteam injector
• collectors: ai-guardrail and mitre-atlas collectors

Pairs with the openaev backend endpoints /api/injects/expectations/ai/{sourceId} and /api/ai_targets.

Tests

• test/signatures/test_ai_marker.py: locks the marker prefix, length, hex suffix, determinism, empty-agent default and exact value so the injector and collectors stay byte-for-byte compatible across runs and languages.
• test/apis/ai_target/test_ai_target.py: validates request construction (method / path / payload) for create, get, update and delete against /ai_targets.
• test/signatures/test_ai_signature_types.py: covers the new SignatureTypes values and confirms they are usable by SignatureType.

Notes

• Rebased on main and resolved the pyoaev/signatures/types.py conflict (kept both the new cloud signature types and the AI ones).
• Addressed the Copilot review: ai_expectations_for_source now returns List[Dict[str, Any]] (matching the docstring), the AI expectations path is built with a single f-string, and the three test files above were added.
• The security/snyk (Filigran) check is failing with "You have used your limit of private tests" (Snyk account quota, unrelated to this change). All other checks (CircleCI build / test / linter / formatting, coverage, signed commits, linked issue, PR title) are green.

Closes #295

[Copilot]

Pull request overview

Adds initial SDK primitives for the AI adversarial exposure validation (AI red-team injector + AI defense collector) domain by introducing new signature types, a shared deterministic marker helper, an expectations polling helper for AI collectors, and a new AI Target CRUD manager exposed on the client.

Changes:

• Add AI-related SignatureTypes and a deterministic build_marker() helper for correlating inject executions to AI defense telemetry.
• Add InjectExpectationManager.ai_expectations_for_source(source_id) for polling agentless AI DETECTION/PREVENTION expectations.
• Add AiTargetManager (CRUD for /ai_targets) and wire it onto OpenAEV as client.ai_target.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pyoaev/signatures/types.py	Adds new AI signature enum values used for AI validation correlation.
pyoaev/signatures/ai_marker.py	Introduces deterministic per-inject marker helper shared by injector/collectors.
pyoaev/apis/inject_expectation/inject_expectation.py	Adds API helper to fetch AI-specific expectations for a collector/source.
pyoaev/apis/ai_target.py	Adds new REST manager/object for AI Target assets CRUD.
pyoaev/apis/init.py	Exposes the new AI Target API module via package exports.
pyoaev/client.py	Wires AiTargetManager onto the main OpenAEV client.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

[codecov]

Codecov Report

❌ Patch coverage is 86.95652% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.96%. Comparing base (8283bfe) to head (86147e6).

Files with missing lines	Patch %	Lines
...oaev/apis/inject_expectation/inject_expectation.py	50.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #296      +/-   ##
==========================================
+ Coverage   73.58%   75.96%   +2.38%     
==========================================
  Files          54       56       +2     
  Lines        2404     2426      +22     
==========================================
+ Hits         1769     1843      +74     
+ Misses        635      583      -52     

Flag	Coverage Δ
connectors	75.96% <86.95%> (+2.38%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[SamuelHassine]

Review and fix summary

Reviewed the full changed files (not just the diff) and reconciled the branch with main.

What was done:

• Rebased onto the latest main and resolved the pyoaev/signatures/types.py conflict, keeping both the new cloud signature types from main and the AI ones from this PR. Branch is now MERGEABLE.
• Fixed the return-type / docstring mismatch: ai_expectations_for_source now returns List[Dict[str, Any]] and builds its path with a single f-string.
• Added unit tests for all new primitives: test/signatures/test_ai_marker.py (locks the marker prefix, length, determinism and exact value), test/apis/ai_target/test_ai_target.py (CRUD request construction against /ai_targets), and test/signatures/test_ai_signature_types.py (new SignatureTypes values usable by SignatureType).
• Replied to and resolved all 5 Copilot review threads.

Verification (local): python -m unittest for the new tests passes (11/11), isort --check-only, black --check and flake8 --ignore=E,W are clean.

CI: CircleCI build / test / linter / formatting, codecov, signed commits, linked issue and PR title are all green.

Remaining (non-code blockers):

• security/snyk (Filigran) fails with "You have used your limit of private tests" - this is a Snyk account quota issue, unrelated to this change.
• 1 approving review is still required to merge; as the PR author I cannot self-approve, so a maintainer approval is the last step.