CLIO Core

Docs · Context Exploration Engine

The Context Exploration Engine.

The Context Exploration Engine (CEE) is a small API over the other two engines. It imports data through the Context Assimilation Engine, then finds and reads it back through the Context Transfer Engine by name, by keyword or by time. It exists so that a program, a notebook or an agent can work with stored data through five calls.

C++
iowarp::ContextInterface in clio_cee/api/context_interface.h
Python
import clio_cee
Source
context-exploration-engine/api
Needs
A running runtime

What it is

CEE is one class, iowarp::ContextInterface, available in C++ and as the Python module clio_cee. It has five methods:

  • bundle imports a list of sources into tags.
  • query returns the names of blobs that match a regular expression, a keyword prompt, or a time range.
  • retrieve runs the same query and returns the matching blobs' bytes packed into one buffer.
  • destroy deletes tags.
  • splice is declared but not implemented.

The class stores nothing itself. Every call becomes a task on the Context Assimilation Engine or the Context Transfer Engine, so what CEE can find and how fast it can read is decided by how the runtime is composed.

The problem it solves

The CTE client is precise but verbose: tags, tag ids, blob ids, buffers in shared memory, async futures. The CAE client takes serialized context lists. A program that only wants to put some documents in, ask which ones talk about a subject, and read those back should not have to learn either. CEE is that shortcut. It is also the API the pip wheel exposes for Python users who do not build from source, and the shape an agent tool or a retrieval pipeline calls.

Key concepts

  • Context. In CEE's vocabulary a context is a CTE tag. context_destroy takes tag names. A bundle's dst is iowarp::<tag name>.
  • AssimilationCtx. The transfer description shared with the CAE: source URL, destination, format, and optional range, tokens and inline payload. The Python binding exposes nine of its fields.
  • Query modes. One method, three behaviors chosen by its arguments: temporal when a time bound is set, semantic when a prompt is given, regex otherwise. The order of precedence is temporal, then semantic, then regex.
  • Patterns. tag_re and blob_re are full-string regular expressions. .* matches everything; .*part.* matches a substring.
  • Packed buffer. Retrieve returns the bytes of every matched blob concatenated, with no framing. The caller must know the blob sizes or query names first.

How it relates to the other technologies

  • Context Assimilation Engine: context_bundle is a ParseOmni task on the CAE pool at 400.0. Everything the CAE can import, CEE can import, with the fields the binding exposes.
  • Context Transfer Engine: query, retrieve and destroy are the CTE client's BlobQuery, SemanticSearch, TemporalSearch, GetBlob and DelTag. Keyword search is answered by the CTE indexer module, so the client must be bound to a pool that reaches it.
  • Context Runtime: CEE attaches to a running runtime as a client on first use. It does not start one.
  • Context FS: files written through a mount are tags and blobs, so CEE can query and retrieve them without an import. Pages are named by number and there is a small attribute blob to exclude.
  • Machine learning: clio-ml reads datasets from the same tags; CEE is a convenient way to stage and inspect them from Python.

Where to go next

  • Install: the pip wheel includes clio_cee; the CMake options and nanobind for source builds; what the MCP server needs.
  • Usage: connecting, bundling, the three query modes, retrieving, working with Context FS files, composing storage for search, and the MCP server.
  • API reference: every method, argument and default in C++ and Python, AssimilationCtx, return formats, environment variables and the MCP tools.