qiro-analyzer 0.1.0

Structured environmental marketing claim risk-review pipeline.

Qiro Analyzer

Qiro Analyzer is a standalone Python package and CLI for environmental marketing-claim risk review. This v0.1 developer preview focuses on EU EmpCo review flow:

1. Step 1 — extract textual, visual, and holistic environmental marketing signals.
2. Step 1.5 — apply deterministic grouping/protection so explicit claims are not hidden by broad holistic findings.
3. Step 2 — assess potential regulatory risk under the EmpCo EU regulation pack.

Outputs are structured JSON or Markdown risk-review findings. They are not legal advice and do not determine whether a claim is unlawful.

Scope for v0.1

Supported inputs:

• Text files: .txt, .md
• Images: .png, .jpg, .jpeg, .webp, .gif
• Batch folders containing the above

Not in scope for this repository/release:

• PDF input. PDF text extraction is future work unless implemented and tested locally.
• Step 3 evidence/RAG/substantiation. This lives in the separate qiro-rag repository so evidence ingestion, retrieval, privacy, and substantiation quality can evolve independently.
• SaaS dashboard, billing, teams, hosted audit history, or definitive legal determinations.

Core capabilities

• Text and image analysis with first-class image support.
• Textual, visual, and holistic environmental signal extraction.
• Deterministic Step 1.5 grouping/protection before Step 2.
• EmpCo EU regulation pack with schema-first prompts.
• Per-step model routing from .env + qiro.models.yaml.
• JSON and Markdown risk-review reports with internal model scores stripped.
• Offline deterministic tests through the mock route.
• Folder batch analysis that writes one output per input plus a summary file.

Qiro is conservative by design: it prefers flagging potential issues for human review over missing material environmental-claim risks. This can create false positives, especially for broad nature imagery, generic sustainability language, and claims whose substantiation is not visible in the marketing asset.

Why Qiro is different

Step 1 extraction → Step 1.5 claim grouping/protection → Step 2 assessment → report

• Step 1.5 claim graph/protection. Broad holistic impressions should not bury explicit textual or label-like claims. Qiro inserts a deterministic grouping/protection layer before assessment, then validates folding before report assembly.
• Model routing for efficiency. Use a vision-capable model where extraction needs image understanding, then route assessment/rewrite to a cheaper review model when appropriate. Provider usage is captured as cost_summary.json when available.
• Mock route by design. Public demos, CI, and tests can run offline without API keys, which keeps the developer preview reproducible and reviewable.
• Reliability capsule for model output. Schema-bearing provider calls use bounded normal retries, typed validation metadata, optional repair/consolidation, and fail-closed errors instead of unbounded agentic retries.
• Synthetic adversarial fixtures. Public fixtures are fictional smoke tests for schema health and pipeline behavior, not public accuracy or legal-quality claims.

Quickstart

uv sync --extra dev
printf "100% eco-friendly detergent\n" > sample.txt
uv run qiro analyze sample.txt --format markdown --out report.md
uv run pytest

CLI usage

uv run qiro analyze sample.txt --out analysis.json
uv run qiro analyze tests/fixtures/images/greenglow_detergent.png --out-dir run-output --save-steps
uv run qiro extract tests/fixtures/images/greenglow_detergent.png --out extraction.json
uv run qiro assess extraction.json --pack empco_eu --out assessment.json
uv run qiro report analysis.json --format markdown --out report.md
uv run qiro batch tests/fixtures/images --model-route mock --out-dir batch-output
uv run qiro rules list
uv run qiro config show

When --out-dir is used, Qiro also writes first-class operational artifacts:

cost_summary.json      # provider usage/cost summary when usage is available
model_attempts.json    # bounded attempt/retry/repair metadata when live provider attempts are recorded

Batch mode writes:

batch-output/
  files/<input-name>.analysis.json
  summary.json         # per-file risk, error, recoveryStatus, and modelAttempts
  cost_summary.json

Use --recursive only for folders that contain marketing inputs; Qiro analyzes every supported .txt, .md, and image file it finds, including nested support/evidence notes if they are under the input directory. Use --format markdown to write one Markdown report per input instead.

Documentation

• Architecture
• Pipeline
• Folding and grouping
• Providers and model routing
• Regulation packs
• Schemas
• Roadmap

Model routing

Secrets stay in .env; non-secret routing lives in qiro.models.yaml.

OPENAI_API_KEY=
DEEPSEEK_API_KEY=
QIRO_MODEL_ROUTE=mock

Useful commands:

uv run qiro models list
uv run qiro models show openai_vision_deepseek_review
uv run qiro models use openai_vision_deepseek_review
uv run qiro analyze input.png --model-route openai_vision_deepseek_review

models show is safe to run without provider keys; it reports route metadata and whether each referenced key is currently present. Live analysis with non-mock routes requires the corresponding provider keys.

Important routes:

• mock — offline deterministic route.
• openai_vision_deepseek_review — GPT-4o vision extraction with DeepSeek chat assessment/rewrite.
• openai_all — GPT-4o mini for all steps.
• openai_4o_all — GPT-4o for all steps.
• deepseek_all_text — DeepSeek chat for text-focused runs.

Python API

from qiro_analyzer import QiroAnalyzer
from qiro_analyzer.config import Settings

analyzer = QiroAnalyzer(settings=Settings(model_route="mock"))
report = analyzer.analyze_text("100% eco-friendly detergent", document_name="claim.txt")
print(report.model_dump(by_alias=True))

Limitations

• Outputs are risk-review findings, not legal determinations.
• Live provider behavior depends on model access, quota, and provider quality.
• Public fixtures are synthetic and fictional.
• PDF input is not advertised in v0.1.
• Step 1.5 grouping is deterministic; it detects known anti-overfolding patterns and triggers a Step 2 repair attempt before report assembly fails closed.

Related repositories

• Step 3 evidence/RAG/substantiation: qiro-rag
• End-to-end launch-gate demo: qiro-launch-gate-demo

License

Apache-2.0. See LICENSE and NOTICE.