faultsguards 0.1.0__py3-none-any.whl

faultsguards/mcp_server.py

@@ -0,0 +1,30 @@
+"""A small MCP server over stdio (newline-delimited JSON-RPC), standard library only. Methods: initialize, tools/list, tools/call, ping. Read-only, no network, no model calls."""
+import sys, json
+from . import __version__
+from .prompts import tool_schemas, call_tool
+PROTO = '2024-11-05'
+def _tools():
+    return [dict(name=t['function']['name'], description=t['function']['description'], inputSchema=t['function']['parameters']) for t in tool_schemas()]
+def handle(msg):
+    """returns a response dict, or None for notifications"""
+    m = msg.get('method'); i = msg.get('id')
+    if i is None: return None
+    if m == 'initialize': return dict(jsonrpc='2.0', id=i, result=dict(protocolVersion=PROTO, capabilities=dict(tools={}), serverInfo=dict(name='faultsguards', version=__version__)))
+    if m == 'ping': return dict(jsonrpc='2.0', id=i, result={})
+    if m == 'tools/list': return dict(jsonrpc='2.0', id=i, result=dict(tools=_tools()))
+    if m == 'tools/call':
+        p = msg.get('params') or {}
+        try: r = call_tool(p.get('name'), p.get('arguments'))
+        except KeyError: return dict(jsonrpc='2.0', id=i, result=dict(isError=True, content=[dict(type='text', text='unknown tool or entry: %s' % p.get('name'))]))
+        except Exception as e: return dict(jsonrpc='2.0', id=i, result=dict(isError=True, content=[dict(type='text', text='error: %s' % type(e).__name__)]))
+        return dict(jsonrpc='2.0', id=i, result=dict(content=[dict(type='text', text=r if isinstance(r, str) else json.dumps(r, ensure_ascii=False, indent=1))]))
+    return dict(jsonrpc='2.0', id=i, error=dict(code=-32601, message='method not found: %s' % m))
+def serve(inp=None, out=None):
+    inp = inp or sys.stdin; out = out or sys.stdout
+    for line in inp:
+        line = line.strip()
+        if not line: continue
+        try: msg = json.loads(line)
+        except Exception: out.write(json.dumps(dict(jsonrpc='2.0', id=None, error=dict(code=-32700, message='parse error'))) + '\n'); out.flush(); continue
+        r = handle(msg)
+        if r is not None: out.write(json.dumps(r, ensure_ascii=False) + '\n'); out.flush()

faultsguards/prompts.py

