git commit -m "Release v0.1.2 with Double-X trust reporting and CLI formatter"

Author: Vbj1808

CHANGELOG.md

@@ -5,11 +5,67 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.1] - 2026-03-28
+## [0.1.2]
+
+### Added
+
+- **CLI trust report** - `dokis audit sample_audit.json` now renders a
+  screenshot-friendly terminal report that highlights:
+  - allowed vs blocked sources
+  - human-readable blocked-source reasons
+  - supported vs unsupported claim verdicts
+  - `policy_issues`
+  - `enforcement_mode` and `enforcement_verdict`
+  - final compliance status
+
+- **Structured trust result** - Dokis now returns a richer per-response
+  provenance report aimed at runtime trust enforcement, not only a compliance
+  score. `ProvenanceResult` now includes:
+  - `blocked_source_details` with structured `BlockedSource` entries
+  - `claim_verdicts` with compact per-claim reporting
+  - `policy_issues` summarising whether blocked sources and/or unsupported
+    claims were present
+  - `has_blocked_sources` and `has_unsupported_claims`
+  - `enforcement_mode`, `enforcement_verdict`, and `raised_on_violation`
+
+- **Explicit enforcement modes** - `Config` now supports
+  `enforcement_mode="audit" | "guardrail" | "enforce"`.
+  - `audit` always returns a result
+  - `guardrail` returns a result and marks trust failure in the result
+  - `enforce` fails closed by raising `ComplianceViolation`
+
+- **Structured blocked-source classification** - `DomainEnforcer.inspect()`
+  returns `BlockedSource` records with a `reason` field:
+  - `domain_not_allowlisted`
+  - `malformed_source_url`
+  - `missing_source_url`
+
+- **Top-level exports for new report models** - `dokis.BlockedSource` and
+  `dokis.ClaimVerdict` are now part of the public package surface.
+
+
+### Changed
+
+- **Legacy fail-closed config remains supported** - `fail_on_violation` is now
+  treated as a backwards-compatible alias for `enforcement_mode="enforce"`.
+  If both are provided, `enforcement_mode` wins.
+
+- **Async wrappers are documented honestly** - `aaudit()` and `afilter()`
+  remain awaitable wrappers around the synchronous pipeline. They are
+  convenient for async call sites, but they do not offload matching work from
+  the event loop.
+
+- **ComplianceViolation messaging** now includes both the final
+  `enforcement_verdict` and the compact `policy_issues` summary.
+
+- **README and example config** now reflect the modern `enforcement_mode`
+  interface and the richer result object.
 
 ### Fixed
-- Use absolute asset URLs for PyPI README rendering
-- Force Python badge cache refresh
+
+- **BM25 progress noise suppressed** - BM25 tokenization, indexing, and
+  retrieval now pass `show_progress=False` so runtime audits and tests stay
+  quiet by default.
 
 ## [0.1.0] - 2026-03-25
 

README.md

@@ -24,19 +24,19 @@ Existing tools don't solve this at runtime:
 - **LLM guardrails** handle safety and policy enforcement well - toxicity, jailbreaks, off-topic content. Their provenance validators strip unsupported sentences but don't return a structured claim→URL map, a compliance rate, or a source allowlist.
 - **Prompt engineering** reduces the problem. It doesn't eliminate it.
 
-Dokis sits inline - between your retriever and your LLM response going out - and enforces provenance in real time.
+Dokis sits inline between retrieval and response delivery and returns a runtime trust report for the exact answer your system is about to ship. It acts as a provenance and enforcement boundary in real time.
 
 ---
 
 ## How it works
 
-Dokis does exactly two things:
+Dokis does two things in one deterministic runtime pass:
 
 **1. Pre-retrieval enforcement.** Strip chunks whose source URL is not on your allowlist before they enter the prompt.
 
-**2. Post-generation auditing.** Split the response into atomic claim sentences. Match each claim to the chunk it came from using BM25 lexical scoring. Build a `claim → chunk → URL` provenance map. Compute a compliance rate. Flag anything below your threshold.
+**2. Post-generation auditing.** Split the response into atomic claim sentences. Match each claim to the best supporting chunk using BM25 lexical scoring by default. Build a `claim → chunk → URL` provenance map. Compute a compliance rate. Return blocked-source details, claim-level verdicts, policy issues, and a final enforcement verdict.
 
