kenschae/thoth-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
thoth-gateway/.thoth/30-glossary.md
T

30 KiB
Raw Permalink Blame History

Thoth Gateway Infrastructure Glossary

Version: 0.1.0 Status: Canonical Terminology Last Updated: 2026-07-28

Purpose

This glossary defines the canonical vocabulary used throughout the Thoth Gateway infrastructure project.

Its purpose is to ensure that:

  • Human operators.
  • Developers.
  • AI assistants.
  • Autonomous agents.
  • Documentation.
  • Scripts.
  • Service definitions.

all use the same terms consistently.

Where possible, each concept has one preferred term.

A

Access Policy

The rules that determine whether an identity may discover, retrieve, view, or use a knowledge artifact or service.

Access Policy is evaluated before restricted content is disclosed.

Access Policy is distinct from Egress Policy and Execution Policy.

Agent

A governed software component that performs or coordinates work on behalf of a user or system.

An Agent operates with:

  • A defined identity.
  • A defined task.
  • A permitted knowledge scope.
  • A permitted tool scope.
  • Execution limits.
  • Provider restrictions.
  • Audit requirements.

An Agent does not receive unrestricted authority by default.

Agent Runtime

The Gateway component responsible for coordinating Agent execution.

The Agent Runtime may manage:

  • Task state.
  • Tool calls.
  • Model calls.
  • Approval steps.
  • Audit events.
  • Execution limits.
  • Failure handling.

The Agent Runtime does not itself grant authority.

Authority is supplied through policy and delegation.

Application Persistence

Mutable state maintained by a specific hosted service.

Examples include:

  • User accounts.
  • Conversation history.
  • Service settings.
  • Internal databases.
  • Application-specific files.

Application Persistence is not automatically a Canonical Artifact.

Architecture Decision Record

A document that records a significant architectural decision and its rationale.

An Architecture Decision Record typically contains:

  • Context.
  • Decision.
  • Alternatives.
  • Consequences.
  • Status.

Preferred abbreviation:

ADR

An ADR should be created when a decision establishes a persistent boundary, dependency, storage rule, security rule, or operational standard.

Artifact

Any file, record, configuration item, image, model, log, dataset, or document managed or referenced by the infrastructure project.

Artifacts may be:

  • Canonical.
  • Generated.
  • Operational.
  • Runtime.
  • Deployment-related.

The more specific term should be used when the artifact category is known.

Audit Event

A record of a security-relevant or governance-relevant action.

Examples include:

  • A user retrieving restricted content.
  • An Agent invoking a tool.
  • Information being routed to a frontier provider.
  • A policy decision being evaluated.
  • A privileged configuration change.
  • A failed authorization attempt.

Audit Events should identify what occurred, who or what initiated it, and when it occurred.

Authorization

The process of deciding whether an authenticated identity may perform a requested action.

Authorization answers:

Is this identity allowed to do this?

Authorization is distinct from Authentication.

B

Backup Artifact

A generated copy of runtime data, configuration, secrets, or knowledge created for recovery purposes.

Backup Artifacts are stored outside the infrastructure Git repository.

A Backup Artifact is useful only when it can be restored and verified.

Base Commissioning

The process of bringing a host into its documented minimum operational state.

For Gateway, Base Commissioning includes:

  • Operating-system readiness.
  • Network identity.
  • Storage preparation.
  • Docker operation.
  • Repository initialization.
  • Service deployment.
  • Dependency verification.
  • End-to-end testing.

Installation alone does not constitute commissioning.

C

Canonical Artifact

An artifact considered the permanent source of truth.

Within the wider Project Thoth environment, Canonical Artifacts may include:

  • Preserved conversations.
  • Original attachments.
  • Images.
  • Audio.
  • Video.
  • Canonical Markdown documents.

Infrastructure application state is not automatically canonical.

Canonical Endpoint

The approved network address used by services to reach a dependency.

Examples include:

http://thoth-oracle:11434

or, during initial commissioning:

http://192.168.5.52:11434

Stable internal DNS names are preferred over hard-coded addresses when available.

Canonical Term

The preferred word or phrase used for a concept throughout the project.

