Skip to main content

galet-prompt-builder

Provider-neutral orchestration of CoALA memory into bounded prompts.

The caller supplies instructions, current input, retrieval options, and budgets. Galet-prompt-builder obtains memory through galet-memory, chooses relevant candidates within the limits, and assembles provider messages with selection metrics. It consumes digests; it does not generate or store them. The host application chooses when to compile a prompt and which policy to use.

See the galet architecture notes for the full layering.

Install

Requires Python 3.11 or later. The commands below use a Linux/macOS shell.

Install the published package

python3 -m venv .venv
source .venv/bin/activate
python -m pip install galet-prompt-builder

Both galet and galet-memory are installed automatically as required dependencies. Add [semantic] when using the SQLite vector store: python -m pip install "galet-prompt-builder[semantic]".

Install from source and run the tests

git clone --branch develop https://github.com/junwin/galet-prompt-builder.git
cd galet-prompt-builder
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[test,semantic]"
python -m pytest -q

For an existing checkout, start from cd galet-prompt-builder and reuse your .venv if present. The test extra installs pytest; semantic installs sqlite-vec for vector recall. You can omit semantic if you do not use it.

Editable installation (-e) means Python imports this checkout, so source changes take effect without reinstalling. Dependencies come from your configured package index. To develop against sibling source checkouts too, install them into this same environment:

python -m pip install -e ../galet -e ../galet-memory

Those paths assume all three repositories share a parent directory. No PYTHONPATH setting is needed after the editable installation.

Update an existing source installation

Update your checkout with Git, activate its virtual environment, then run:

python -m pip install --upgrade --upgrade-strategy eager -e ".[test,semantic]"
python -m pytest -q

This upgrades dependencies within the constraints in pyproject.toml. If you are developing against editable sibling checkouts, update those repositories separately too.

Prompt-builder settings contain prompt policy and a reference to the shared galet-memory config, not another set of store paths or credential values. galet_prompt_builder_sample.json is a complete example. Its relative memory_config_path points to the sibling galet-tools config already tested through MCP; adjust the reference to your actual file.

{
  "config_version": 1,
  "memory_config_path": "../galet-tools/galet-memory-mcp.json",
  "policy": {
    "total_tokens": 6000,
    "semantic_tokens": 900,
    "maximum_semantic_documents": 3
  }
}

The public loader selects a configuration object, an explicit path, or GALET_PROMPT_BUILDER_CONFIG_PATH, in that order. Sources are selected rather than merged. File references resolve relative to the containing prompt config; a configuration object with a relative reference requires base_dir. Without prompt settings, policy defaults apply and galet-memory selects GALET_MEMORY_CONFIG_PATH. An invalid selected source fails without falling back. Galet-memory still owns its own config validation and backend assembly. Galet still owns credential lookup (GALET_CREDENTIAL_PATH or the selected profile). The configured embedding model is used for retrieval, rather than a hardcoded query model. Requires galet-memory 0.1.28 or newer.

Compile against the same existing stores as MCP

export GALET_CREDENTIAL_PATH=/home/junwin/credential
python -m galet_prompt_builder.cli "What do my notes say about Jon Fosse?" \
  --config galet_prompt_builder_sample.json \
  --account junwin --session-id YOUR_EXISTING_SESSION_ID \
  --namespaces books --format json

Or skip the policy file and pass the shared memory config directly:

python -m galet_prompt_builder.cli "What happened at Tyntesfield?" \
  --memory-config /home/junwin/src/repos/galet-tools/galet-memory-mcp.json \
  --account junwin --session-id YOUR_EXISTING_SESSION_ID --namespaces vol_7

--chat-name can replace --session-id. Configured mode uses the declared semantic metadata version, episodic database and procedural layout; it does not infer any of them from filenames. The comparison CLI requires existing stores and will not create missing databases, even if a shared test config has create:true. Legacy storage/layout/provider flags cannot be combined with shared configuration. Policy flags such as --total-tokens override only the specified policy values. Use --no-semantic or --no-digests to disable those retrieval channels. No LLM reply is generated, but semantic/digest retrieval can make paid embedding requests.

When configured namespaces are omitted, retrieval uses the named procedural context's search_namespaces, then all namespaces belonging to the account if none are declared. Explicit namespaces remain authoritative.

Python API and runtime ownership

from galet_prompt_builder import build_prompt_builder, PromptRequest

with build_prompt_builder(path="galet_prompt_builder_sample.json",
                          allow_create=False) as builder:
    compiled = builder.build(PromptRequest(
        account_name="junwin",
        conversation_id="YOUR_EXISTING_SESSION_ID",
        context_name="reading",
        current_input="What do my notes say about Jon Fosse?",
        semantic_namespaces=("books",),
    ))
    print(compiled.provider_messages)
    print(compiled.metrics)

