README

Evidence-aware risk review guardrails for Laravel applications, AI products, RAG systems, and MCP tools.

This package labels source strength, detects risky claims, keeps LLM calls default-OFF, records review evidence when enabled, and exposes the same core engine through PHP, Artisan, HTTP, and MCP surfaces.

Table Of Contents

• Why It Exists
• What Is Inside
• Quick Start
• PHP Surface
• Artisan Surface
• HTTP Surface
• MCP Surface
• Configuration
• Profiles And Taxonomy
• Review Logs
• Testing
• Architecture
• Security
• Contributing
• License

Why It Exists

LLM answers often look confident before they are well supported. padosoft/laravel-evidence-risk-review gives Laravel teams a deterministic review layer that can run before publishing, storing, streaming, or acting on AI-generated content.

The core idea is simple:

• classify every source into a configured evidence tier
• compare claim assertiveness against required evidence strength
• run cheap deterministic checks first
• call expensive or external LLM review only when explicitly enabled
• return structured findings that adapters can use consistently

What Is Inside

Quick Start

Install the package:

composer require padosoft/laravel-evidence-risk-review

Publish config and the optional database migration:

php artisan vendor:publish --tag=evidence-risk-review-config
php artisan vendor:publish --tag=evidence-risk-review-migrations

Run a dry review from PHP:

use Padosoft\EvidenceRiskReview\Data\ReviewArtifact;
use Padosoft\EvidenceRiskReview\Facades\EvidenceRiskReview;

$result = EvidenceRiskReview::review(new ReviewArtifact(
    artifactId: 'answer-123',
    answerText: 'This likely helps when the documented prerequisites are met.',
));

return $result->toArray();

Run a dry review from the CLI:

php artisan evidence:review artifact.json --dry-run

Enable nothing else until you need it. HTTP, MCP integrations, LLM calls, and persistence are designed to stay opt-in.

PHP Surface

use Padosoft\EvidenceRiskReview\Facades\EvidenceRiskReview;

$arrayResult = EvidenceRiskReview::reviewArray([
    'artifact_id' => 'answer-124',
    'answer_text' => 'This always cures the condition.',
    'claims' => [[
        'id' => 'c1',
        'text' => 'This always cures the condition.',
        'assertiveness' => 'definitive',
        'source_ids' => ['s1'],
    ]],
    'sources' => [[
        'id' => 's1',
        'declared_tier' => 'blog',
    ]],
    'options' => [
        'profile_key' => 'medical',
        'dry_run' => true,
    ],
]);

$tier = EvidenceRiskReview::labelTier([
    'id' => 'source-1',
    'url' => 'https://arxiv.org/abs/1234.5678',
]);

$profiles = EvidenceRiskReview::listProfiles();
$taxonomy = EvidenceRiskReview::taxonomy();

Artisan Surface

php artisan evidence:review artifact.json --dry-run
php artisan evidence:profiles
php artisan evidence:taxonomy
php artisan evidence:log --limit=25

evidence:review exits with:

HTTP Surface

The HTTP API is default-OFF. Enable it explicitly:

'api' => [
    'enabled' => env('EVIDENCE_RISK_REVIEW_API_ENABLED', false),
    'prefix' => env('EVIDENCE_RISK_REVIEW_API_PREFIX', 'evidence-risk-review/api'),
    'middleware' => [],
],

Available endpoints when enabled:

POST /evidence-risk-review/api/reviews
GET  /evidence-risk-review/api/reviews/{review}
GET  /evidence-risk-review/api/profiles
GET  /evidence-risk-review/api/profiles/{key}
GET  /evidence-risk-review/api/taxonomy
GET  /evidence-risk-review/api/openapi.yaml

HTTP errors use a stable envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Expected non-empty string at [artifact_id].",
    "details": {}
  }
}

MCP Surface

The MCP layer is framework-agnostic:

use Padosoft\EvidenceRiskReview\Mcp\McpToolRegistry;

$registry = app(McpToolRegistry::class);

$definitions = array_map(
    static fn ($definition) => $definition->toArray(),
    $registry->definitions(),
);

$result = $registry->handle('evidence_review.assess', [
    'artifact_id' => 'answer-125',
    'answer_text' => 'No claims to check.',
    'options' => ['dry_run' => true],
]);

Available tools:

evidence_review.assess
evidence_review.label_tier
evidence_review.list_profiles

Configuration

The package config is published to config/evidence-risk-review.php.

Important defaults:

See .env.example for the supported environment variables.

Profiles And Taxonomy

Built-in profiles:

• default
• engineering
• medical
• legal
• finance

Evidence tiers are configurable. Built-ins include guideline, peer-reviewed, official, preprint, news, blog, search hint, and unverified.

Profiles decide which risk checks are enabled and what minimum source tier each claim assertiveness level requires.

Review Logs

Supported stores:

• null: default, append is a no-op
• array: useful for tests and in-process inspection
• database: append-only table published through the package migration

Enable database logs:

EVIDENCE_RISK_REVIEW_LOG_STORE=database
EVIDENCE_RISK_REVIEW_LOG_CONNECTION=mysql
EVIDENCE_RISK_REVIEW_LOG_TABLE=evidence_risk_review_logs

Testing

Local gates:

composer validate --strict --no-interaction --no-ansi
vendor/bin/pint --test
vendor/bin/phpstan analyse --memory-limit=512M --no-progress
vendor/bin/phpunit
npx --yes @redocly/cli@latest lint resources/openapi.yaml

Live tests are opt-in and skip unless explicitly enabled:

EVIDENCE_RISK_REVIEW_LIVE=1 vendor/bin/phpunit --testsuite Live

Architecture

The package keeps one core engine and thin adapters:

ReviewArtifact / ReviewOptions
        |
        v
ReviewEngine
        |
        +-- EvidenceTierLabeler
        +-- RiskSweepEngine
        +-- EvidenceReviewerLlmContract
        +-- ReviewLogStore
        |
        v
PHP facade / Artisan / HTTP / MCP

Business rules live in core services and DTOs. Controllers, commands, and MCP handlers adapt input and output only.

Security

• LLM calls are default-OFF.
• HTTP routes are default-OFF.
• Review logging is default-OFF.
• Unknown config values fail loudly.
• The package has no AskMyDocs or host-app namespace dependency.

Report vulnerabilities through the process in SECURITY.md.

Contributing

Read CONTRIBUTING.md, AGENTS.md, CLAUDE.md, docs/RULES.md, and docs/LESSON.md before opening a PR.

The repo includes a Claude/agent/vibe-coding pack under .claude/ and skills/ so future agent sessions inherit the project rules.

License

Apache-2.0. See LICENSE.