A Canonical Term should be used consistently in:

  • Documentation.
  • Code.
  • Scripts.
  • Configuration.
  • Work Orders.
  • Architecture Decision Records.
  • Agent instructions.

Commissioning

The process of bringing a system or service into a verified operational state.

Commissioning includes:

  • Installation.
  • Configuration.
  • Persistence testing.
  • Dependency testing.
  • Documentation.
  • Recovery awareness.
  • End-to-end verification.

Commissioning is stronger than Deployment.

Compose Definition

The complete Docker Compose configuration for a Service Project.

The canonical filename is:

compose.yaml

Avoid using docker-compose.yml for new Service Projects.

Configuration Template

A committed configuration file that documents required settings without containing environment-specific secrets.

Examples include:

.env.example
config.example.yaml
settings.template.json

A Configuration Template is safe to store in Git.

Consumer

A human or software component that reads, retrieves, processes, or reasons over knowledge.

Examples include:

  • Open WebUI.
  • A local model.
  • A frontier model.
  • A search service.
  • An Agent.
  • A human reader.

Consumers do not own the archive.

Container

An isolated runtime instance created from a Container Image.

A Container is ephemeral unless its required state is stored through explicit persistence.

A running Container does not by itself prove that the service is healthy.

Container Image

A packaged, immutable filesystem and configuration template used to create Containers.

Container Images should be selected deliberately and pinned where operational stability requires it.

Container Runtime

The software responsible for executing Containers.

The current Container Runtime is Docker Engine.

Docker Engine is an implementation choice, not an architectural requirement.

Context Package

A structured set of authorized information prepared for a specific AI or Agent request.

A Context Package may include:

  • User instructions.
  • Retrieved source excerpts.
  • Metadata.
  • Citations.
  • Policy constraints.
  • Tool results.
  • Provider-specific formatting.

A Context Package must contain only information approved for the target Consumer.

Context Packager

The component responsible for assembling a Context Package.

The Context Packager operates after retrieval and authorization.

It does not independently grant access.

D

Data Directory

A host directory used to store Persistent Runtime Data for a Service Project.

Example:

/srv/thoth/data/open-webui

Data Directories are not stored inside the Git repository.

Delegated Authority

The specific permission granted to an Agent to act on behalf of a user or system.

Delegated Authority may limit:

  • Duration.
  • Knowledge scope.
  • Tool scope.
  • Target systems.
  • Transaction value.
  • Approval requirements.
  • Provider use.

An Agent must not infer Delegated Authority from the user’s general identity.

Deployment

The act of creating or updating a service from its Deployment Definition.

Deployment may include:

  • Pulling images.
  • Creating networks.
  • Creating Containers.
  • Attaching volumes.
  • Loading configuration.
  • Starting services.

Deployment does not imply successful commissioning.

Deployment Definition

The version-controlled files that describe how a Service Project is deployed.

A Deployment Definition may include:

  • compose.yaml
  • Configuration templates.
  • Health checks.
  • Startup scripts.
  • Network declarations.
  • Volume declarations.

Deployment Definitions should be reproducible.

Derived Artifact

An artifact generated from Canonical Artifacts or other controlled inputs.

Examples include:

  • Embeddings.
  • Search indexes.
  • Summaries.
  • Manifests.
  • Harvests.
  • Relationship data.

Derived Artifacts may be regenerated.

Direct Inference

An inference request sent to a Model Provider without first retrieving knowledge from the Project Thoth repository.

The initial Open WebUI-to-Oracle workflow is a Direct Inference workflow.

Docker Compose

The Docker CLI capability used to define and operate multi-container Service Projects.

The preferred command form is:

docker compose

Avoid the legacy command:

docker-compose

E

Egress

The movement of information from one trust boundary to another.

Examples include:

  • Gateway to a frontier AI provider.
  • A local service to an external API.
  • A container to the public internet.
  • A user downloading restricted content.

Egress must be governed by policy.

Egress Policy

The rules that determine whether information may leave a defined environment or trust boundary.

Egress Policy may consider:

  • Data classification.
  • Provider approval.
  • User identity.
  • Purpose.
  • De-identification.
  • Retention.
  • Jurisdiction.
  • Audit requirements.