The factory owns and closes memory it constructs. An application that already owns a runtime can borrow it instead, avoiding duplicate stores:

with build_prompt_builder({"config_version": 1},
                          memory_runtime=runtime) as builder:
    compiled = builder.build(request)
# runtime remains open and owned by the application.

Borrowing cannot be combined with another memory-config reference or provider factory. embedding_provider_factory remains available when constructing memory for tests or explicit host integrations. The factory normally honors the memory config's creation flags; allow_create=False disables creation for existing-store inspection. Neither prompt construction nor compilation ingests documents, creates sessions, publishes digests, or changes events.

For the Python API, an empty semantic_namespaces=() opts into context/all-account selection. PromptRequest retains its older default ("external",) for existing callers. PromptCompiler still accepts explicitly injected memory interfaces.

Configured digest retrieval resolves V3 root-relative locators and checks account ownership and invalidation before reading a file. Legacy metadata paths are used only in explicit V2 mode and remain confined to configured roots. Missing or unauthorized sources do not expose stored text snapshots. A borrowed runtime's explicit digest-search provider is preserved. Working state can be part of the shared runtime but is not inserted into prompts automatically.

Application boundary

Prompt-builder owns retrieval, policy, selection and rendering. This configured entry point means a host need not construct memory backends or adapt query models just to compile a prompt. Session creation, event append, archive/reset and digest publication remain application/memory operations. They are not moved into the prompt compiler. Applications may retain direct galet-memory use for those tasks and lend the same runtime to prompt-builder. No Lucy-specific imports or global runtime are introduced here.

Run locally

Keep the virtual environment active for the commands below. In a new shell, run source .venv/bin/activate from the checkout first.

Compile a prompt from Python

This complete example needs no database, credentials, or network calls. It compiles the supplied instructions and input without attaching memory stores:

python - <<'PY'
from galet_prompt_builder import PromptCompiler, PromptPolicy, PromptRequest

compiled = PromptCompiler().build(
    PromptRequest(
        account_name="demo",
        system_instructions=("You are a careful assistant.",),
        current_input="Explain what a prompt compiler does.",
        include_procedural=False,
        include_episodic=False,
        include_semantic=False,
        include_digests=False,
    ),
    PromptPolicy(),
)

print(compiled.text)
print(compiled.provider_messages)
print(compiled.metrics)
PY

This prints the assembled prompt and metrics; it does not send the prompt to an LLM. For memory-backed use, construct and pass the stores shown in Basic use.

Legacy comparison CLI without shared configuration

The editable installation also installs galet-prompt-run. Check its options:

python -m galet_prompt_builder.cli --help

To compile against your existing chat database, replace the account and chat name below with your stored values:

python -m galet_prompt_builder.cli "What should we do next?" \
  --account your-account \
  --storage-root "$HOME/lucy_storage" \
  --chat-name "Your existing chat name"

You can replace python -m galet_prompt_builder.cli with galet-prompt-run; both invoke the same runner. It expects an existing compatible <storage-root>/data/chat2.sqlite database and an existing session; installation does not create sample chat data. Use --db /path/to/chat2.sqlite to override the chat database and --storage-namespace if it is not data.

Pass your own account and storage root explicitly: the CLI currently defaults to account junwin and storage root /home/junwin/lucy_storage. The CLI prints a compiled prompt and metrics; it does not generate an LLM reply. See Prompt comparison CLI for memory and policy options.

When an embeddings database exists at the selected path, the runner also initializes vector recall for digests, even without --namespaces. That path needs the semantic extra and Galet embedding credentials; use --credential-path /path/to/credentials to supply the credential directory. Adding --namespaces also enables semantic document recall.

The package compiles caller-supplied system instructions and current input with procedural, episodic, and semantic memory from galet-memory. It applies independent section budgets, a total hard limit, relevance assessment, digest deduplication, deterministic selection, and detailed metrics.

The core compiler has no concept of host agents, handlers, attachment storage, or application-specific configuration. The configured facade above handles only prompt policy and the shared memory reference. The host adapts other values into PromptRequest, PromptBudgets, and PromptLimits.

Basic use

The examples below assume you have already constructed procedural_memory, episodic_memory, and semantic_memory stores for your application. Use the self-contained example in Run locally to verify installation first.

from galet_prompt_builder import (
    PromptBudgets,
    PromptCompiler,
    PromptLimits,
    PromptRequest,
)

compiler = PromptCompiler(
    procedural_memory=procedural_memory,
    episodic_memory=episodic_memory,
    digest_memory=episodic_memory,  # only when its digest_search provider is configured
    semantic_memory=semantic_memory,
)

