> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Building GlossWise on HeavenBase

> How GlossWise uses HeavenBase entities, modules, workspace APIs, search, LLMs, and MCP to become a complete terminology product.

<Note>
  *A glossary is just a list until the rest of your app can ask it questions.*
</Note>

<Info>
  Project case study - HeavenBase Team - July 28, 2026 - \~1,700 words - \~9 min read
</Info>

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.

<br />

## 1. Motivation

A project can begin with a Python mapping:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 2. Model the Domain Once

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<Tip>
  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.
</Tip>

<br />

## 3. Ship One Module Folder

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 4. Attach One Workspace API

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 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.

<br />

## 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.

<br />

## 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.

<br />

## 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.

<br />

## 10. Try GlossWise

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://github.com/Magolor/GlossWise) includes the complete quickstart, external-module tests, MCP profiles, and the project’s detailed HeavenBase integration feedback.

<br />

## 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.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Entities](/features/entities) - Define the shared domain model
  * [Backends](/features/backends) - Route fields and inspect execution evidence
  * [Extensions](/features/extensions) - Publish one external module folder
  * [Toolkits](/features/toolkits) - Build profile-scoped agent tools
  * [LLM Overview](/features/llm/overview) - Resolve visible model presets
  * [GlossWise on GitHub](https://github.com/Magolor/GlossWise) - Read the complete product and tests
</Tip>

<br />