Deeper Strands integration: in-process check_agent_result() API

[bamdadd]

Right now the only entry point is the CLI reading a file off disk (taintline check <path>). For a Strands user the natural gate is in-process: run the agent, get an AgentResult, and check it without serializing to a temp file. Add a small typed public API that turns a Strands AgentResult (or its .traces) directly into a Verdict. This must preserve the core invariant: the check path runs the same deterministic detectors with NO LLM judge, no network, no clock, no RNG.

Acceptance criteria

• A public function (e.g. taintline.check_agent_result(result) -> Verdict) normalizes a Strands AgentResult/traces object through the existing ingest path and calls run_all — reusing, not duplicating, detector logic.
• Typed signature (pydantic types / defined Protocol for the accepted input; no loose dicts), mypy strict clean; Strands is an optional/duck-typed dependency so importing taintline never hard-requires it.
• A convenience that maps a Verdict to a pass/fail against a caller-supplied fail_on set, mirroring CLI --fail-on, so it is usable as a hard gate in a script.
• Documented in the README Strands section with a short domain-neutral example.
• Tests cover a tainted and a clean AgentResult-shaped input and assert deterministic verdicts; no network, no LLM in the path.

[nolanefe]

Hi, I’d like to work on this issue if it is still available.

I’ll first trace the existing CLI check flow, ingest/normalization path, run_all detector execution, Verdict model, and current --fail-on behavior so the new API reuses the same logic rather than introducing a parallel path.

My proposed implementation would:

• add a public check_agent_result(result) -> Verdict entry point for in-process Strands integrations
• normalize AgentResult / traces through the existing ingest path before calling the current deterministic detector pipeline
• keep detector behavior identical to the CLI path, with no LLM judge, network access, clock dependency, or randomness introduced
• use a typed boundary such as a defined Protocol or Pydantic-compatible adapter rather than accepting loose dictionaries
• keep Strands optional and duck-typed so importing taintline does not require installing Strands
• add a small convenience helper that evaluates a Verdict against a caller-provided fail_on set, mirroring the existing CLI --fail-on semantics
• add deterministic tests for both clean and tainted AgentResult-shaped inputs
• test that the API goes through the existing detector/ingest logic rather than duplicating detection behavior
• add a short domain-neutral README example showing how a Strands user can inspect an AgentResult directly in-process
• run the existing typing, lint, and test suite to keep the new public API mypy-strict clean

Before I begin, would you prefer the accepted input boundary to be a small structural Protocol representing only the AgentResult fields Taintline needs, or an explicit adapter/normalization function for Strands-shaped objects so the public check_agent_result() API stays completely independent of Strands types?