compiled = compiler.compile(
    PromptRequest(
        account_name="demo",
        conversation_id="session-id",
        context_name="project",
        system_instructions=["You are a careful assistant."],
        current_input="What did we decide about storage?",
        semantic_namespaces=("documents",),
        semantic_score_threshold=0.30,
        episodic_event_kinds=(
            "user_message",
            "assistant_message",
            "session_digest",
        ),
        include_structured_episodic_events=False,
        episodic_digest_score_threshold=0.40,
    ),
    PromptBudgets(
        total_tokens=8000,
        procedural_tokens=1500,
        episodic_event_tokens=2000,
        episodic_digest_tokens=1000,
        semantic_tokens=2000,
        safety_margin_tokens=500,
    ),
    PromptLimits(
        maximum_total_tokens=16000,
        maximum_procedural_tokens=3000,
        maximum_episodic_event_tokens=4000,
        maximum_episodic_digest_tokens=2000,
        maximum_semantic_tokens=4000,
        maximum_events=6,
        maximum_digests=2,
        maximum_semantic_documents=3,
        maximum_episodic_event_chars=4000,
        maximum_episodic_digest_chars=1800,
        maximum_semantic_item_chars=1800,
    ),
)

provider_messages = compiled.provider_messages
metrics = compiled.metrics

The default relevance assessor is deterministic and makes no network calls. GaletRelevanceAssessor is available when an application explicitly wants an LLM-based assessment; all such calls go through Galet's LLMApi.

Prompt policy is explicit and agent-independent. Applications choose the overall and per-section token budgets, retrieval counts, event kinds, relevance thresholds, and per-item character caps. An agent may supply system instructions, but no agent object or application policy is required.

Applications can pass the same knobs used by galet-prompt-run through PromptPolicy, without constructing budgets and limits themselves:

from galet_prompt_builder import PromptCompiler, PromptPolicy, PromptRequest

compiled = PromptCompiler(
    episodic_memory=episodic_memory,
    digest_memory=episodic_memory,  # only when its digest_search provider is configured
    semantic_memory=semantic_memory,
    procedural_memory=procedural_memory,
).build(
    PromptRequest(account_name="junwin", current_input=question,
                  conversation_id=session_id, context_name="skinny",
                  semantic_namespaces=("books", "vol_6", "vol_7", "documents")),
    PromptPolicy(total_tokens=6000, safety_margin_tokens=500,
                 procedural_tokens=300, episodic_event_tokens=800,
                 episodic_digest_tokens=400, semantic_tokens=900,
                 maximum_events=6, maximum_digests=2,
                 maximum_semantic_documents=3,
                 digest_score_threshold=0.45,
                 semantic_score_threshold=0.35,
                 semantic_item_max_chars=1800),
)

Explicit episodic interfaces

The compiler's episodic_memory implements EventStore and the active snapshot operation from CurationStore; digest_memory is an optional, separately supplied DigestStore. The same SQLite/JSONL object can supply both when it has a configured digest_search provider. Omit digest_memory for recent-history-only use. No agent selector or combined EpisodicMemoryRequest/recall is used.

Recent messages come from get_recent_events, with kind filters applied before maximum_events. Complete JSON content reaches the compiler, which owns text rendering, truncation, relevance and token budgets. The active snapshot supplies only the current archive boundary summary as an additional required candidate; it does not select older pre-reset boundaries. That summary uses the event budget, independently of historical digest search. Search uses search_digests(account_name=..., query=..., count=...) and the separate digest budget. Both paths respect memory's invalidation/provenance rules.

Zero maximum_events or maximum_digests disables the corresponding read; negative counts are rejected. No conversation ID means no recent-history read, but explicit digest search can still run across account-owned sessions. Compilation remains read-only. A context reset retains storage history while removing prior events and boundary summaries from recent prompt context.

This is a breaking API/storage change requiring a fresh database. Supply digest_memory explicitly if historical digest search is wanted.

Prompt comparison CLI

The installed galet-prompt-run command compiles a prompt from an existing chat database and a new request. It resolves the chat's friendly name to its stored session ID and reads episodic history from the SQLite chat database.

By default it reads:

/home/junwin/lucy_storage/data/chat2.sqlite

Example:

galet-prompt-run \
  "What should we do next?" \
  --chat-name "Prompt Builder Work"

Use a different storage root or an explicit database when needed:

galet-prompt-run \
  "Compare this prompt" \
  --chat-name "Prompt Builder Work" \
  --storage-root /srv/lucy_storage

galet-prompt-run \
  "Compare this prompt" \
  --chat-name "Prompt Builder Work" \
  --db /tmp/chat2.sqlite \
  --format json

