Metadata-Version: 2.4
Name: attune-verify
Version: 0.3.0
Summary: Generation fact-checker for the attune-* family. Verifies named entities in LLM output actually exist — imports import, CLI flags are real, links resolve, counts match source.
Author-email: Patrick Roebuck <admin@smartaimemory.com>
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
        Copyright 2026 Smart AI Memory
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
        
Project-URL: Homepage, https://github.com/Smart-AI-Memory/attune-verify
Project-URL: Repository, https://github.com/Smart-AI-Memory/attune-verify
Keywords: verification,fact-checking,hallucination,llm,attune,grounding,faithfulness
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: rag
Requires-Dist: attune-rag>=0.2.0; extra == "rag"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: mutmut>=3.0; extra == "dev"
Dynamic: license-file

# attune-verify

Generation fact-checker for the attune-\* family. Verifies named entities
in LLM-generated content actually exist — imports import, CLI flags are real,
links resolve, counts match source — so hallucinations that pass unit tests
are caught before they reach a reader.

## Install

```bash
pip install attune-verify
```

With the optional LLM semantic layer (requires attune-rag):

```bash
pip install 'attune-verify[rag]'
```

## Quick start

```python
from attune_verify import verify, VerifyContext
from pathlib import Path

ctx = VerifyContext(
    project_root=Path("."),
    allowed_help_cmds=frozenset(["attune"]),
)
result = verify(generated_content, ctx)
if not result.ok:
    for f in result.findings:
        print(f"{f.kind}: {f.detail}")
```

## Part of the attune family

- **attune-rag** grounds generation in accurate retrieved sources (input-side)
- **attune-verify** checks that named entities in the output actually exist (output-side)

Together they bracket generation: rag verifies *"is this claim supported?"*;
verify checks *"does this named thing exist?"*

## What each checker verifies

| Checker | Claim it settles | Truth source you declare |
|---|---|---|
| imports | every import in a Python code fence resolves, by full dotted path | `env_python` |
| flags | every `--flag` in an inline span or shell fence appears in that command's `--help` | `help_commands` / `allowed_help_cmds` |
| links | every local markdown link target exists under the project | `project_root` |
| counts | every numeric claim matches the number it names | `count_sources` |

Findings are `error` when a claim is refuted and `warning` when it cannot be
checked — an unverifiable claim is never a silent pass. `result.ok` is False
only on errors; `raise_if_failed(result)` turns it into a hard gate.

## Status

Beta — the deterministic core (imports, flags, links, counts) is stable and
guarded by a labeled precision/recall corpus (gated ≥ 0.95 each) and mutation
testing (gated ≥ 0.75). The public API above (`verify`, `VerifyContext`,
`VerifyResult`, `Finding`, `FindingKind`, `raise_if_failed`, and the `Judge`
protocol) is what beta covers: it will not change shape without a deprecation
in a minor release. The LLM semantic layer is optional via the `[rag]` extra
and is the least settled part of the surface.

### Known limitations

- Reference-style links (`[text][ref]`) are not resolved — only inline
  `[text](target)` links are checked.
- Short flags (`-v`) are not checked; only `--long` forms are.
- A flag written as bare `` `--flag` `` in prose is attributed to the nearest
  preceding word, so it may degrade to a warning rather than resolve.
- Counts are matched to a source by keyword overlap with the claim's
  surrounding text; a numeric claim whose context names no source is skipped
  rather than guessed at.

## License

Apache 2.0
