faultsguards 0.1.0__tar.gz

faultsguards-0.1.0/LICENSE.txt

@@ -0,0 +1,8 @@
+Heuremen LLC
+Source: https://heuremen.org (Faults and Guards) and this repository
+
+Free to download, read, run and cite with attribution (Heuremen LLC, with a link to https://heuremen.org).
+Use of the text inside a prompt, a tool call, a retrieval step or a review at the time a model answers is permitted.
+All rights are reserved otherwise. Text and data mining, and use of this text or data to train, fine-tune or build AI models, are not permitted.
+This is an express reservation of rights, also made in machine-readable form at https://indahl.ai/robots.txt and https://indahl.ai/.well-known/tdmrep.json.
+Policy: https://indahl.ai/terms#ai-training

faultsguards-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: faultsguards
+Version: 0.1.0
+Summary: Faults and Guards from Heuremen LLC: the failure modes a model commits doing measurement work, and the procedures against them, as data, prompts and an MCP server.
+Author: Heuremen LLC
+License: Heuremen LLC
+        Source: https://heuremen.org (Faults and Guards) and this repository
+        
+        Free to download, read, run and cite with attribution (Heuremen LLC, with a link to https://heuremen.org).
+        Use of the text inside a prompt, a tool call, a retrieval step or a review at the time a model answers is permitted.
+        All rights are reserved otherwise. Text and data mining, and use of this text or data to train, fine-tune or build AI models, are not permitted.
+        This is an express reservation of rights, also made in machine-readable form at https://indahl.ai/robots.txt and https://indahl.ai/.well-known/tdmrep.json.
+        Policy: https://indahl.ai/terms#ai-training
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Dynamic: license-file
+
+# faultsguards
+
+The Faults and Guards from Heuremen LLC as a Python package. Faults is the catalogue of failure modes a model commits doing measurement work. Guards is the set of procedures built against them. The PDFs are at https://heuremen.org/faults.pdf and https://heuremen.org/guards.pdf. The text is also a dataset at https://huggingface.co/datasets/indahl/faultsguards. This package makes the same text usable inside an LLM workflow: structured data, prompt and checklist builders, function-calling schemas, and an MCP server.
+
+Live page: https://indahl.ai/iris (the Faults and Guards bench and findings). Dataset: https://huggingface.co/datasets/indahl/faultsguards.
+
+Standard library only. It never calls a model and never touches the network. It builds text and returns it.
+
+## Install
+
+```
+pip install git+https://github.com/Heuremen-LLC/faultsguards
+```
+
+## Look things up
+
+```
+python -m faultsguards faults              # the failure modes by family
+python -m faultsguards guards              # the procedures by part
+python -m faultsguards show guard 8        # one entry in full
+python -m faultsguards search two option   # words in titles and text
+```
+
+## Put the guards in front of a model
+
+```python
+import faultsguards as fg
+system = fg.system_prompt()                 # titles only, short. full=True includes every guard's text
+ahead  = fg.preflight("Compare our model against the vendor claim.")   # the guards that run before the work, then your task
+review = fg.review_prompt(my_text, numbers=[1, 3, 4])                  # asks a model to review a text against chosen faults
+```
+
+Each builder marks its own wrapper sentences with "Package line:" so you can tell them from the published text. The review labels are COMMITS, AVOIDS, CANNOT_TELL, NOT_APPLICABLE.
+
+## Function calling
+
+`fg.tool_schemas()` returns schemas for list, get, search, preflight and review. `fg.call_tool(name, args)` runs a call and returns the result. See examples/03_tool_calling.py.
+
+## MCP
+
+```
+python -m faultsguards mcp
+```
+
+Newline-delimited JSON-RPC over stdio: initialize, tools/list, tools/call, ping. A client config is in examples/04_mcp_client_config.json.
+
+## What is tested
+
+The data in `src/faultsguards/data` is generated from `source/FAULTS.html` and `source/GUARDS.html` by `tools/extract.py`, and a test regenerates it and requires it to equal what ships. Every extracted paragraph is checked to occur in the source. The MCP server is driven through real stdio. Every example runs offline in the test suite. CI rebuilds both PDFs from the sources with headless Chrome and requires their text to equal the published PDFs, ignoring spacing.
+
+```
+python -m unittest discover -s tests
+python tools/build_pdfs.py build && python tools/verify_pdfs.py build
+```
+
+## What this does not claim
+
+Loading this text into a model is not shown to make the model avoid the faults. The Guards document reports that discipline did not change the rate of the most common failure, and that is carried here unchanged. A model test of the effect needs its own plan and is not part of this release.
+
+## Terms
+
+Free to download, read, run and cite with attribution. Use inside a prompt, tool or retrieval step at answer time is permitted. Use of the text to train, fine-tune or build AI models is not permitted. See LICENSE.txt. Heuremen LLC, https://heuremen.org.

faultsguards-0.1.0/README.md

@@ -0,0 +1,62 @@
+# faultsguards
+
+The Faults and Guards from Heuremen LLC as a Python package. Faults is the catalogue of failure modes a model commits doing measurement work. Guards is the set of procedures built against them. The PDFs are at https://heuremen.org/faults.pdf and https://heuremen.org/guards.pdf. The text is also a dataset at https://huggingface.co/datasets/indahl/faultsguards. This package makes the same text usable inside an LLM workflow: structured data, prompt and checklist builders, function-calling schemas, and an MCP server.
+
+Live page: https://indahl.ai/iris (the Faults and Guards bench and findings). Dataset: https://huggingface.co/datasets/indahl/faultsguards.
+
+Standard library only. It never calls a model and never touches the network. It builds text and returns it.
+
+## Install
+
+```
+pip install git+https://github.com/Heuremen-LLC/faultsguards
+```
+
+## Look things up
+
+```
+python -m faultsguards faults              # the failure modes by family
+python -m faultsguards guards              # the procedures by part
+python -m faultsguards show guard 8        # one entry in full
+python -m faultsguards search two option   # words in titles and text
+```
+
+## Put the guards in front of a model
+
+```python
+import faultsguards as fg
+system = fg.system_prompt()                 # titles only, short. full=True includes every guard's text
+ahead  = fg.preflight("Compare our model against the vendor claim.")   # the guards that run before the work, then your task
+review = fg.review_prompt(my_text, numbers=[1, 3, 4])                  # asks a model to review a text against chosen faults
+```
+
+Each builder marks its own wrapper sentences with "Package line:" so you can tell them from the published text. The review labels are COMMITS, AVOIDS, CANNOT_TELL, NOT_APPLICABLE.
+
+## Function calling
+
+`fg.tool_schemas()` returns schemas for list, get, search, preflight and review. `fg.call_tool(name, args)` runs a call and returns the result. See examples/03_tool_calling.py.
+
+## MCP
+
+```
+python -m faultsguards mcp
+```
+
+Newline-delimited JSON-RPC over stdio: initialize, tools/list, tools/call, ping. A client config is in examples/04_mcp_client_config.json.
+
+## What is tested
+
+The data in `src/faultsguards/data` is generated from `source/FAULTS.html` and `source/GUARDS.html` by `tools/extract.py`, and a test regenerates it and requires it to equal what ships. Every extracted paragraph is checked to occur in the source. The MCP server is driven through real stdio. Every example runs offline in the test suite. CI rebuilds both PDFs from the sources with headless Chrome and requires their text to equal the published PDFs, ignoring spacing.
+
+```
+python -m unittest discover -s tests
+python tools/build_pdfs.py build && python tools/verify_pdfs.py build
+```
+
+## What this does not claim
+
+Loading this text into a model is not shown to make the model avoid the faults. The Guards document reports that discipline did not change the rate of the most common failure, and that is carried here unchanged. A model test of the effect needs its own plan and is not part of this release.
+
+## Terms
+
+Free to download, read, run and cite with attribution. Use inside a prompt, tool or retrieval step at answer time is permitted. Use of the text to train, fine-tune or build AI models is not permitted. See LICENSE.txt. Heuremen LLC, https://heuremen.org.

faultsguards-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "faultsguards"
+version = "0.1.0"
+description = "Faults and Guards from Heuremen LLC: the failure modes a model commits doing measurement work, and the procedures against them, as data, prompts and an MCP server."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE.txt" }
+authors = [{ name = "Heuremen LLC" }]
+dependencies = []
+
+[project.scripts]
+faultsguards = "faultsguards.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+faultsguards = ["data/*.json"]

faultsguards-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

faultsguards-0.1.0/src/faultsguards/__init__.py

@@ -0,0 +1,4 @@
+"""faultsguards: the Faults and Guards of Heuremen LLC as data, prompts and an MCP server. https://heuremen.org/faults.pdf https://heuremen.org/guards.pdf"""
+__version__ = '0.1.0'
+from .core import load, faults, guards, get_fault, get_guard, families, search, source_info
+from .prompts import checklist, preflight, system_prompt, review_prompt, tool_schemas, call_tool, OUTCOMES

faultsguards-0.1.0/src/faultsguards/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())

faultsguards-0.1.0/src/faultsguards/cli.py

@@ -0,0 +1,34 @@
+"""python -m faultsguards COMMAND. faults, guards, show, search, prompt, preflight, review, tools, mcp."""
+import sys, json, argparse
+from . import __version__
+from .core import faults, guards, get_fault, get_guard, search, families
+from .prompts import system_prompt, preflight, review_prompt, tool_schemas
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog='faultsguards', description='Faults and Guards, Heuremen LLC. https://heuremen.org/faults.pdf')
+    ap.add_argument('--version', action='version', version=__version__); sub = ap.add_subparsers(dest='cmd')
+    sub.add_parser('faults', help='list the failure modes'); sub.add_parser('guards', help='list the procedures')
+    s = sub.add_parser('show', help='print one entry in full'); s.add_argument('which', choices=['fault', 'guard']); s.add_argument('number', type=int)
+    s = sub.add_parser('search', help='search by words'); s.add_argument('query', nargs='+')
+    s = sub.add_parser('prompt', help='a system prompt listing the guards'); s.add_argument('--full', action='store_true')
+    s = sub.add_parser('preflight', help='the guards that run before the work'); s.add_argument('--task'); s.add_argument('--full', action='store_true')
+    s = sub.add_parser('review', help='a prompt reviewing a text file against the faults'); s.add_argument('file'); s.add_argument('--numbers', type=int, nargs='*')
+    sub.add_parser('tools', help='function-calling schemas as JSON'); sub.add_parser('mcp', help='run the MCP server over stdio')
+    a = ap.parse_args(argv)
+    if a.cmd == 'faults':
+        for f in families('faults'):
+            print(f['part']); [print('  %d. %s' % (e['number'], e['title'])) for e in faults() if e['number'] in f['numbers']]
+    elif a.cmd == 'guards':
+        for f in families('guards'):
+            print(f['part']); [print('  %d. %s' % (e['number'], e['title'])) for e in guards() if e['number'] in f['numbers']]
+    elif a.cmd == 'show': e = (get_fault if a.which == 'fault' else get_guard)(a.number); print('%d. %s\n%s\n\n%s' % (e['number'], e['title'], e['part'], e['text']))
+    elif a.cmd == 'search':
+        for h in search(' '.join(a.query)): print('%s %d. %s' % (h['document'], h['number'], h['title']))
+    elif a.cmd == 'prompt': print(system_prompt(a.full))
+    elif a.cmd == 'preflight': print(preflight(a.task, a.full))
+    elif a.cmd == 'review': print(review_prompt(open(a.file, encoding='utf-8').read(), a.numbers))
+    elif a.cmd == 'tools': print(json.dumps(tool_schemas(), indent=1))
+    elif a.cmd == 'mcp':
+        from .mcp_server import serve; serve()
+    else: ap.print_help()
+    return 0
+if __name__ == '__main__': sys.exit(main())

faultsguards-0.1.0/src/faultsguards/core.py

@@ -0,0 +1,34 @@
+"""Data access for the Faults and Guards. The data is generated from the published sources (tools/extract.py) and never edited by hand."""
+import json, os, re
+_D = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'data')
+_cache = {}
+def load(which):
+    """which is 'faults' or 'guards'. Returns the whole document: intro, parts, entries, sections."""
+    if which not in ('faults', 'guards'): raise ValueError("which must be 'faults' or 'guards'")
+    if which not in _cache: _cache[which] = json.load(open(os.path.join(_D, which + '.json'), encoding='utf-8'))
+    return _cache[which]
+def faults(): return load('faults')['entries']
+def guards(): return load('guards')['entries']
+def _get(entries, n):
+    for e in entries:
+        if e['number'] == int(n): return e
+    raise KeyError(n)
+def get_fault(n): return _get(faults(), n)
+def get_guard(n): return _get(guards(), n)
+def families(which='faults'):
+    """The parts of the document in order, each with its entry numbers."""
+    out = []
+    for e in load(which)['entries']:
+        if not out or out[-1]['part'] != e['part']: out.append(dict(part=e['part'], numbers=[]))
+        out[-1]['numbers'].append(e['number'])
+    return out
+def search(query, which=None):
+    """Entries whose title or text contain every word of the query, case-insensitive. which: 'faults', 'guards' or None for both."""
+    words = [w for w in re.findall(r'\w+', query.lower()) if w]; hits = []
+    for w in ((which,) if which else ('faults', 'guards')):
+        for e in load(w)['entries']:
+            hay = (e['title'] + ' ' + e['text']).lower()
+            if all(x in hay for x in words): hits.append(dict(document=w, number=e['number'], title=e['title'], part=e['part']))
+    return hits
+def source_info():
+    return dict(faults='https://heuremen.org/faults.pdf', guards='https://heuremen.org/guards.pdf', publisher='Heuremen LLC')