Skip to main content

Glossary

This page defines the terms that the Foundation4 documentation uses, in alphabetical order, with a link to the page that describes each term. Every reader role uses this page: integrators and administrators for the objects of the API, operators for the terms of installation and operation, and security reviewers and evaluators for both.

A​

  • Administration key. The API key that runs administrative requests: the master key, or a key that holds the permissions that the requests need, such as write permission on the api-keys object type. See Manage API keys and permissions.
  • Agent. A reusable prompt that consists of a prompt template and a set of named placeholders. An agent is bound to neither a pipeline nor an LLM: each execution names both, and an agent keeps no conversation state between executions. See Agents and prompt templates.
  • Agent execution. A run of an agent with POST /agents/{id}/execute, which searches the pipeline named in the x-pipeline-id header and sends the completed prompt to the LLM named in the x-llm-id header. See Agents and prompt templates.
  • Agent execution trace. A record of one agent execution with tracing set to true: the input values, the fragments that each retrieval placeholder retrieved and the messages as sent to the LLM. The Redis-compatible cache keeps the trace for 60 minutes, and only the API key that ran the execution reads the trace. See Agents and prompt templates and Observability.
  • AI assistant. An application outside Foundation4, with a language model of the application's own, that connects to the Model Context Protocol (MCP) server of Foundation4 as an MCP client and uses search results from Foundation4 as context for answers. See MCP server.
  • Air-gapped. Describes a deployment without internet access, in which every image, model file, package and model server is provided inside the network. See Models, packages and air-gapped installs.
  • API key. The credential of every request: an identifier in universally unique identifier (UUID) format and a secret, sent in the x-api-key and x-api-key-secret headers. Foundation4 stores an Argon2 hash of the secret and returns the secret once, when the key is created. See Access control.
  • API server. The Rust service that receives all external requests: the REST API, the MCP endpoint, the API documentation and the metrics route. The API server runs searches and agent executions directly, and places ingestion jobs on the queue for the workers. See Architecture.
  • Application release. The Helm release foundation4ai, which installs the API server, the workers, the dashboard, the installation Jobs and, optionally, an Ingress or an HTTPRoute. See Deployment overview and requirements.
  • Application secret. The Fernet key in the configuration key app.secret, which encrypts the API keys of LLMs, the cached results of API key verification and agent execution traces. A changed or lost application secret makes the stored LLM API keys unreadable. See Secrets and keys and Data protection.
  • Argon2. The password hashing function with which Foundation4 stores API key secrets. A hash needs no key and cannot be turned back into the secret. See Access control.
  • Attribute-based access control (ABAC). The model that classifications follow: a document carries an attribute, and a reader must hold that attribute to see the document. The client application names the attributes that the reader holds in each search request. See Classifications.

C​

  • ChaCha20-Poly1305. The authenticated encryption algorithm with which the workers encrypt the text of every fragment, using a dedicated key for each classification. See Classifications and Data protection.
  • Classification. An attribute that a reader must hold to see a document. Every document carries exactly one classification from the classifications of the pipeline, and every search request names the classifications that the reader holds. See Classifications.
  • Classification allow-list. The classifications of a pipeline that an API key may use, carried by a permission on the pipeline; the value * permits every classification. The allow-list applies to adding, expiring and deleting documents and to classification management, while search requests name the reader's classifications explicitly. See Access control.
  • Classification matching. The rule, set by search_type in the classification field of a search, that decides which classifications a search includes. Hierarchical matching, the default, includes every classification that the named classifications inherit, and exact matching includes only the named classifications. Hierarchical matching with validation includes the inherited classifications, as hierarchical matching does, and fails if a named classification is not defined in the pipeline. See Classifications.
  • Client application. The application that calls the Foundation4 API on behalf of end users, such as a support portal or a chat application. The client application supplies documents, names the reader's classifications in searches and displays the results. See What is Foundation4.
  • Command-line interface (CLI). The foundation4ai binary in the API server image, which runs the API server, the workers and the maintenance subcommands for the database, the license, models and the master key. See Command-line interface.
  • Core release. The Helm release foundation4ai-core, which installs NATS JetStream, Valkey as the Redis-compatible cache, the Prometheus server, optionally PostgreSQL with pgvector, and the Secret with the connection settings. The application release reads that Secret by name. See Deployment overview and requirements.
  • Cursor mode. The default pagination mode of list requests, which pages forward with first and after and backward with last and before, using opaque cursors. See API conventions.

