Metadata-Version: 2.4
Name: ed-witness
Version: 0.2.2
Summary: Ed — the Witness Translation Engine: AI-assisted Bible translation reasoning with inspectable multi-LLM debate.
License: Apache-2.0
Project-URL: Homepage, https://github.com/gellsmore-svg/Ed
Project-URL: Repository, https://github.com/gellsmore-svg/Ed
Project-URL: Issues, https://github.com/gellsmore-svg/Ed/issues
Keywords: witness,reasoning,translation,bible,hebrew,greek,cantillation,llm
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff<0.16,>=0.6; extra == "dev"
Requires-Dist: fastapi>=0.110; extra == "dev"
Requires-Dist: uvicorn>=0.29; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn>=0.29; extra == "web"
Provides-Extra: keturah
Requires-Dist: keturah>=0.1; extra == "keturah"
Provides-Extra: hoglah
Requires-Dist: hoglah>=0.8.0; extra == "hoglah"
Provides-Extra: milcah
Requires-Dist: milcah>=0.2.0; extra == "milcah"
Provides-Extra: mahalath
Requires-Dist: mahalath>=1.1.0; extra == "mahalath"
Requires-Dist: pymongo>=4.6; extra == "mahalath"
Provides-Extra: tirzah
Requires-Dist: tirzah>=1.3.0; extra == "tirzah"
Requires-Dist: pymongo>=4.6; extra == "tirzah"
Provides-Extra: galeed
Requires-Dist: galeed>=0.1; extra == "galeed"
Requires-Dist: pymongo>=4.6; extra == "galeed"
Provides-Extra: family
Requires-Dist: hoglah>=0.8.0; extra == "family"
Requires-Dist: milcah>=0.2.0; extra == "family"
Requires-Dist: mahalath>=1.1.0; extra == "family"
Requires-Dist: tirzah>=1.3.0; extra == "family"
Requires-Dist: galeed>=0.1; extra == "family"
Requires-Dist: keturah>=0.1; extra == "family"
Requires-Dist: pymongo>=4.6; extra == "family"
Dynamic: license-file

# Ed — AI Bible Translation Reasoning

**Ed** (עֵד, *witness*) is an AI-assisted Bible translation *reasoning* platform.
It uses the **Textus Receptus (TSR)** Greek text, the **Masoretic Hebrew**
tradition, and the family stack (Mahalath, Tirzah, Milcah, Hoglah) to translate
under configurable principles — reconstructing the *principles* behind the King
James Version, not copying KJV wording.

> The Bible is a self-defining, self-referencing whole: any term is interpreted
> in light of every other canonical occurrence.

See [`docs/vision.md`](docs/vision.md) and
[`docs/translation-principle-semantic-layers.md`](docs/translation-principle-semantic-layers.md).

```bash
ed --help
ed policies
ed policies --format json --out policies.json
ed target-languages
ed target-languages --format json --out target-languages.json
ed manifest --out ed-manifest.json
ed build-bundle fixtures/john-1-1.json --policy evidence-based --out bundle.json
ed build-bundle fixtures/john-1-1.json --policy evidence-based --format markdown --out bundle.md
ed build-debate-prompt bundle.json --target-language en --out prompt.txt
ed build-bundle fixtures/genesis-1-1-cantillation.json --policy masoretic-traditional --out hebrew-bundle.json
ed decide bundle.json --target-language en --mock --out decision.json
ed decide bundle.json --target-language en --mock --prior-decision decision.json --out revised-decision.json
ed decide hebrew-bundle.json --target-language en --mock --out hebrew-decision.json
ed decide bundle.json --target-language es --mock --out decision-es.json
ed explain decision.json
ed explain decision.json --out decision.md
ed evaluate-decision decision.json fixtures/evaluations/john-1-1-en.json
ed evaluate-decision hebrew-decision.json fixtures/evaluations/genesis-1-1-en-cantillation.json
ed run-evaluation-suite fixtures/evaluation-suite.json --mock --out suite-report.json
ed explain-suite suite-report.json --out suite-report.md
ed run-evaluation-suite fixtures/evaluation-suite.json --mock --format markdown --out suite-report.md
ed run-evaluation-suite fixtures/evaluation-suite.json --mock --case-id genesis-1-1-en-cantillation --work-dir suite-artifacts
# optional trace output (overwrites by default; --trace-append to accumulate):
ed decide bundle.json --target-language en --mock --trace-out trace.jsonl
ed explain-trace trace.jsonl --out trace.md
# optional local Ollama adapter:
ollama create ed-dictalm-q8-final -f ops/ollama/ed-dictalm-q8-final.Modelfile
ed decide bundle.json --target-language en --ollama-model ed-dictalm-q8-final --prompt-out prompt.txt --out decision.json
# optional Milcah specialist pressure-test adapter:
ed build-milcah-request bundle.json --target-language en --out milcah-request.json
# ...or seed the request from an existing decision instead of a fresh mock:
ed build-milcah-request bundle.json --base-decision decision.json --out milcah-request.json
ed decide bundle.json --target-language en --milcah --out decision-milcah.json
# optional thinking review packet:
ed decide bundle.json --target-language en --ollama-model hf.co/dicta-il/DictaLM-3.0-24B-Thinking-GGUF:Q8_0 --ollama-think --capture-thinking --out decision.json
ed review-thinking decision.json --out thinking-review.md
```