Egress Policy is distinct from Access Policy.

End-to-End Test

A test that verifies the complete intended workflow across all participating components.

The initial Gateway End-to-End Test is:

Browser
    ↓
Open WebUI
    ↓
Gateway
    ↓
Oracle
    ↓
Gemma 4
    ↓
Gateway
    ↓
Browser

An End-to-End Test verifies capability rather than isolated component health.

Endpoint

A network-accessible interface exposed by a service.

Examples include:

  • HTTP APIs.
  • Web interfaces.
  • Health endpoints.
  • Model endpoints.

An Endpoint should expose only the access required for its responsibility.

Environment Configuration

Deployment-specific settings that vary between environments.

Examples include:

  • Hostnames.
  • IP addresses.
  • Port assignments.
  • Storage paths.
  • Internal domain names.

Environment Configuration may be stored in an uncommitted .env file when appropriate.

Execution Policy

The rules that determine what actions an Agent or service may perform.

Execution Policy governs:

  • Tool invocation.
  • System modification.
  • Credential use.
  • Approval requirements.
  • Transaction limits.
  • Audit requirements.

Execution Policy is distinct from Access Policy and Egress Policy.

F

Frontier Provider

An externally hosted AI provider offering remote inference.

A Frontier Provider may provide capabilities beyond the current local models.

Information may be sent to a Frontier Provider only when Egress Policy permits it.

Full-Text Search

A deterministic retrieval method that finds text based on words, phrases, and indexed document content.

Full-Text Search should remain available independently of AI-assisted retrieval where practical.

G

Gateway

The orchestration and service-interface host for the Project Thoth environment.

Canonical hostname:

thoth-gateway

Gateway responsibilities include:

  • Hosting Service Projects.
  • Providing user interfaces.
  • Coordinating retrieval.
  • Applying policy.
  • Preparing context.
  • Routing inference.
  • Coordinating Agents.
  • Integrating external systems.

Gateway does not own the archive and is not the primary local inference host.

Gateway Service Layer

The collection of services hosted by or coordinated through Gateway.

The Gateway Service Layer may include:

  • Open WebUI.
  • Retrieval services.
  • Policy services.
  • Agent Runtime.
  • Monitoring.
  • Integrations.
  • Context packaging.
  • Provider interfaces.

Generated Artifact

See Derived Artifact.

H

Health Check

A deterministic test that confirms whether a component is operating as expected.

Health Checks may test:

  • Process availability.
  • Endpoint response.
  • Dependency access.
  • Storage access.
  • Model availability.
  • Workflow completion.

A Health Check should produce actionable results.

Host

A physical machine or virtual machine that runs infrastructure services.

Current Hosts include:

  • thoth-gateway
  • thoth-oracle

Host Health

The operational condition of the underlying Host.

Host Health may include:

  • Operating-system status.
  • Network availability.
  • Storage availability.
  • Memory pressure.
  • CPU load.
  • Service-manager status.
  • Reboot persistence.

I

Identity

A known user, service, Agent, or system principal.

Identity is used as the basis for Authentication, Authorization, Delegated Authority, and Audit Events.

Inference

The act of generating a model response from supplied instructions and context.

Inference may be:

  • Local.
  • Frontier.
  • Direct.
  • Knowledge-augmented.
  • Agent-mediated.

Inference output is not automatically a Canonical Artifact.

Inference Host

A Host primarily responsible for loading and executing AI models.

The current local Inference Host is Oracle.

Infrastructure Repository

The Git repository containing the reproducible knowledge required to deploy and operate Gateway services.

Canonical location:

/srv/thoth/containers

The Infrastructure Repository contains definitions and documentation, not mutable service data.

Integration

A connection between Gateway and an external service, repository, provider, or application.

Integrations should use documented interfaces and least-privilege access.

K

Knowledge-Augmented Inference

An inference workflow in which authorized information is retrieved from the Project Thoth knowledge environment and supplied to a model as context.

Knowledge-Augmented Inference includes:

  • Search.
  • Authorization.
  • Source Resolution.
  • Context Packaging.
  • Provider routing.
  • Citation preservation.

Use this term when describing the complete governed workflow.