D​

  • Dashboard. The web application served at /dashboard on the host of the API server, to which operators sign in with an API key and secret. See Architecture.
  • Deployment profile. One of the two supported installation forms: the evaluation profile or the production profile. See Deployment overview and requirements.
  • Direct query. A request to POST /llms/{id}/query, which sends one prompt to a registered LLM as a single user message, without a system message and without retrieval. See LLMs.
  • Distance strategy. The measure with which similarity search and maximal marginal relevance (MMR) search compare the query vector with fragment vectors: cosine, the default, euclidean-distance or dot-product. See Search and retrieval.
  • Document. One piece of plain text with one classification and optional metadata, submitted to a pipeline. Foundation4 does not parse files, so the client application extracts the text before submission. See Documents, versions and fragments.
  • Document expiry. The operation that marks every current version of a document as expired, so that search and document lists exclude the versions while the version history stays readable. Deletion, by contrast, removes every version and fragment permanently. See Documents, versions and fragments.
  • Document status. The status field of a document: pending until a worker has processed the document, then success, or failed when the processing job could not be placed on the queue. A document is searchable only after the status is success. See Documents, versions and fragments.

E​

  • Embedding model. A configured instance of an embedding provider, with a model name and parameters, that converts text into vectors. A pipeline with vector search names the embedding model at creation, and the choice cannot change afterwards. See Embedding models and text splitters.
  • Embedding provider. An embedding engine that Foundation4 supports: FastEmbedEmbeddings, OpenAIEmbeddings, GPT4AllEmbeddings, HuggingFaceEmbeddings or HuggingFaceEndpointEmbeddings. See Providers and models.
  • Evaluation profile. The deployment profile for evaluation on one node, with a bundled PostgreSQL on a temporary pod volume and 1 worker. Deleting or rescheduling the PostgreSQL pod deletes all data and changes the system ID. See Install for evaluation.
  • External identifier. The external_identifier of a document: an identifier from the client application's own system. A submission with an existing external identifier creates a new version of the document that carries the identifier. See Documents, versions and fragments.

F​

  • FastEmbed. The embedding library that runs inside the API server and worker processes, with Open Neural Network Exchange (ONNX) model files; the seeded embedding model uses FastEmbed. See Providers and models.
  • Fernet. The authenticated symmetric encryption format that the application secret uses. See Secrets and keys.
  • Filter. A condition on metadata in the filters field of a request, which PostgreSQL applies in the same query that selects the fragments. See Metadata, filters and taxonomies and Filter operators.
  • Fragment. A section of a document produced by the text splitter. Search returns fragments, and each fragment carries the classification and metadata of the document, a position within the document version and, in search results, a score. See Documents, versions and fragments.
  • Full-text search. The search mode that returns the fragments that contain every word of the query, ranked by relevance with the text search of PostgreSQL. Full-text search requires a pipeline created with full-text search enabled. See Search and retrieval.
  • Full-text-only pipeline. A pipeline created without an embedding model and with full-text search enabled. Foundation4 splits and stores the documents of the pipeline but computes no vectors. See Pipelines.

G​

  • gRPC service. The Python service that runs every text splitter and the embedding providers that depend on Python libraries. The gRPC service runs as a sidecar container in every API server pod and every worker pod. See Architecture.

H​

  • Health check. The route /healthz of the API server, which answers after startup and reports every component as ok without checking the components. A response therefore means that the API server process started and serves HTTP. See Monitoring and logging.
  • Hierarchical navigable small world (HNSW) index. The approximate nearest-neighbor index on each vector table, with one index for each distance strategy. See Search and retrieval.
  • Hybrid search. The combination of a vector search and a full-text search for the same query, with the two result lists fused by rank. In the current release, the client application sends both searches and fuses the results; Feature status lists the status of native hybrid search. See Combine full-text and vector results.

I​

  • Image volume. A Kubernetes volume whose content comes from an image that the kubelet pulls and mounts read-only without running the image. The charts deliver model images and package images as image volumes. See Models, packages and air-gapped installs.
  • Inheritance. A relation between the classifications of a pipeline: a reader who holds a classification also sees documents that carry any classification that the held classification inherits, transitively. See Classifications.
  • Installation bundle. An archive from the Foundation4 provider with the deployment files, both charts, image archives and example values. See Charts, images and installation bundle.
  • Installation Jobs. The three Helm hook Jobs of the application release, which apply the database migrations, check the license and create the master key at every installation and upgrade, before the Deployments start. See Install on Kubernetes.

L​

  • License. The value, issued by the Foundation4 provider for one system ID, that every installation requires. The license carries an optional expiry date and optional limits on object counts. See Licensing.
  • License limits. The maximum number of objects of each type, such as pipelines or documents, that a license allows. The API server refuses an operation that would exceed a limit with HTTP 403. See Licensing.
  • LLM. A registered connection to a language model on a model server: a name and the endpoint base URL, with an optional model name, description and API key. Foundation4 encrypts the API key and never returns the key. See LLMs.

