Metadata-Version: 2.4
Name: qiro-analyzer
Version: 0.1.0
Summary: Structured environmental marketing claim risk-review pipeline.
Project-URL: Homepage, https://github.com/PPDEGRET/EMPCOAnalyzer
Project-URL: Repository, https://github.com/PPDEGRET/EMPCOAnalyzer
Project-URL: Issues, https://github.com/PPDEGRET/EMPCOAnalyzer/issues
Project-URL: Changelog, https://github.com/PPDEGRET/EMPCOAnalyzer/blob/main/CHANGELOG.md
Author: Qiro Analyzer contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: compliance,consumer-protection,environmental-claims,greenwashing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](https://github.com/PPDEGRET/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

```text
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

```bash
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

```bash
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:

```text
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:

```text
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](docs/architecture.md)
- [Pipeline](docs/pipeline.md)
- [Folding and grouping](docs/folding-and-grouping.md)
- [Providers and model routing](docs/providers.md)
- [Regulation packs](docs/regulation-packs.md)
- [Schemas](docs/schemas.md)
- [Roadmap](docs/roadmap.md)

## Model routing

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

```env
OPENAI_API_KEY=
DEEPSEEK_API_KEY=
QIRO_MODEL_ROUTE=mock
```

Useful commands:

```bash
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

```python
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`](https://github.com/PPDEGRET/qiro-rag)
- End-to-end launch-gate demo: [`qiro-launch-gate-demo`](https://github.com/PPDEGRET/qiro-launch-gate-demo)

## License

Apache-2.0. See `LICENSE` and `NOTICE`.