Avoid using RAG when the broader policy and source-resolution responsibilities are material.

Knowledge Consumer

A Consumer that reads or reasons over Project Thoth knowledge.

Examples include:

  • Local models.
  • Frontier models.
  • Search tools.
  • Agents.
  • Human users.

A Knowledge Consumer does not own canonical knowledge.

Knowledge Repository

The organized collection of Canonical Artifacts, Derived Artifacts, metadata, relationships, and retrieval structures managed by Project Thoth.

The Knowledge Repository remains independent of any model, interface, or provider.

L

Local Inference

Inference executed within the locally controlled environment.

The initial Local Inference path uses:

Gateway → Oracle → Ollama → Gemma 4

Local Inference is the preferred private processing path when capable and permitted.

Local Provider

A Model Provider hosted within the locally controlled environment.

The initial Local Provider is Oracle through Ollama.

Log

An operational record produced by a Host, service, Container, or application.

Logs should support:

  • Diagnosis.
  • Recovery.
  • Monitoring.
  • Audit where appropriate.

Logs are Operational Artifacts, not Canonical Artifacts.

M

Model

A machine-learning system used to perform inference.

Examples include:

  • Gemma 4.
  • Future local models.
  • Frontier-provider models.

A Model is replaceable and must not become the owner of knowledge.

Model Endpoint

An Endpoint through which a Consumer sends inference requests to a Model Provider.

The initial Model Endpoint is:

http://192.168.5.52:11434

A stable internal DNS name should replace the address when available.

Model Provider

A service that exposes one or more Models through a defined interface.

Model Providers may be:

  • Local.
  • Frontier.
  • Specialized.

Consumers should depend on provider interfaces rather than model-specific infrastructure where practical.

Mutable State

Data that changes during normal service operation.

Examples include:

  • Databases.
  • Conversation history.
  • User settings.
  • Queues.
  • Caches.
  • Runtime indexes.

Mutable State must remain separate from the Git-managed Deployment Definition.

N

Network Boundary

A point where communication crosses between Hosts, networks, Containers, or external systems.

Network Boundaries require explicit consideration of:

  • Exposure.
  • Authentication.
  • Authorization.
  • Encryption.
  • Logging.
  • Trust.

O

Observability

The ability to understand system behavior through health checks, logs, metrics, traces, and operational evidence.

Observability should support diagnosis and recovery rather than produce data without purpose.

Open WebUI

The initial browser-based AI interaction service hosted on Gateway.

Open WebUI provides:

  • Conversation interfaces.
  • Model selection.
  • Model requests.
  • Response display.
  • Application-specific persistence.

Open WebUI is replaceable and does not own canonical Project Thoth knowledge.

Operational Artifact

An artifact generated to operate, diagnose, audit, or recover the infrastructure.

Examples include:

  • Logs.
  • Health reports.
  • Audit Events.
  • Backup reports.
  • Deployment records.

Operational Artifacts are distinct from Canonical and Derived Artifacts.

Oracle

The local Inference Host for the Project Thoth environment.

Canonical hostname:

thoth-oracle

Current address:

192.168.5.52

Oracle responsibilities include:

  • Hosting the local model runtime.
  • Loading Models.
  • Performing GPU inference.
  • Exposing Local Provider endpoints.
  • Reporting model availability.

Oracle does not own the knowledge archive or user interface.

Orchestration

The coordination of services, tasks, tools, policies, and information flows.

Gateway performs orchestration.

Oracle performs inference.

P

Persistent Runtime Data

Mutable State that must survive Container recreation, service restart, or Host reboot.

Persistent Runtime Data is stored outside the Infrastructure Repository.

Example:

/srv/thoth/data/open-webui

Policy Layer

The Gateway capability responsible for evaluating Access Policy, Egress Policy, and Execution Policy.

The Policy Layer makes deterministic authorization decisions where practical.

It must not delegate final authority to a language model.

Provider Interface

A stable abstraction through which Gateway services communicate with a Model Provider.

A Provider Interface should hide implementation-specific details where practical.

Provider Interfaces preserve the ability to replace Ollama, a model family, or a frontier provider.

Provider Routing