The command is read-only. It fails if the database or friendly chat name does not exist, and it reports duplicate friendly names instead of guessing. The runner includes episodic events and digests by default.

The runner also loads the chat's stored project context, if present, from <storage-root>/<storage-namespace>/contexts/<account>/<context-name>.md. Imported skills come from the sibling skills/<account> directory. To try a different named context, override the chat's value explicitly:

galet-prompt-run "What should we do next?" \
  --chat-name "Prompt Builder Work" \
  --context-name galet-memory \
  --procedural-tokens 1000

Use --procedural-root /path/to/root when the contexts and skills live elsewhere. Use --procedural-layout scoped for galet-memory's global/account/ project directory layout, and --project-name to include a project scope. An explicitly named context that is missing produces an error; recall never creates a file. Set --procedural-tokens 0 to omit procedural content for a comparison run.

Semantic recall is opt-in. Supply one or more namespaces to query the embeddings-v2.sqlite store:

galet-prompt-run \
  "What did I write about attention?" \
  --chat-name "Prompt Builder Work" \
  --namespaces vol_6 vol_7 documents

The comparison runner uses deliberately compact defaults:

  • 8,000 total tokens with a 500-token safety margin
  • 1,000 project-context and skill tokens
  • 1,000 recent-event tokens across at most 6 events
  • 500 digest tokens across at most 2 digests
  • 1,000 semantic tokens across at most 3 documents
  • semantic score threshold 0.30
  • digest score threshold 0.40
  • conversational event kinds only; structured tool payloads are excluded

Every policy value can be stated explicitly:

galet-prompt-run \
  "What did I write about attention?" \
  --chat-name "Prompt Builder Work" \
  --namespaces vol_6 vol_7 documents \
  --total-tokens 6000 \
  --safety-margin-tokens 500 \
  --episodic-event-tokens 800 \
  --max-events 6 \
  --episodic-digest-tokens 400 \
  --max-digests 2 \
  --digest-score-threshold 0.45 \
  --semantic-tokens 900 \
  --semantic-top-k 3 \
  --semantic-score-threshold 0.35 \
  --semantic-item-max-chars 1800

With no --namespaces, document semantic recall is disabled. When the embedding database exists, the runner can still query its digests namespace for archived, published session digests. A session_digest event in the current chat appears as an episodic event; it does not by itself create an archived digest candidate. Archives must be published with an embedding and readable digest document to be recalled from other sessions. Semantic mode defaults to /home/junwin/lucy_storage/data/embeddings-v2.sqlite; use --embedding-db to override it and install the optional dependency with python -m pip install -e ".[semantic]". Galet supplies the query embedding, using its normal credential configuration or the directory passed to --credential-path.

The text report includes a content-safe candidate decision table. It shows each candidate ID, source, raw relevance score, original/final token cost, and whether it was selected or rejected by the relevance threshold or token budget. The JSON report exposes the same data under metrics.candidates. Rejected candidates still count as retrieved and dropped in their section metrics, making threshold tuning visible without copying document or chat content into diagnostics.

Dependency rule

Applications may depend on galet-prompt-builder; the package must never depend on an application.

The package depends on the neutral interfaces from galet-memory. It never opens memory databases itself and prompt compilation never mutates memory.

Metadata

Release files for galet-prompt-builder 0.1.23

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for galet-prompt-builder 0.1.23
File Size Uploaded Provenance Actions
galet_prompt_builder-0.1.23.tar.gz 44.2 kB Without provenance Details for galet_prompt_builder-0.1.23.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for galet-prompt-builder 0.1.23
File Interpreter ABI Platform Actions
galet_prompt_builder-0.1.23-py3-none-any.whl Python 3 none any Details for galet_prompt_builder-0.1.23-py3-none-any.whl

Total release size: 75.2 kB

Release files / galet_prompt_builder-0.1.23.tar.gz

Download URL galet_prompt_builder-0.1.23.tar.gz
Size 44.2 kB
Tags Source
SHA-256 checksum
How to use checksums
9ab838abaabfae09550302b2034ef36f41d5cc6fc6a6674319936c9b8b8d2e09
BLAKE2b-256 checksum
How to use checksums
a4833cb80cdcf9ed00c2154de1876f8b77625b7b6e66d0470d1ac9422f6d240d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / galet_prompt_builder-0.1.23-py3-none-any.whl

Download URL galet_prompt_builder-0.1.23-py3-none-any.whl
Size 31.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2531ccad67899346989c058a8eb10d8dc7192f8463861a10884622294e7835c7
BLAKE2b-256 checksum
How to use checksums
29ceab003a74b8ea179fdc8f8213350d0850022dd4fa48b81e8924851c772d24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for galet-prompt-builder 0.1.23

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page