M​

  • Master key. The administration key of a deployment, created at installation from app.master.key and app.master.secret, with all three permissions on every object type and the allow-list *. The API server and the workers authenticate with the master key at startup. See Access control.
  • Maximal marginal relevance (MMR) search. The search mode that retrieves fetch_k candidates by similarity and selects k fragments that are relevant to the query and different from one another. See Search and retrieval.
  • MCP client. An application that connects to an MCP server, lists the tools of the server and calls the tools. See MCP server.
  • MCP server. The MCP endpoint /mcp of the API server, which offers the tools get_pipelines, get_pipeline_classifications and search_knowledge. Each tool corresponds to a REST operation, and each request carries the API key headers of the REST API. See MCP server and MCP tools.
  • Metadata. A JSON object submitted with a document and copied to every fragment of the document. Metadata is stored unencrypted, because PostgreSQL compares metadata values directly when applying filters. See Metadata, filters and taxonomies.
  • Metadata index. An index that POST /pipelines/{id}/indexes creates on a declared metadata field. A metadata index does not accelerate metadata filters. See Write metadata filters.
  • Metadata schema. The JSON Schema of a pipeline that the metadata of every submitted document must satisfy. See Metadata, filters and taxonomies.
  • Migration. A numbered change to the database schema, recorded in the table schema_migrations. Migrations only move forward. The migration Job applies pending migrations, and the API server, the workers and the master key Job also apply pending migrations at startup. See Database.
  • Model Context Protocol (MCP). An open protocol through which AI assistants and other MCP clients discover the tools that a server offers and call those tools. See MCP server.
  • Model directory. The directory in which a provider reads model files, set by a paths configuration key, such as /data/fastembed for FastEmbed. See Models, packages and air-gapped installs.
  • Model image. An image with model files for one provider, which the charts mount into the API server and worker pods as an image volume. See Models, packages and air-gapped installs.
  • Model server. A server that exposes an OpenAI-compatible API and that the API server can reach, either a hosted service or a server inside the network. Agents and direct queries call the Responses API of the model server, and the OpenAI-compatible endpoint calls the chat completions API. See LLMs.

N​

  • NATS JetStream. The messaging system that provides the work queue between the API server and the workers, and the object store that holds the raw text of each document until processing completes. See Architecture.
  • NATS utility pod. The pod foundation4ai-core-nats-box of the core release, which contains the nats command-line tool for reading the state of the queue. See Operator command reference.
  • Newline-delimited JSON (NDJSON). The default streamed response format of agent executions and direct queries, with one JSON object on each line. See LLMs.

O​

  • Object store. The NATS JetStream store that holds the raw text of each submitted document until a worker has processed the document, for at most 24 hours. See Documents, versions and fragments.
  • Object type. A kind of object on which an API key holds permissions: agents, api-keys, embedding-models, embedding-providers, llms, pipelines, taxonomies, text-splitter-providers or text-splitters. See Access control.
  • Offset mode. The pagination mode that selects a page by position with limit and offset. See API conventions.
  • OpenAI-compatible endpoint. The route POST /openai/v1/chat/completions, which relays a chat completion request to a registered LLM with Foundation4 authentication and permissions. See LLMs.
  • OpenTelemetry export. The export of a span for each API request and of the log records of the API server through the OpenTelemetry Protocol (OTLP), enabled by OTLP environment variables. The workers, the gRPC service and the dashboard export no OpenTelemetry data. See Monitoring and logging and Observability.

P​

  • Package image. An image with one Python package and the package dependencies, which the charts mount into the gRPC service container at /packages/<name>. See Models, packages and air-gapped installs.
  • Permission. A combination of three bits held by an API key on an object type or on an individual object: read (4), write (2) and execute (1). A key with all three permissions holds 7. See Access control.
  • Pipeline. The primary container of content, which binds documents to the rules that process the documents: the embedding model, the default text splitter, the classifications, the metadata schema and the full-text search setting. Each pipeline has a dedicated set of tables and indexes in PostgreSQL. See Pipelines.
  • Placeholder. A named value that Foundation4 inserts into the prompt template of an agent at execution. A query placeholder holds a value that the client application supplies, and a retrieval placeholder, of type similarity or mmr, holds the text of the fragments that a search returns. See Agents and prompt templates.
  • Point-in-time read. A document or fragment read with the as_of parameter, which returns each document as the document existed at that time. See Documents, versions and fragments.
  • PostgreSQL with pgvector. The primary data store of Foundation4, which holds all persistent state, including documents, fragments, vectors and full-text indexes. The pgvector extension provides vector storage and nearest-neighbor indexing. See Architecture.
  • Processing job. A message on the NATS JetStream queue that asks a worker to split, embed and store one submitted document version. When processing fails, the queue redelivers the job after 10 seconds, and the queue removes each job 24 hours after submission. See Documents, versions and fragments.
  • Production profile. The deployment profile for production use, with external PostgreSQL with pgvector, several nodes, resource requests and limits, and access through an Ingress or an HTTPRoute with Transport Layer Security (TLS). See Deployment overview and requirements.
  • Prometheus metrics. The metrics that the API server serves at /metrics on port 8000 and that each worker serves on port 9090. See Monitoring and logging and Metrics.
  • Prompt inspection. A request to GET /agents/{id}/prompt, which returns the stored messages and placeholders of an agent and the names of the query placeholders that an execution must supply. See Agents and prompt templates.
  • Prompt template. The list of messages of an agent in the order that the model receives the messages, each with a role and a template text that refers to placeholders by name in braces. See Agents and prompt templates.
  • Provider. An engine that Foundation4 supports for embeddings or for text splitting. An embedding model or a text splitter is a configured instance of a provider. See Embedding models and text splitters.

