Your first vector analysis with EigenLens

Start with a familiar collection of customer messages, documents, articles, or reviews, and one question: “What are the recurring themes in this selection?” EigenLens helps you investigate it through clustering, topic terms, and representative records you can inspect.

Set up the service and your connection

Use the getting-started guide for the Docker command, configuration, and client connection. The public Docker image is available now; public source release is planned.

Analysis runs in your EigenLens deployment, using local snapshots of selected vectors, source text, and metadata. Plan for those copies and saved results when choosing where to run the service.

The MCP workflow begins with get_capabilities. Then use connect_database and list_collections to establish which collection you want to inspect. Connection details differ across the supported stores, so follow the backend guidance for your adapter.

If your application already holds the intended records, register_records provides another input path. Each record needs an ID and a compatible vector; useful topic language also needs the original text. Vectors of equal length can still come from incompatible embedding spaces, so check their model and preparation history.

Choose what the result will describe

Decide whether your question concerns a collection or a local neighborhood. retrieve_records can read all pages of a selected collection within configured limits, or retrieve a bounded set of semantic neighbors. The result describes that selection.

For example, retrieving records similar to “refund delay” and then clustering them may reveal different kinds of refund-related messages. It does not tell you what proportion of all customer messages concern refunds. To answer a collection-wide question, supply the appropriate collection-wide selection or a defensible sample with its limitations made clear.

Keep the first selection manageable. Row limits do not guarantee that a workload fits available memory or time. A small collection makes connection and data-quality problems easier to spot.

Run clustering and topics

Retrieval or registration returns a dataset ID. Substitute it into this current run_analysis request:

{
  "name": "run_analysis",
  "arguments": {
    "dataset_id": "REPLACE_WITH_RETURNED_DATASET_ID",
    "operations": [
      {
        "id": "groups",
        "type": "cluster",
        "algorithm": "dbscan_search"
      },
      {
        "id": "themes",
        "type": "topics",
        "clusters_from": "groups",
        "parameters": { "ngram_max": 2 }
      }
    ]
  }
}

groups and themes are caller-chosen operation IDs. The topic operation reuses the clustering assignments through clusters_from.

The service returns a job handle. Poll get_job until the job succeeds or reports a terminal failure. A queued or running job has no completed result to interpret. If you need to stop the work, use cancel_job.

Inspect the evidence before naming the groups

After success, inspect the returned results.groups and results.themes using get_summary, get_examples, and get_result_page.

Confirm the selection scope, record count, group sizes, and unassigned count. Examine weighted topic terms alongside source examples, then use result pages for underlying assignments and IDs.

A group can suggest a useful theme without establishing a predefined business category. Read enough examples to decide whether the interpretation is coherent. Record counts may include several chunks from one document or ticket, so explain them as vector-record counts unless your application has explicitly reconciled parent records.

Clustering can leave records unassigned, and sometimes no valid candidate is found. Preserve that outcome and its diagnostics. Forcing an attractive label onto every record would hide useful information about the data or the fit of the method.

Turn the result into a useful next step

Write a short explanation of what was analyzed, which groups appeared, and which terms and source examples support your interpretation. Include uncertainty and unassigned records where they affect the conclusion.

Use that evidence to investigate recurring concerns or design a useful way to browse the collection. Evidence beyond search explains how to carry results into an agent or application with their scope and source references intact.