Explorations

Overview

Explorations are the primary user-facing experience built on Condelo's platform primitives. An exploration is a two-phase, agent-driven workflow that turns a space's inferences into guided conversations:

1. Prep phase — an agent clusters the space's inferences, identifies connections between clusters, and generates seed cards (entry points) for each cluster.
2. Conversation phase — the user opens a cluster, picks a seed card or asks their own question, and the agent guides them through the material via suggested paths, inline surface references, and research tasks.

Every space has exactly one exploration. It is created automatically the first time a user opens the explore view for that space.

Key Concepts

• Exploration — a persistent analysis session scoped to a single space. Tracks agent state (clusters, connections) and user state (visited clusters, current position).
• Clusters — groups of related inferences, each with a name, description, significance score (0–1), density metric, and a list of seed cards. Clusters are the primary navigation unit.
• Seed cards — designed entry points into a cluster. Each has a type — finding_thread (follow a line of evidence), contradiction (surface conflicting signals), pattern (highlight recurring themes), or opportunity (identify actionable gaps).
• Connections — edges between clusters describing how they relate: shared_evidence, causal, contradiction, or related. Displayed as a cluster graph.
• Threads — chat conversations scoped to a single cluster. A user can have multiple threads per cluster.
• Suggested paths — after each agent response, the model proposes 2–3 follow-up directions (label, description, prompt) the user can click to continue the conversation.
• Research tasks — questions queued for background investigation. Can be auto-suggested by the agent or created manually. Results are delivered as new messages.
• Collection items — bookmarked findings, surfaces, research results, and notes saved during exploration. Items can be pinned and reordered.
• Nudges — when new inferences arrive after the last prep, the exploration is flagged (nudgePending) with a reason so the UI can prompt the user to re-prep.
• Delta tracking — incremental prep updates only process inferences added since the last run, tracked via agentState.delta and agentState.version.

Data Model

explorations table:

exploration_threads table:

exploration_messages table:

exploration_collection_items table:

exploration_research_tasks table:

How It Works

1. Auto-creation — when a user first opens the explore view for a space, an exploration record is created automatically with status: active and empty agentState.

2. Prep (initial) — the user triggers prep. The prep agent reads all inferences in the space, clusters them by semantic similarity, generates seed cards for each cluster, identifies cross-cluster connections, and writes the full result to agentState. The lastPreparedAt timestamp is set.

3. Cluster navigation — the UI renders a cluster graph from agentState.connections and a list of clusters sorted by significance. The user picks a cluster to explore.

4. Seed card selection — each cluster shows its seed cards (finding threads, contradictions, patterns, opportunities). Clicking a seed card creates a new thread and sends the seed card's prompt as the first message.

5. Conversation — the agent streams a response via SSE, referencing relevant surfaces inline and appending 2–3 suggested paths. The user can follow a suggested path, ask their own question, or save findings to their collection.

6. Research tasks — during conversation, the agent may suggest research questions. The user can also create them manually. Each task is queued, processed by the deep-dive agent in the background, and the result is posted as a new message in the thread.

7. Collection — as the user explores, they bookmark findings, pin important items, and add notes. Collection items persist across threads and clusters.

8. Nudges — when new documents are ingested and new inferences are generated after the last prep, the system sets nudgePending: true with a reason describing what changed. The UI shows a prompt to re-prep.

9. Incremental prep — when the user re-preps, the agent only processes inferences added since the last run (tracked via agentState.delta). Existing clusters are preserved or merged; new clusters may be created. The agentState.version is incremented.

Why It Works This Way

Clusters Over Flat Lists

Inferences can number in the hundreds or thousands per space. Flat lists are overwhelming. Clustering groups related signals so users can approach the material thematically, starting with the highest-significance cluster and drilling down.

Seed Cards as Designed Entry Points

Open-ended "ask anything" interfaces produce shallow questions. Seed cards are generated from the actual inference content and typed by analytical purpose (finding thread, contradiction, pattern, opportunity), giving users substantive starting points that lead to deeper engagement.

Suggested Paths Over Open-Ended Chat

After each response, the agent proposes concrete follow-up directions rather than waiting for the user to figure out what to ask next. This maintains conversational momentum and ensures the user doesn't miss important connections.

agentState as JSONB

The prep output (clusters, connections, summary) is a complex nested structure that varies as the clustering algorithm evolves. Storing it as JSONB avoids frequent schema migrations while still being queryable for nudge checks and UI rendering.

Delta Tracking for Efficiency

Re-running full prep on every new inference would be expensive and disruptive (users lose their place in existing clusters). Delta tracking (agentState.delta, agentState.version) enables incremental updates that preserve existing cluster structure while incorporating new material.

Research Tasks as Background Agents

Some questions require deeper analysis than a single chat turn can provide — pulling from multiple sources, cross-referencing structured data, or synthesising across clusters. Research tasks run asynchronously so the user can continue exploring while the deep-dive agent works.

Code Reference

Relationships

• Spaces — each exploration belongs to exactly one space. The space's inferences are the raw material for clustering.
• Inferences — the prep agent reads inferences to build clusters and seed cards. New inferences trigger nudges.
• Agents — explorations use three specialised agents (prep, converse, deep-dive) built on the platform's agent infrastructure.
• Surfaces — agent responses reference surfaces inline, linking conversational insights back to structured outputs.
• Feeds — clusters reference feed IDs, connecting thematic groups back to the feeds that generated the underlying inferences.