Building GlossWise on HeavenBase

A glossary is just a list until the rest of your app can ask it questions.

Project case study - HeavenBase Team - July 28, 2026 - ~1,700 words - ~9 min read

GlossWise stores approved terms, translation rules, and examples, then prepares a compact brief for a calling agent or application. It is a Python SDK, CLI, HeavenBase extension, agent Skill, and MCP server. The host agent can keep its own translation model, while the direct CLI uses an explicit HeavenBase LLM preset. That product shape makes GlossWise a useful stress test. It needs durable structured data, exact phrase matching, optional semantic search, graph relationships, workspace isolation, configuration, LLM calls, and several interfaces. The interesting question is not whether HeavenBase can store a term. It is how much application architecture disappears when all those surfaces share one model.

1. Motivation

A project can begin with a Python mapping:

preferred_terms = {
    "rate limit": "速率限制",
    "workspace": "工作区",
}

That works until a term needs aliases, prohibited forms, language scopes, project domains, priorities, examples, relationships, audit fields, or search evidence. A second file may add rules; a vector database may add similarity; an MCP wrapper may add agent access. Soon each interface reconstructs a slightly different idea of “the glossary.” GlossWise keeps one explicit domain instead. Terms represent language-neutral concepts. Forms store language-specific preferred, alias, typo, or prohibited text. Rules carry scoped instructions. Examples preserve reviewed source/target pairs. Every surface calls the same workspace-bound service. This matters because translation consistency is a state problem before it is a model problem. A better prompt cannot retrieve a decision that the application never stored coherently.

2. Model the Domain Once

GlossWise defines ordinary HeavenBase entities. This shortened excerpt shows why one form is more than a string:

import heavenbase as hb


class GlossWiseTermForm(hb.Entity):
    identifier = "glosswise-term-form"

    term_id = hb.field(hb.Identifier["glosswise-term"])
    lang = hb.field(hb.ShortText)
    role = hb.field(hb.ShortText)
    text = hb.field(hb.ShortText)
    triggers = (
        hb.field(hb.Array[hb.ShortText])
        .default([])
        .store(strategy=hb.SparseGramIndex(normalizer="default"))
    )
    embedding = hb.field(hb.Vector[3]).optional()
    status = hb.field(hb.ShortText).default("active")

The declaration carries identity, validation, descriptions, and placement intent together. SparseGramIndex supports reverse containment, so a stored phrase can be found inside a longer document. The optional vector supports semantic candidates when an embedding policy is configured. Scalar fields keep exact language, role, and status filters inspectable. GlossWise also uses SideTable for structured arrays and GraphEdge for typed relationships between terms, rules, and examples. HeavenBase keeps those choices behind one entity and query surface instead of making the application coordinate SQL, vector, and graph clients directly.

GlossWise still owns domain validation. HeavenBase knows how to store and query role; GlossWise decides that preferred, alias, typo, and prohibited are the accepted values.

3. Ship One Module Folder

GlossWise contributes more than entity classes. Its package root is one HeavenBase module folder:

src/glosswise/
├── entities.py
├── service.py
├── mcp/
├── meta.yaml
└── ...

The meta.yaml descriptor declares four entities, the glosswise extension, a Toolkit family, and three MCP profiles. A compact fragment looks like this:

manifest_version: 2
coordinate: glosswise/glosswise
version: 0.1.0.5
bundle: glosswise
items:
  - kind: entity
    identifier: glosswise-term-form
    source: path
    target: {module: entities, qualname: GlossWiseTermForm}
  - kind: extension
    identifier: glosswise
    source: inline
    target: definition

Built-in and external modules use the same descriptor, Registry publication, resolution, and lifecycle. Installation captures path-based code into a verified content-addressed artifact. Inspection can read records without importing the implementation, while activation resolves exact declared dependencies. For a product author, that is a useful boundary: package metadata explains what the product contributes, and Python explains how those pieces behave.

4. Attach One Workspace API

The extension attaches GlossWiseService as workspace.glosswise. Application setup can therefore stay short:

import heavenbase as hb
from glosswise import install


context = hb.Context.load()
install(context)

ws = hb.HeavenBase(
    "glosswise-demo",
    backends={
        "main": {
            "type": "sqlite",
            "database": "glosswise.db",
        }
    },
    context=context,
)
ws.enable_extension("glosswise")

service = ws.glosswise

The Context owns machine configuration, installed module records, and workspace identity. The workspace owns the selected extension roots, canonical entity classes, storage plans, and rows. The attached service owns GlossWise rules such as normalization, conflict handling, bounded search, and response envelopes. This split avoids two common traps. GlossWise does not hide business logic in CLI commands, and it does not depend on ambient process state when it already has an owning Context.

5. Query Exact and Semantic Evidence Together

The service composes normal HeavenBase queries. A lexical scan can ask whether stored triggers appear inside a longer source string:

TermForm = ws.entities["glosswise-term-form"]

hits = (
    ws.query(TermForm)
    .where(TermForm.triggers.contained_in("Retry after the rate limit resets."))
    .where(TermForm.status == "active")
    .select("term_id", "lang", "role", "text", "match")
    .execute()
    .rows()
)