The process of selecting an approved Model Provider for a request.

Provider Routing may consider:

  • Information classification.
  • User permissions.
  • Task requirements.
  • Model capability.
  • Local availability.
  • Cost.
  • Latency.
  • Egress restrictions.

Provider Routing occurs after policy evaluation.

Prompt Injection

An attempt to manipulate an AI system through instructions embedded in user input, retrieved content, files, tool output, or external data.

Prompt Injection is treated as a trust-boundary and authority problem.

Retrieved content must not be allowed to expand permissions or override system policy.

R

Recovery Procedure

The documented process for restoring a Host, Service Project, or workflow after failure or loss.

A Recovery Procedure should identify:

  • Required deployment files.
  • Required configuration.
  • Required secrets.
  • Required runtime data.
  • Restore sequence.
  • Verification steps.
  • Known limitations.

Repository Boundary

The distinction between content stored inside the Infrastructure Repository and content stored outside it.

Inside the Repository:

  • Deployment Definitions.
  • Documentation.
  • Templates.
  • Scripts.
  • Project self-description.

Outside the Repository:

  • Secrets.
  • Mutable State.
  • Logs.
  • Backups.
  • Model files.
  • Application databases.

Retrieval

The process of locating and obtaining information for an authorized Consumer.

Retrieval includes more than Search.

A governed Retrieval flow may include:

  • Search.
  • Authorization.
  • Source Resolution.
  • Content filtering.
  • Context Packaging.

Retrieval Service

A Gateway service responsible for locating and resolving knowledge.

A Retrieval Service does not grant access merely because it found relevant content.

Runtime Configuration

Configuration consumed by a running service.

Runtime Configuration may include:

  • Environment variables.
  • Mounted configuration files.
  • Command-line arguments.
  • Secrets.

Runtime Configuration may be partly generated from Configuration Templates.

Runtime Data

See Persistent Runtime Data or Mutable State, depending on whether persistence is required.

Avoid using Runtime Data when a more precise term is available.

S

Search

The process of finding candidate knowledge based on text, metadata, relationships, or semantic similarity.

Search does not itself grant permission to retrieve or disclose content.

Secret

Sensitive information that grants access or protects confidentiality.

Examples include:

  • Passwords.
  • API keys.
  • Access tokens.
  • Private keys.
  • Encryption keys.
  • Database credentials.

Secrets must never be committed to Git.

Service

A software capability exposed through a process, Container, API, or interface.

Examples include:

  • Open WebUI.
  • Ollama.
  • A Retrieval Service.
  • A Policy Layer.
  • An Agent Runtime.

Service Data

Persistent Runtime Data owned by a specific Service Project.

Example:

/srv/thoth/data/open-webui

Service Data should be backed up according to the service’s recovery requirements.

Service Dependency

A Host, Service, Endpoint, storage location, credential, or network path required by another service.

Examples include:

  • Open WebUI depending on Oracle.
  • Oracle depending on GPU drivers.
  • A Retrieval Service depending on the Knowledge Repository.

Dependencies must be documented and testable.

Service Interface

The defined mechanism through which users or other services interact with a Service.

Examples include:

  • HTTP API.
  • Browser interface.
  • File interface.
  • Command-line interface.
  • Message queue.

Service Project

A repository directory that defines one deployable containerized application or closely related service group.

A Service Project normally contains:

service-name/
├── compose.yaml
├── .env.example
├── README.md
├── config/
└── scripts/

Each Service Project should have one clear responsibility.

Source Resolution

The process of retrieving a Canonical Artifact from its authoritative location after Search and Authorization.

Source Resolution may use:

  • File paths.
  • URLs.
  • Object identifiers.
  • Repository addresses.
  • Connector-specific references.

Search results may contain metadata and an address rather than a duplicate of the source artifact.

Stable Interface

An interface intended to remain consistent even when the underlying implementation changes.

Stable Interfaces are preferred at architectural boundaries.

T

Thoth Gateway Infrastructure

The complete infrastructure project responsible for documenting, deploying, and operating Gateway-hosted services.

It includes:

  • The Infrastructure Repository.
  • Gateway Service Projects.
  • Runtime directories.
  • Service documentation.
  • Architectural documents.
  • Operational procedures.