@@ -0,0 +1,47 @@
+"""Prompt and checklist builders. The text of each fault and guard is exactly as published. The wrapper sentences here are the package's own and are marked as such."""
+from .core import load, faults, guards, get_fault, get_guard
+OUTCOMES = ('COMMITS', 'AVOIDS', 'CANNOT_TELL', 'NOT_APPLICABLE')
+CREDIT = 'Faults and Guards, Heuremen LLC, https://heuremen.org/faults.pdf and https://heuremen.org/guards.pdf. Use at answer time is permitted. Use as training data is not.'
+def _fmt(e, full):
+    return '%d. %s\n%s' % (e['number'], e['title'], e['text']) if full else '%d. %s' % (e['number'], e['title'])
+def checklist(part=None, full=False):
+    """Guards as an ordered list. part: None for all, or a roman numeral prefix such as 'I' (procedures that run before the work), 'II', 'III', 'IV'. full=True includes each guard's whole text."""
+    es = guards()
+    if part: es = [e for e in es if (e['part'] or '').split(' ')[0] == part]
+    return '\n\n'.join(_fmt(e, full) for e in es)
+def preflight(task=None, full=False):
+    """The guards that run before the work, to place ahead of a task. The package line is ours, the numbered guards are as published."""
+    head = 'Package line: before you compute or state any number for the task below, work through these procedures in order.\n\n'
+    body = checklist('I', full)
+    tail = ('\n\nTask:\n' + task) if task else ''
+    return head + body + tail + '\n\nSource: ' + CREDIT
+def system_prompt(full=False, parts=('I', 'II', 'III', 'IV')):
+    """A system prompt that lists the guards. Titles only by default, which is short. full=True includes every guard's text (long)."""
+    head = 'Package line: the procedures below come from Faults and Guards. They apply before a number is stated, not after. Four outcomes only for any result: ABOVE, BELOW, CONSISTENT, CANNOT_TELL.\n\n'
+    body = '\n\n'.join('Part %s\n%s' % (p, checklist(p, full)) for p in parts)
+    return head + body + '\n\nSource: ' + CREDIT
+def review_prompt(text, numbers=None, full=True):
+    """A prompt asking a model to review text against faults. numbers: fault numbers to use, default all. The four labels are the package's own."""
+    fs = [get_fault(n) for n in numbers] if numbers else faults()
+    head = ('Package line: review the text under REVIEW against each fault below. For each fault answer with one label, %s, and quote the sentence that decides it. '
+            'COMMITS means the text commits the fault. AVOIDS means it addresses it. CANNOT_TELL means the text does not show either. NOT_APPLICABLE means the fault does not apply to this kind of text. Do not fold CANNOT_TELL into COMMITS.\n\n') % ', '.join(OUTCOMES)
+    return head + 'FAULTS\n' + '\n\n'.join(_fmt(e, full) for e in fs) + '\n\nREVIEW\n' + text + '\n\nSource: ' + CREDIT
+def tool_schemas():
+    """Function-calling schemas (JSON Schema parameters) for list, get, search, preflight and review, usable with any tool-calling API."""
+    S = lambda name, desc, props, req=(): dict(type='function', function=dict(name=name, description=desc, parameters=dict(type='object', properties=props, required=list(req))))
+    return [S('list_faults', 'List the failure modes in Faults: number, title, family.', {}), S('list_guards', 'List the procedures in Guards: number, title, part.', {}),
+            S('get_fault', 'The full published text of one fault.', {'number': {'type': 'integer'}}, ['number']), S('get_guard', 'The full published text of one guard.', {'number': {'type': 'integer'}}, ['number']),
+            S('search', 'Search faults and guards by words.', {'query': {'type': 'string'}}, ['query']), S('preflight', 'The guards that run before the work, optionally ahead of a task.', {'task': {'type': 'string'}, 'full': {'type': 'boolean'}}),
+            S('review_prompt', 'A prompt that reviews a text against the faults.', {'text': {'type': 'string'}, 'numbers': {'type': 'array', 'items': {'type': 'integer'}}}, ['text'])]
+def call_tool(name, args):
+    """Runs one tool by name and returns a JSON-serialisable result."""
+    a = args or {}
+    if name == 'list_faults': return [dict(number=e['number'], title=e['title'], family=e['part']) for e in faults()]
+    if name == 'list_guards': return [dict(number=e['number'], title=e['title'], part=e['part']) for e in guards()]
+    if name == 'get_fault': e = get_fault(a['number']); return dict(number=e['number'], title=e['title'], family=e['part'], text=e['text'], source=CREDIT)
+    if name == 'get_guard': e = get_guard(a['number']); return dict(number=e['number'], title=e['title'], part=e['part'], text=e['text'], source=CREDIT)
+    if name == 'search':
+        from .core import search; return search(a['query'])
+    if name == 'preflight': return preflight(a.get('task'), bool(a.get('full')))
+    if name == 'review_prompt': return review_prompt(a['text'], a.get('numbers'))
+    raise KeyError(name)

faultsguards-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+faultsguards/__init__.py,sha256=oK2HS_cbJeDhwpUcqdqUYJiwgS_wou74I-z4AkQQ1lQ,379
+faultsguards/__main__.py,sha256=81Ek5TDGfhRLYb38ohIwEISYL8FAiiMV84Jhf6pukg8,50
+faultsguards/cli.py,sha256=fqk8wLNRm1j8KIX1Td3RjXGb5cPmCD3SzF4KQ3_Jtm4,2658
+faultsguards/core.py,sha256=-3RhEAe-_oP1eTnE0_ukuIHkgA1UBX9dm37KzaOV8iI,1881
+faultsguards/mcp_server.py,sha256=GU-Wk8koUZrtcYkSHhqYifdVKfrZL-N-xOToDG63W_E,2117
+faultsguards/prompts.py,sha256=XFNJUItcczsTGQR0n5bLWDXy2p4OuKs7N0sl0Y_GxII,4862
+faultsguards/data/faults.json,sha256=CBZjXW8OhbrTUD9QNU7qCa36_LeHYFjJUmcoelecu1o,83398
+faultsguards/data/guards.json,sha256=z-KRWEhol9y-MPGKwpFF2aOWOV7aeKqlNEuaSOwIruc,68785
+faultsguards-0.1.0.dist-info/licenses/LICENSE.txt,sha256=qU9ota9aLuQiAb1gR9dgiv5CSGOBrpoLhfsutGPzjUA,652
+faultsguards-0.1.0.dist-info/METADATA,sha256=rTBK-HbNNoJZsc6qEbdPVZhAUVdovScEXiHkke2x8o8,4446
+faultsguards-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+faultsguards-0.1.0.dist-info/entry_points.txt,sha256=0AOX8zrIMpMhU8IIU89Ucln5di5jtZD7SzSbzRXr31k,55
+faultsguards-0.1.0.dist-info/top_level.txt,sha256=Fxoz2jUCsVJ_tmeRF9Jxbfno7rJTYdh-Ino4GmOAXLM,13
+faultsguards-0.1.0.dist-info/RECORD,,

faultsguards-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

faultsguards-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+faultsguards = faultsguards.cli:main

faultsguards-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+faultsguards