The result includes object_id plus match evidence. GlossWise can then hydrate the parent term, apply language and domain policy, combine optional vector candidates, and explain which stored decisions entered a translation brief. Query.explain() is as important as execute(). A declared capability is not proof that one concrete field runs natively on one concrete backend. GlossWise tests the chosen handler mode and keeps bounded fallbacks honest instead of turning a green setup check into a performance promise.

6. Reuse the Same Core Across Interfaces

GlossWise exposes the same application through:

GlossWiseApp for Python callers
glosswise for terminal workflows
namespaced glosswise_* MCP tools for agents
a packaged Skill that teaches agents when and how to call those tools

The CLI and MCP functions are thin adapters. They select a workspace, validate boundary inputs, call workspace.glosswise, and serialize a bounded result. They do not reimplement term search or curation. The module descriptor makes the MCP surface inspectable. The read profile exposes search, scans, translation briefs, and Skill access. The curator profile extends it with validated writes. The local profile adds only explicitly authorized file ranges and PDF OCR tools. This is where HeavenBase pays off most visibly: the product does not need a Python repository, a CLI repository, an MCP repository, and a fourth schema that tries to keep them in agreement.

7. Keep Model Choice Visible

GlossWise prepares context; it does not pretend that context and generation are the same job. Host agents translate with their own model. The direct command uses hb.LLMSession with a named preset and reports the resolved gateway, provider, model, and model id. Reusable translation and OCR instructions are rendered through hb.Prompt. Page images flow through the configured vision-capable preset, while GlossWise owns file authorization, page ranges, temporary document handles, and cleanup. That division is deliberate. HeavenBase supplies Context-bound LLM and prompt infrastructure. GlossWise supplies the product policy that says what may be read, what must be disclosed, and which terminology evidence must reach the model.

8. What HeavenBase Removed—and What It Did Not

Concern	HeavenBase supplies	GlossWise still owns
Data model	Entity schemas, identity, validation, placement	Terminology semantics and cross-record invariants
Persistence	Workspace lifecycle and backend routing	Managed workspace defaults and product migrations
Retrieval	Typed filters, Sparse GRAM, vectors, graph traversal	Ranking, thresholds, conflicts, and bounded briefs
Extension packaging	Module descriptors, Registry resolution, artifacts	GlossWise records and compatibility declarations
Agent access	Toolkit families, MCP profiles, serializers	Tool names, authorization policy, and result contracts
Generation	Context-bound LLM sessions and prompts	Translation workflow, disclosure, and uncertainty modes

The table is the practical benefit of a framework boundary: HeavenBase removes repeated infrastructure without swallowing the application.

9. Lessons from a Real External Project

GlossWise also found honest gaps. External distribution and trust are still local and installer-driven. Workspace manifests do not yet export extension-owned configuration such as language hints. Short-lived CLI processes pay noticeable schema-replay cost. Some filtered vector and Sparse GRAM paths need explicit bounds or project-side workarounds. Those limits are useful evidence, not a failed demo. A framework becomes dependable when an external project can show both the code it deleted and the policy it still had to write. The strongest result is architectural: GlossWise can remain a terminology product. Its central object is a workspace-bound service, its domain is declared once, and every interface is an adapter over that owner. HeavenBase makes that ordinary shape possible across storage and agent boundaries.

10. Try GlossWise

Install the current source and create a workspace with your normal language set:

python -m pip install "git+https://github.com/Magolor/GlossWise.git"
glosswise setup '["en","zh"]'
glosswise ws get

Then connect the MCP server to a supported agent or use the Python SDK. The GlossWise repository includes the complete quickstart, external-module tests, MCP profiles, and the project’s detailed HeavenBase integration feedback.

Summary

GlossWise models terms, rules, examples, and evidence once.
HeavenBase turns that model into storage, search, Extension, CLI, Skill, and MCP surfaces.
Product-specific curation stays in GlossWise while infrastructure ownership stays visible.

Further Exploration

Related resources:

Entities - Define the shared domain model
Backends - Route fields and inspect execution evidence
Extensions - Publish one external module folder
Toolkits - Build profile-scoped agent tools
LLM Overview - Resolve visible model presets
GlossWise on GitHub - Read the complete product and tests

​1. Motivation

​2. Model the Domain Once

​3. Ship One Module Folder

​4. Attach One Workspace API

​5. Query Exact and Semantic Evidence Together

​6. Reuse the Same Core Across Interfaces

​7. Keep Model Choice Visible

​8. What HeavenBase Removed—and What It Did Not

​9. Lessons from a Real External Project

​10. Try GlossWise

​Summary

​Further Exploration

1. Motivation

2. Model the Domain Once

3. Ship One Module Folder

4. Attach One Workspace API

5. Query Exact and Semantic Evidence Together

6. Reuse the Same Core Across Interfaces

7. Keep Model Choice Visible

8. What HeavenBase Removed—and What It Did Not

9. Lessons from a Real External Project

10. Try GlossWise

Summary

Further Exploration