R​

  • Raw text. The text of a document as submitted, which Foundation4 keeps in the NATS JetStream object store only until processing completes, and for at most 24 hours. After processing, the encrypted fragments are the only stored copy of the text. See Documents, versions and fragments.
  • Reciprocal rank fusion (RRF). The method with which a client application fuses the result lists of hybrid search: a fragment at rank r in a list with weight w receives w / (60 + r) from that list, and the fused list is sorted by the sum. See Combine full-text and vector results.
  • Redis-compatible cache. The cache that holds short-lived data only: encrypted results of API key verification, frequently read objects such as pipelines and agents, and encrypted agent execution traces. The cache contains no data that recovery requires. See Architecture.
  • Request identifier. The x-request-id value of a response from an API operation, which the API server generates for each request or takes from the request, and records in the traces of the request. See API conventions and Observability.
  • Retrieval dry run. A request to POST /agents/{id}/search, which runs the retrieval placeholders of an agent without calling a model and returns the fragments of each placeholder. See Agents and prompt templates.
  • Retrieval-augmented generation (RAG). The answering of a question by a language model that receives relevant content retrieved at the moment the question is asked. Foundation4 performs the retrieval, and agents also run the generation. See What is Foundation4.

S​

  • Scoped key. An API key for a client application, with permissions on individual objects and a classification allow-list. See Access control.
  • Score. The score field of a search result: a distance under the distance strategy for similarity search and MMR search, where lower is closer, or a text search rank for full-text search, where higher is better. Scores of different modes cannot be compared. See Search and retrieval.
  • Secrets file. The file foundation4ai.secrets.env, which holds the connection settings, passwords, the license, the application secret and the master key values, and from which the operator builds the Secret foundation4ai-secrets. See Secrets and keys.
  • Seeded objects. The embedding model and the three text splitters that every installation includes, so that a first pipeline can be created without configuring a provider. See Providers and models.
  • Server-sent events (SSE). A streamed response format of agent executions and direct queries, selected with stream set to "sse". See LLMs.
  • Sidecar container. A second container in the same Kubernetes pod as the main container, sharing the network namespace of the pod. The gRPC service runs as a sidecar container. See Architecture.
  • Similarity search. The search mode that returns the k fragments whose vectors are closest to the query vector. See Search and retrieval.
  • System ID. A string of 64 hexadecimal characters that identifies one PostgreSQL database, computed from catalog object identifiers of the database. The Foundation4 provider issues each license for one system ID. See Licensing.

T​

  • Taxonomy. A hierarchy of metadata values, such as regions that contain countries. The $teq filter operator matches a value together with every value beneath that value in the taxonomy. See Metadata, filters and taxonomies.
  • Text search configuration. The PostgreSQL configuration of a language, which defines how full-text search reduces words to terms. See Full-text languages.
  • Text splitter. A configured instance of a text splitter provider, which divides the text of a document into fragments before embedding. All text splitters run in the gRPC service. See Embedding models and text splitters.
  • Text splitter provider. A splitting algorithm from the LangChain library that Foundation4 supports, such as RecursiveCharacterTextSplitter. See Providers and models.

V​

  • Valkey. The Redis-compatible cache that the core release installs. See Values reference.
  • Vector. A list of numbers that an embedding model computes from a text, which places texts with similar meaning close together. See Concepts map.
  • Vector embedding. The association of a pipeline with an embedding model, which has an identifier of the association's own. The embedding_models object of a pipeline maps each vector embedding identifier to the embedding model, and a vector embedding identifier is not an embedding model identifier. See First search.
  • Version. The state of a document created by one submission, identified by the creation time in microseconds since the Unix epoch. See Documents, versions and fragments.

W​

  • Worker. A process that runs the Foundation4 binary in worker mode, retrieves ingestion jobs from the queue in batches of up to 100 documents, splits each document into fragments, computes vectors and writes the fragments to PostgreSQL. See Architecture.