# hev layer

> Retrieval gateway and transform runtime around turbopuffer.

hev layer is a transparent proxy in front of turbopuffer that adds operational semantics — document cache, namespace snapshots, search history, pipeline state — plus a Kubernetes-native UDF transform runtime for embedding, classification, tagging, and attribute migration.

These docs are queryable from the command line — better than reading this file: install `ask` (`go install github.com/hev/ask/cmd/ask@latest`), then `ask --endpoint https://hevlayer.com/api/ask search "<question>"` for ranked sections with deep links, `section get "<id>"` for detail, `overview` for the full map. Setup and verbs: https://hevlayer.com/docs/agents

The full concatenated docs are at https://hevlayer.com/llms-full.txt.

## Overview
- [Introduction](https://hevlayer.com/docs): Layer is a gateway and function runtime for modern retrieval systems. It scales compute for multi-stage indexing pipelines and runs functions across every row of your index, with all durable state in object storage.
- [Concepts](https://hevlayer.com/docs/concepts): How the gateway composes turbopuffer, the document cache, PostgreSQL, S3, and metrics — and the core nouns you'll work with.
- [Document model](https://hevlayer.com/docs/document-model): A Layer document and the reserved attributes the gateway manages on every row.
- [No Guarantees](https://hevlayer.com/docs/guarantees): Layer can't offer guarantees — here's what we commit to instead.
- [Tradeoffs](https://hevlayer.com/docs/tradeoffs): The current product posture and the cases it is not trying to cover.
- [Limits](https://hevlayer.com/docs/limits): Current ceilings inherited from the components we ship with, and what we don't cap.
- [Agents](https://hevlayer.com/docs/agents): Use the Layer docs and layer CLI from your coding agent with one-file skills that work across agent harnesses.
- [Demos](https://hevlayer.com/docs/demos): Live applications built on Layer — query routing, hybrid text fusion, semantic image search, and a full storefront workload — each composing shipped gateway features over a different corpus.
- [Changelog](https://hevlayer.com/docs/roadmap): What has shipped in hev layer, and what is coming next.
- [FAQ](https://hevlayer.com/docs/faq): Licensing, pricing, trials, and how to get started.

## Operations
- [Quickstart](https://hevlayer.com/docs/quickstart): Clone the repo, run the community gateway with Docker Compose, initialize a namespace, and run a query — no license key.
- [Install](https://hevlayer.com/docs/install): How to bring up a hev layer environment: AWS resources via Terraform, runtime via Helm.
- [Operator Overview](https://hevlayer.com/docs/kubernetes/operator): What layer-operator reconciles and how it relates to the gateway.
- [VectorStore CRD](https://hevlayer.com/docs/kubernetes/vectorstore-crd): Backend connection and gateway inbound auth policy for a Layer install.
- [ApiKey CRD](https://hevlayer.com/docs/kubernetes/apikey-crd): Minted API keys as Kubernetes resources: lifecycle, entitlements, and opaque claims.
- [Warehouse CRD](https://hevlayer.com/docs/kubernetes/warehouse-crd): Declared upstream data source: identity, credential, and verified reachability.
- [Index CRD](https://hevlayer.com/docs/kubernetes/index-crd): Declarative representation of a namespace managed by Layer.
- [InfraRules CRD](https://hevlayer.com/docs/kubernetes/scaling-crd): Cluster-wide compute pools, document cache rules, and workload scaling.
- [Pipeline CRD](https://hevlayer.com/docs/kubernetes/pipeline-crd): Staged row-changing work declared as a Kubernetes resource.
- [Function CRD](https://hevlayer.com/docs/kubernetes/function-crd): Stateless user-defined functions declared as Kubernetes resources.
- [Agent CRD](https://hevlayer.com/docs/kubernetes/agent-crd): Agentic search as a Kubernetes resource: a governed reasoning loop over your indices, bound to a model, a budget, and an entitlement.
- [Failure Modes](https://hevlayer.com/docs/failure-modes): How reads and writes degrade when the gateway, cache, or pipeline runs into trouble.
- [Layer CLI](https://hevlayer.com/docs/cli): The layer CLI manages environments, initializes namespace sharding, observes data-supply resources, indexes, pipelines, and UDFs, mints API keys, and runs Function manifests.
- [Dashboard](https://hevlayer.com/docs/dashboard): Running the in-cluster operations dashboard: the access it needs, networking, auth, and turning it off.

## API
- [Introduction](https://hevlayer.com/docs/api/introduction): What Layer adds on top of the turbopuffer-compatible client wire, and how to point a client at the gateway.
- [Write & Stage](https://hevlayer.com/docs/api/write): Write rows to a namespace and stage documents in the cache.
- [Blobs](https://hevlayer.com/docs/api/blobs): Durable content-addressed bytes served through the gateway.
- [Query & Fetch](https://hevlayer.com/docs/api/query): Vector similarity search with stable reads, query by id, and cached document fetch.
- [Federated query](https://hevlayer.com/docs/api/federated-query): Federate one query across a set of namespaces and merge the results into a single ranked list, scoped by the key's entitlements.
- [Agentic search](https://hevlayer.com/docs/api/agents): Run a configured reasoning loop over your indices: plan, fan out for recall, score for relevance, and return the standard row shape.
- [Scan](https://hevlayer.com/docs/api/scans): On-demand row selection by filter, full-text, hybrid-text, or radius — IDs, count, or values.
- [Pipelines](https://hevlayer.com/docs/api/pipelines): Organize a two-stage indexing pipeline: extract + chunk on CPU, embed on GPU, trigger runs and wait for completion.
- [Namespace metadata](https://hevlayer.com/docs/api/namespace-metadata): Read namespace metadata enriched with Layer freshness signals.
- [VectorStores And Warehouses](https://hevlayer.com/docs/api/data-supply): Read declared vector stores and upstream warehouses through the gateway.
- [Warm cache](https://hevlayer.com/docs/api/warm-cache): Warm a namespace's document cache and snapshot mirror.
- [Snapshot History](https://hevlayer.com/docs/api/snapshots): Facet snapshot jobs, history, bodies, and activity streams.
- [Checkpoints](https://hevlayer.com/docs/api/checkpoints): Immutable labels over namespace snapshot watermarks.
- [Query History](https://hevlayer.com/docs/api/search-history): Per-namespace query and clickstream history backed by JSONL in S3.

## Search knowledge graph

Version: 2
Generated: 2026-07-28T14:02:31.026Z
Content hash: a6e863a42cf528914f7a7396afa18ca84725389a9e6fe4f2ce1ae2d135112319

Context:
hevlayer is a gateway and Kubernetes runtime around Turbopuffer-compatible vector stores. The gateway preserves familiar document and query APIs while adding stable reads, caching, federated and agentic retrieval, operational metadata, and durable support data in object storage. Pipelines ingest external data or change row cardinality; Functions enrich rows already stored in Layer. Kubernetes resources configure indexes, vector stores, warehouses, compute pools, credentials, snapshots, and serving policy while keeping the gateway data path independent from reconciliation. Licensing is verified locally: core gateway operations remain available at the open floor, expired trials enter the floor immediately, and only commercial licenses receive post-expiration grace. The system favors explicit lifecycle, authorization, observability, and reconstructible state, accepting some gateway and indexing overhead in return.

Glossary:
- stable watermark: The per-namespace point through which the backing index is known to be fully caught up. Aliases: stable read watermark, stable-as-of.
- document cache: The ephemeral pull-through store used to accelerate document reads and pipeline staging while durable data remains elsewhere. Aliases: cache.
- VectorStore: A declared search backend and its credentials, endpoint, and inbound authorization policy. Aliases: vector store, backing store.
- Index: The control-plane resource that binds a namespace to backend, snapshot, scan, and scaling policy. Aliases: namespace index.
- Pipeline: A staged compute workflow whose processing may change row cardinality and whose workers scale with queue depth. Aliases: indexing pipeline.
- Function: A declared computation over rows that runs through operator-managed workers and preserves the intended row-level contract. Aliases: UDF, user-defined function.
- snapshot: A durable, content-addressed view of namespace state and facet information at a known watermark. Aliases: namespace snapshot.
- checkpoint: An immutable human-readable label for a durable namespace snapshot cut. Aliases: snapshot label.
- grace: A temporary license state in which gated capabilities continue while operators are warned to renew or replace the key. Aliases: license grace.
- license floor: The reduced capability set projected when no currently usable license or grace window remains. Aliases: floor.
- Agent: A saved, governed reasoning configuration that reformulates federated searches and reranks retrieved rows.
- ApiKey: A managed credential resource carrying scoped entitlements and opaque claims.
- InfraRules: The singleton cluster policy for compute pools, cache settings, and shared scaling constraints.
- Warehouse: A verified external source identity and credential used by ingestion pipelines.
- warm window: A cooldown that retains a worker and its node briefly after demand drains.