Trust Boundary

A boundary across which identity, permissions, data, or execution authority must be reevaluated.

Examples include:

  • Browser to Gateway.
  • Gateway to Knowledge Repository.
  • Gateway to Oracle.
  • Gateway to a Frontier Provider.
  • Container to Host.
  • Retrieved content to Agent Runtime.

U

User Interface

A human-facing interface through which a user interacts with Gateway services.

The initial User Interface is Open WebUI.

The User Interface is replaceable and does not own canonical knowledge.

V

Verification

The process of proving that a component or workflow behaves as intended.

Verification may include:

  • Command output.
  • Health checks.
  • Persistent-state tests.
  • Dependency tests.
  • End-to-End Tests.
  • Recovery tests.

Verification requires evidence.

Volume

A Docker-managed or host-mounted storage location attached to a Container.

Volumes may store Persistent Runtime Data.

Where host visibility and recovery clarity are important, explicit host-mounted Data Directories may be preferred.

W

Work Order

A structured engineering document describing a discrete unit of implementation work.

A Work Order should contain:

  • Context.
  • Objective.
  • Constraints.
  • Deliverables.
  • Acceptance criteria.
  • Architectural references.

Work Orders should be executable by either human developers or AI assistants with minimal additional explanation.

Canonical Terminology

The following preferred terms should be used consistently.

Preferred Avoid
Gateway Docker server
Oracle AI box
Service Project Docker app folder
Compose Definition Docker Compose file
Deployment Definition Setup files
Persistent Runtime Data Docker stuff
Data Directory Volume folder
Infrastructure Repository Docker repo
Local Provider Local AI
Frontier Provider Cloud AI
Model Provider AI backend
Model Endpoint Ollama URL
Knowledge-Augmented Inference RAG, when governance and source retrieval are included
Retrieval Service RAG service
Context Package Prompt payload
Source Resolution File fetching
Policy Layer Security filter
Access Policy Permissions check
Egress Policy Cloud check
Execution Policy Agent rules
Delegated Authority Agent permission
Service Dependency Required thing
Verification Testing it quickly
Commissioning Installing
End-to-End Test Smoke test, when the complete workflow is tested
Configuration Template Sample config
Architecture Decision Record Design note
Operational Artifact Log file, when referring to the broader category
Canonical Artifact Source file
Derived Artifact Generated output

Naming Principles

When introducing new terminology:

  1. Prefer nouns over verbs.
  2. Use one Canonical Term for each concept.
  3. Prefer architecture-neutral language.
  4. Avoid naming concepts after temporary products.
  5. Separate responsibility from implementation.
  6. Prefer explicit names over abbreviations.
  7. Use abbreviations only after defining the full term.
  8. Preserve consistency over novelty.
  9. Avoid vague terms such as helper, manager, stuff, or misc.
  10. Use names that will remain meaningful if the implementation changes.

Host Naming

Current canonical Host names:

Host Canonical Name Responsibility
Gateway thoth-gateway Orchestration and service interfaces
Oracle thoth-oracle Local model inference

Host names should describe architectural roles rather than hardware models or temporary software.

Directory Naming

Canonical infrastructure directories:

Directory Responsibility
/srv/thoth/containers Infrastructure Repository
/srv/thoth/data Persistent Runtime Data
/srv/thoth/config Non-repository Runtime Configuration
/srv/thoth/backups Backup Artifacts
/srv/thoth/logs Host-managed operational Logs

Service-specific directories should use lowercase kebab-case.

Example:

open-webui

File Naming

Preferred names include:

compose.yaml
.env.example
README.md
00-project-state.md
10-architecture.md
20-philosophy.md
30-glossary.md
40-coding-standards.md
50-roadmap.md

Avoid creating alternate names for equivalent document roles without an Architecture Decision Record.

Final Principle

A shared vocabulary is part of the architecture.

When humans, AI assistants, Agents, documentation, and automation use the same words for the same responsibilities, system boundaries become clearer, policy becomes easier to enforce, and operational knowledge becomes more durable.

Precise language reduces accidental architecture.

Reference in New Issue View Git Blame Copy Permalink