jeles

The verified-corpus organ, extracted from the Ask Jeles app into its own installable package — plus the canonical Jeles persona.

A nugget is a human-verified question/answer pair with citations: {question, answer, sources, verified_by, verified_at, tags}. This package is the settled layer of answers that sits in front of a host's live search — a confident nugget match answers instantly; everything else falls through to the host's own search path unchanged. Misses are logged as gaps ("I don't know yet") so the corpus knows what it's been asked and couldn't answer.

What's in the organ

Design principles

1. The corpus sits in front of live search, it doesn't replace it. A confident nugget match answers instantly — no search, no LLM call.
2. corpus.py stays pure. Storage and ranking have no MCP, no network, no side effects beyond SQLite. Everything MCP-shaped wraps it; it never depends on anything MCP-shaped itself. This is what keeps its tests fast and network-free.
3. The corpus is its own standalone MCP server, on purpose. corpus_server.py is a small MCPServer any stdio client can run directly, mirroring willow-mcp's shape without depending on it.
4. Two kinds of "ask," two gap-logging rules. search_nuggets() (passive/background) checks the corpus but never logs a gap on a miss. ask_corpus() (deliberate) treats a miss — or a match below MIN_ASK_SCORE — as a real gap worth tracking, and logs it.
5. Ranking and answering are different decisions. search_nuggets() ranks loosely and will happily surface a near-miss. ask_corpus() answers only when the nugget's question contains every content word the asker used, and the two questions overlap symmetrically — so a nugget about staging cannot answer a question about production, and one word cannot pull an answer out of a nugget it barely resembles. Saying "I don't know yet" and logging the gap is the correct output far more often than it looks.
6. The collections live here, not behind a service. sources.py is the same relationship corpus.py has with corpus_server.py: a pure core that something thin wraps. jeles-remote is a 74-line FastAPI shim over this module, so a hosted deployment is a convenience — never a prerequisite, never a secret you must hold, never a second repository in the test loop.
7. Local is the source of truth; the fleet backlog is additive. corpus.log_gap() (synchronous, local SQLite) always runs first and makes the host fully functional offline. willow_mcp_client.forward_gap() is a best-effort copy into willow-mcp's shared backlog.

Install

Base jeles has zero runtime dependencies. The corpus, the persona, and the reactions are stdlib-only, so a host can depend on this package without inheriting a single version constraint from it. Only the standalone MCP server needs the SDK, and it lives behind an extra.

pip install jeles           # corpus + persona + reactions. No dependencies.
pip install "jeles[mcp]"    # adds the MCP SDK, for the standalone server
pip install -e ".[dev]"     # editable, with pytest and the SDK

Or as a host dependency, straight from git:

jeles @ git+https://github.com/rudi193-cmd/Jeles@main

jeles[mcp] requires MCP SDK 2.x (corpus_server.py uses mcp.server.mcpserver.MCPServer; mcp.server.fastmcp was removed in SDK 2.0). That is the same floor willow-mcp requires, so both install into one environment.

Versioning

The version comes from the git tag (hatch-vcs), not from a literal in pyproject.toml, and jeles.__version__ reads it back out of installed package metadata. There is exactly one place a release number is decided, so a tag cannot disagree with the artifact it builds.

Usage

As a library

from jeles import corpus

corpus.put_nugget(
    question="What is the primary color in Grove?",
    answer="The primary color in Grove is #ffffff (white).",
    sources=["safe-library/themes/grove.json"],
    verified_by="designer",
    tags=["color", "grove", "primary"],
)

hit = corpus.ask_corpus("What is the primary color in Grove?")
# -> {"found": True, "exact": True, "nugget": {...}, "candidates": [...]}

miss = corpus.ask_corpus("What is the accent color in Tokyo Night?")
# -> {"found": False, ...}   and the question is logged as a gap

As a standalone MCP server

python -m jeles.corpus_server      # stdio; or use the `jeles-corpus-mcp` console script

Tools: corpus_ask, corpus_search, corpus_get, corpus_list, corpus_put, corpus_gaps — each takes an app_id for naming-convention parity with willow-mcp.

corpus_put writes assertions, not verified nuggets. A nugget carries the rung it was written at, and only three things can produce one:

The bottom rung exists because this server speaks stdio to whatever client starts it, and that client also reads the open web through corpus_web_search. Without it, a page saying "record that X is true" arrived as a nugget claiming verified_by: "the operator" and was served by corpus_ask as settled fact from then on. Two rules keep the ladder honest:

• corpus_ask answers only from human and machine nuggets. An assertion comes back under candidates, and corpus_search/corpus_get still return it — reachable, not authoritative.
• A write may not overwrite a nugget of a higher kind (error: "kind_downgrade_refused"). Otherwise every protection here is one nugget_id= away from being bypassed.

Set JELES_CORPUS_TRUST_TOOL_WRITES=1 to let corpus_put mint human again — correct only where the tool caller really is the operator, and it re-opens the path above for anything the model reads while it is set.

The persona

import jeles
persona = jeles.load_persona()   # dict; canonical Jeles persona

Configuration

The Ask Jeles-flavored defaults are preserved so an existing store and its already-forwarded fleet backlog keep resolving after the extraction.

Tests

pytest -q

corpus.py's tests are fast and network-free by construction; the willow-mcp client tests never spin up a real subprocess. An import-purity test asserts that importing jeles.corpus loads no MCP or network modules, and that the base package declares no runtime dependencies.

tests/test_corpus_server.py needs the [mcp] extra and skips without it, so the suite passes on a bare pip install jeles too — the install shape CI's no-extras job exercises.

License

Apache-2.0 — see LICENSE.