-No LLM call. No API key. No network request after startup. Deterministic output.
+No LLM call or API key is required for the default BM25 path. Output is deterministic for identical inputs and config.
 
 <div align="center">
 
@@ -51,7 +51,7 @@ No LLM call. No API key. No network request after startup. Deterministic output.
 
 <div align="center">
 
-![Dokis CLI demo](https://raw.githubusercontent.com/Vbj1808/dokis/main/assets/demo.gif)
+![Dokis CLI demo](https://raw.githubusercontent.com/Vbj1808/dokis/main/assets/demo.png)
 
 </div>
 
@@ -70,8 +70,26 @@ print(result.compliance_rate)   # 0.91
 print(result.passed)            # True
 print(result.provenance_map)    # {"Aspirin inhibits...": "https://pubmed.com/1"}
 print(result.violations)        # claims with no source
+print(result.claim_verdicts)    # explicit supported / unsupported report
+print(result.policy_issues)     # [] | ["blocked_sources"] | ...
+print(result.enforcement_mode)  # "guardrail"
+print(result.enforcement_verdict)  # "passed"
 ```
 
+### CLI trust report
+
+```bash
+dokis audit sample_audit.json
+```
+
+The CLI reads a JSON file containing `query`, `chunks`, and `response`. If a
+`provenance.toml` file is present in the current directory or beside the input
+file, Dokis loads it automatically so the report reflects your real allowlist,
+threshold, matcher, and enforcement mode. Use `--config path/to/file.toml` to
+override that discovery. Use `--no-color` for plain output. Exit code is `0`
+when the audit passes, `1` when it fails policy/compliance checks, and `2`
+for CLI/input errors.
+
 ### With config
 
 ```python
@@ -81,6 +99,7 @@ config = dokis.Config(
     allowed_domains   = ["pubmed.ncbi.nlm.nih.gov", "cochrane.org"],
     min_citation_rate = 0.85,
     claim_threshold   = 0.3,
+    enforcement_mode  = "guardrail",
 )
 
 clean_chunks = dokis.filter(raw_chunks, config)
@@ -122,9 +141,10 @@ result   = response.metadata["provenance"]
 ```bash
 dokis audit input.json
 dokis audit input.json --config provenance.toml
-cat input.json | dokis audit -
 ```
 
+`dokis audit` currently expects a file path. Stdin piping is not supported.
+
 ### Reusable middleware (production pattern)
 
 ```python
@@ -135,6 +155,7 @@ mw = ProvenanceMiddleware(Config(
     min_citation_rate = 0.85,
     matcher           = "bm25",
     claim_threshold   = 0.3,
+    enforcement_mode  = "guardrail",
 ))
 
 result = mw.audit(query, chunks, response)
@@ -170,11 +191,15 @@ dokis.Config(
     extractor         = "regex",        # "regex" | "nltk" | "llm"
     matcher           = "bm25",         # "bm25" | "semantic"
     model             = "all-MiniLM-L6-v2",
-    fail_on_violation = False,
+    enforcement_mode  = "guardrail",    # "audit" | "guardrail" | "enforce"
     domain            = None,
 )
 ```
 
+`fail_on_violation` still works as a backwards-compatible alias for
+`enforcement_mode="enforce"`, but `enforcement_mode` is the recommended
+interface for new configs and examples.
+
 **`claim_threshold` by matcher:**
 - `matcher="bm25"`: normalised per-query BM25 score. Recommended: `0.3–0.5`.
 - `matcher="semantic"`: cosine similarity. Recommended: `0.65–0.85`.
@@ -193,18 +218,36 @@ config = dokis.Config.from_yaml("provenance.toml")
 ```python
 result.compliance_rate   # float
 result.passed            # bool
-result.violations        # list[Claim]
-result.provenance_map    # dict[claim_text, source_url]
-result.blocked_sources   # list[str]
-result.claims            # list[Claim]
+result.violations        # list[Claim] (derived unsupported claims)
+result.provenance_map    # dict[claim_text, source_url] (derived supported claims)
+result.blocked_sources   # list[str] (backwards-compatible)
+result.blocked_source_details  # list[BlockedSource]
+result.claim_verdicts    # list[ClaimVerdict]
+result.policy_issues     # ["blocked_sources", "unsupported_claims"]
+result.has_blocked_sources     # bool
+result.has_unsupported_claims  # bool
+result.enforcement_mode        # "audit" | "guardrail" | "enforce"
+result.enforcement_verdict     # "passed" | "..._failed" | "enforce_raised"
+result.raised_on_violation     # bool
+result.claims            # list[Claim] (full per-claim audit records)
 
 claim.text               # str
 claim.supported          # bool
 claim.confidence         # float - always set, even when False
 claim.source_url         # str | None
 claim.source_chunk       # Chunk | None
 
-record = result.model_dump_json()  # fully JSON-serialisable
+blocked.url              # str
+blocked.domain           # str | None
+blocked.reason           # "domain_not_allowlisted" | "malformed_source_url" | "missing_source_url"
+
+verdict.claim_text       # str
+verdict.verdict          # "supported" | "unsupported"
+verdict.confidence       # float
+verdict.supporting_url   # str | None
+verdict.note             # str | None
+
+record = result.model_dump_json()  # fully JSON-serialisable trust report
 ```
 
 ---

assets/demo.png

@@ -11,7 +11,7 @@
     result = dokis.audit(query, chunks, response)
 
     # With config
-    config = dokis.Config.from_yaml("provenance.yaml")
+    config = dokis.Config.from_yaml("provenance.toml")
     clean_chunks = dokis.filter(raw_chunks, config)
     result = dokis.audit(query, clean_chunks, response, config=config)
 
@@ -26,7 +26,13 @@
 from dokis.config import Config
 from dokis.exceptions import ComplianceViolation, DomainViolation
 from dokis.middleware import ProvenanceMiddleware
-from dokis.models import Chunk, Claim, ProvenanceResult
+from dokis.models import (
+    BlockedSource,
+    Chunk,
+    Claim,
+    ClaimVerdict,
+    ProvenanceResult,
+)
 
 # Module-level default configuration set via configure().
 _default_config: Config | None = None
@@ -160,11 +166,13 @@ def audit(
     "Config",
     "Chunk",
     "Claim",
+    "BlockedSource",
+    "ClaimVerdict",
     "ProvenanceResult",
     "ProvenanceMiddleware",
     "ComplianceViolation",
     "DomainViolation",
 ]
 
 # Version
-__version__ = "0.1.1"
+__version__ = "0.1.2"

dokis/__init__.py

@@ -0,0 +1,8 @@
+"""Module entrypoint for ``python -m dokis``."""
+
+from __future__ import annotations
+
+from dokis.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dokis/__main__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Any
+from typing import Any, cast
 
 try:
     from langchain_core.callbacks import CallbackManagerForRetrieverRun
@@ -20,8 +20,8 @@
 
 logger = logging.getLogger(__name__)
 
-
-class ProvenanceRetriever(BaseRetriever):  # type: ignore[misc]
+ 
+class ProvenanceRetriever(BaseRetriever): 
     """LangChain retriever that enforces source provenance via DomainEnforcer.
 
     Wraps any existing LangChain ``BaseRetriever`` and filters its results
@@ -60,7 +60,8 @@ def __init__(
         url_metadata_key: str = "source",
         **kwargs: Any,
     ) -> None:
-        super().__init__(
+        super_init = cast(Any, super().__init__)
+        super_init(
             base_retriever=base_retriever,
             config=config or Config(),
             url_metadata_key=url_metadata_key,

dokis/adapters/langchain.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import logging
-from typing import Any
 
 try:
     from llama_index.core.base.base_query_engine import BaseQueryEngine
@@ -81,7 +80,7 @@ def query(self, query: str) -> RESPONSE_TYPE:
             ``metadata["provenance"]`` populated as a
             :class:`~dokis.models.ProvenanceResult`.
         """
-        response: Any = self._base_engine.query(query)
+        response = self._base_engine.query(query)
         result = self._middleware.audit(
             query=query,
             chunks=self._chunks,