gawrys/counterparty-ai

Optional AI-assisted risk research subsystem for counterparty-verification. Advisory only; never decides hard pass/fail.

v0.1.1 2026-06-27 11:40 UTC

Requires

• php: >=8.2
• gawrys/counterparty-core: ^0.1
• psr/log: ^2.0 || ^3.0
• psr/simple-cache: ^2.0 || ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• nyholm/psr7: ^1.8
• php-http/mock-client: ^1.6
• phpstan/phpstan: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^11.0
• psalm/plugin-phpunit: ^0.19
• vimeo/psalm: ^6.0

MIT

• Igor Gawrys

• research
• risk
• ai
• llm
• due-diligence

README

Optional AI-assisted risk research for the Counterparty Verification toolkit. It plugs into the same RiskStrategy seam as the rule-based default and adds qualitative, advisory context using an LLM with native tool use.

⚠️ The AI never decides hard pass/fail. It consumes the finished verification report as ground truth, grounds every claim in a tool's source URL (no source → inconclusive), and forces human review below a confidence threshold. Output is advisory only.

A separate package on purpose: prompts change often and must not bump the core's version.

Features

• AiRiskStrategy - a drop-in RiskStrategy; PSR-16 cached by counterparty + report + prompt version to bound cost.
• Native tool use (function calling) - the model invokes registry_lookup, web_search and verification_report; the provider executes them and feeds results back, looping until the findings JSON is returned.
• Two reference providers over PSR-18, no SDK - AnthropicResearchProvider, OpenAiResearchProvider. Adding another LLM is one AbstractAiResearchProvider subclass.
• Structured output, validated - force JSON, parse, validate, retry; malformed output is never trusted.
• Deterministic test kit - FakeAiResearchProvider, recorded cassettes and an in-memory PSR-16 cache, so tests run offline.

Installation

composer require gawrys/counterparty-ai

Usage

use Gawrys\Counterparty\Ai\AiRiskStrategy;
use Gawrys\Counterparty\Ai\Prompt\RiskPromptBuilder;
use Gawrys\Counterparty\Ai\Research\AnthropicResearchProvider; // or OpenAiResearchProvider
use Gawrys\Counterparty\Ai\Tool\{RegistryTool, ReportLookupTool};

$strategy = new AiRiskStrategy(
    provider: new AnthropicResearchProvider($http, $apiKey),
    promptBuilder: new RiskPromptBuilder(),
    tools: [new RegistryTool($registries), new ReportLookupTool()],
    cache: $psr16Cache,
    reviewThreshold: 0.6,
);

$verifier = new Verifier($checks, $strategy, $clock);

Switching LLM is a one-line change (OpenAiResearchProvider), or implement AbstractAiResearchProvider::complete() for any other backend. Removing this package never breaks the rule-based default - the core has no dependency on it.

See the documentation for prompts, grounding rules and writing custom tools.

Testing

composer check

Changelog

See CHANGELOG.md.

Contributing & Security

Pull requests welcome. Report security issues privately - see SECURITY.md.

Credits

• Igor Gawrys

License

The MIT License (MIT). See LICENSE.