Use `--capture-thinking` with an Ollama thinking model only when the raw
reasoning trace should be stored in the decision metadata for later
documentation/review. By default Ed records that thinking was present without
persisting the trace. Local Ollama decisions request JSON-mode output by
default; use `--no-ollama-json-mode` only for models that fail under constrained
formatting. If a thinking model returns private reasoning but no final
rendering, Ed fails the debate and records diagnostic stop/length metadata in
the trace without storing raw thinking text.

Live Ollama output is only credited with the witnesses the model actually cites
(validated against the bundle); if it cites none, Ed records a review note
rather than implying grounding. If it cites an id that is *not* in the bundle,
Ed names the invented ids in a review note rather than dropping them quietly —
a fabricated citation is evidence the rendering needs more scrutiny, not less.
Repeated citations of one witness are counted once. Structured debate JSON can be long, so
`--ollama-num-predict` defaults to 1024; a generation that stops at the length
limit is flagged with a review note (raise `--ollama-num-predict` and re-run).

## Rule templates & web UI

The built-in policies are the seeded set; you can also author your own
**translation-rule templates** — a policy plus optional `tone`, `custom_guidance`,
and a `term_glossary` (fixed renderings for salient lexemes) — and translate
under them. Templates are stored as JSON under `~/.ed/templates` and are usable
anywhere a policy id is, including `--policy`.

```bash
ed templates save my-rule.json          # validate + store a rule template
ed templates list
ed build-bundle fixtures/john-1-1.json --policy my-rule --out bundle.json
ed build-bundle fixtures/john-1-1.json --policy ./my-rule.json --out bundle.json  # or a file
```

An interactive UI is available with the `web` extra:

```bash
pip install 'ed[web]'
ed serve                                 # http://127.0.0.1:8799
```

Author/edit a rule template (fork a built-in or start blank), paste or upload an
evidence fixture (source unit + witnesses), pick a target language, and translate
— the decision (rendering, reasoning, unresolved questions, cited witnesses)
renders live. Save the template to reuse it from the CLI.

## Family stack

| Sibling | Role in Ed |
|---|---|
| Mahalath | ontology, semantic precision |
| Tirzah | memory, retrieval, concordance |
| Milcah | multi-LLM debate, argument evaluation |
| Hoglah | LLM execution queue |
| Galeed | process trace |
| Keturah | capability manifest |

## Sense layer (design)

Design work for a Hebrew/Greek sense layer — so that what a source word *means*
comes from codified, debated, corpus-derived evidence rather than a model's
memory — is recorded in **ADR-006 – ADR-014** of
[`docs/architecture-decisions.md`](docs/architecture-decisions.md). Headlines:
Mahalath owns the source-language sense inventory and Ed owns rendering; one
sense per lexeme by default, with splits as justified exceptions; **no English
lexicon** — English is purely a rendering under policy; reference lexica are
witnesses Ed may visibly disagree with; and terms with no English equivalent get
a consistent multi-word rendering or a debated composite coinage plus a
reader-facing dictionary entry.

The working paper behind those decisions — options not taken, the licensing
research, and the build order — is
[`docs/lexicon-options.md`](docs/lexicon-options.md). **Nothing here is built
yet.**

## Review

A point-in-time functional + code review of 0.2.0 is in
[`docs/review-2026-08-11.md`](docs/review-2026-08-11.md). All eight findings
were actioned in 0.2.1 — see the remediation section at the end of that
document.

## Develop

```bash
pip install -e ".[dev]"
pytest
```

Install `.[keturah]` or the sibling Keturah checkout when validating the full
capability-manifest integration. Ed can run its standalone fixture workflow
without Keturah installed.

Install `.[milcah]` or the sibling Milcah checkout to run `ed decide --milcah`;
the default development/test install keeps that integration optional.

## License

[Apache License 2.0](LICENSE).
