Concepts map
Foundation4 defines a small number of object types, and every API call operates on one of these types. This page shows how the object types relate to one another and defines each type in one paragraph. The Concepts section documents each object type in detail.
Object relationships
Solid connectors indicate composition: the source object is a component of, or is created within, the target object. Dotted connectors indicate references that are resolved at request time. Permissions apply to every object type; the diagram shows only the pipeline connector.
Processing objects
Embedding provider and embedding model. An embedding provider is an embedding engine that Foundation4 can run: FastEmbed, an OpenAI-compatible embedding endpoint, GPT4All, Hugging Face sentence-transformers, or a Hugging Face inference endpoint. An embedding model is a configured instance of a provider, such as FastEmbed with all-MiniLM-L6-v2. An embedding model converts text into a vector: a list of numbers that positions the text in a space where texts with similar meaning are close together.
Text splitter provider and text splitter. A text splitter provider is a splitting algorithm that determines where a document is divided into fragments. The providers wrap the text splitters of the LangChain library and range from fixed character counts to Markdown-header and code-aware splitting. A text splitter is a provider with configured parameters, such as chunk size and overlap. Fragment size affects retrieval quality: fragments that are too large carry irrelevant text into results, and fragments that are too small lose context.
A new installation includes one FastEmbed embedding model and three text splitters, so an administrator can create a pipeline without configuring a provider first.
Content objects
Pipeline. The primary container. A pipeline binds one body of content to the rules for processing that content: the embedding model, a default text splitter (a document can specify a different splitter), the set of classifications that documents in the pipeline can carry, an optional JSON Schema that document metadata must satisfy, and whether full-text search is enabled. A pipeline created without an embedding model supports full-text search only. The embedding model and the full-text search setting are fixed when the pipeline is created, because these settings determine the storage structure of the pipeline. Classifications can be added and removed after creation. Each pipeline has a dedicated set of tables and indexes, so the size and query load of one pipeline do not affect the indexes of another pipeline.
Classification. An attribute that a reader must hold to see a document, following the attribute-based access control (ABAC) model. Every document carries exactly one classification from the pipeline's list, and every search request names the classifications that the caller holds. The organization defines what classifications represent: clearance levels, teams, tenants, customer accounts, or a combination. Classifications can inherit from one another, so a pipeline can define that a reader holding secret also sees public. Each classification has a dedicated encryption key for the fragment text stored under that classification.
Document. One piece of plain text together with a classification and metadata. A document can carry an external_identifier, such as a message identifier from the client application's own system, which the client application uses to submit updates.
Version. Submitting a document with an existing external identifier creates a new version of the same document. By default, the previous version is expired, so search returns only current content, while the version history remains readable. The API can return a document, or the fragments of a document, as they existed at a specified point in time.
Fragment. A section of a document produced by the text splitter. Search returns fragments. Each fragment carries a position within the document, the classification and metadata of the document and, in search results, a score for the query that matched the fragment.
Metadata and taxonomy. Metadata is structured data attached to a document, such as a room identifier, an author, a date or a product line. Search requests filter on metadata with a query language that supports equality, ranges, pattern matching, set membership, and the and, or and not operators. A taxonomy is a hierarchy of values, such as a region that contains countries. A taxonomy filter matches a value and every value beneath that value.
Generation objects
LLM. A registered connection to an OpenAI-compatible language model, consisting of 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. Request parameters such as temperature are sent with each request and are not stored.
Agent. A reusable prompt. An agent consists of a list of messages (system, user or assistant) written as templates, and a set of named placeholders. A placeholder is either an input that the caller provides, such as the end user's question, or a retrieval step: a similarity or MMR search whose results are inserted into the prompt. An agent is not bound to a pipeline or to an LLM. The caller selects both when running the agent, so one agent can serve several pipelines and several models. Agents retain no conversation state between requests.
Access objects
API key. Every API request to Foundation4 carries an API key identifier and secret. An API key can be deactivated or given an expiry date. A master key, created at installation, holds every permission and is used to create the keys that client applications use.
Permissions. An API key holds read, write and execute permissions, either on an object type (all pipelines, all agents) or on an individual object. Read permits listing and retrieving objects. Write permits creating, updating and deleting objects. Execute permits adding documents, searching, and running agents and LLMs. The key that creates a pipeline receives all three permissions on the new pipeline. Creating any other object grants no permission to the creating key, which relies on the key's permissions on the object type. A key cannot grant permissions that the key does not hold. Permissions on a pipeline can also carry a list of the pipeline's classifications that the key is permitted to use.