Dashboard/Algolia-Central/Brief.md
Algolia-Central

Brief.md

Algolia Central — Project Brief

This is the durable brief. Operational state (current task lists, file pointers, dependency status, R/AG/CF tables) lives in repo RC3-BRIEF.md at /Users/arijitchowdhury/AI-Development/RAG/AlgoliaRAG-Google/rc3-phoenix/RC3-BRIEF.md.

Branch: rc3-phoenix Predecessor: RC2-Algolia, sealed at tag rc2-algolia-final (commit d2df6a19), demoed at Adobe Summit 2026.

Part 1: Why We're Here

RC2-Algolia was demoed at Adobe Summit 2026 (Apr 20-22). The story landed. Nobody said no. Pilot interest from Adobe Brand Concierge, MasterCard, and others. Confirmed pilots: Sherwin Williams and MasterCard. Arijit's call: "POC is done. The story is resonating. How do we take this to market and productize it into an Algolia product offering? That will be my legacy here."

RC3 Phoenix is the production pivot. POC → Product. Bootstrap → Native Algolia. Demo → Pilot-ready reference implementation.

Part 2: What Algolia Central Is — Content Engagement

The positioning shift

Algolia is known for fantastic product search — indexing product data, blazing-fast retrieval. Content Engagement extends that: use the same Algolia infrastructure (connectors, retrieval, indexing) but fan out into ALL content — not just products. Then layer agentic capabilities on top via Agent Studio.

The stack (bottom to top)

  1. Connectors — fan out to content and knowledge silos: service content, educational content, product content, industry content, integration content, blog content, news content — any content repository
  2. Transformation — homogenize heterogeneous content into a common structure
  3. Enrichment — Algolia Fetch to enrich data before indexing
  4. Algolia NeuralSearch — index everything, neural search on top ("heart and soul")
  5. Agentic layer — Agent Studio agents performing any workflow: service, sales, advisory, recommendations — any agentic capability built on top of the indexed content

What "Content Engagement" means

Algolia powering engagement via content. Extending Algolia's capabilities from beyond product search to be at the core of infrastructure for engaging via content. The machine works as the human wants it — humans don't need to understand how the machine works.

What "Central" means

Centralizing content, data, and information — then giving you the means to talk to it, query it, interact with it in a natural, human way. Algolia Central, Adobe Central, Sherwin Central, MasterCard Central — the "Central" pattern is the product. Same architecture, different index, different content, different agents.

Who uses it

The persona is open — developer, business owner, analyst, prospect, existing customer, merchandiser. No fixed ICP. The agent detects who the user is and adapts dynamically. This applies to every implementation: - Algolia Central (algolia.com) — learn about Algolia, get implementation guidance, explore capabilities - Sherwin Central (sherwinwilliams.com) — find paints, learn application, get pricing, maintenance - MasterCard Central (mastercard.com) — compare cards, understand benefits, choose the right card - Any Central — the reference implementation adapts to any business

Confirmed pilots

  1. Sherwin Williams — confirmed
  2. MasterCard — confirmed

The reference implementation IS the product. Prescriptive, opinionated, per-use-case.

Part 3: What The System Is Today (architecture overview)

Architecture

A hybrid multi-persona orchestration system with: - Maverick — local deterministic orchestrator (god-object pattern). Runs discovery, signal extraction, retrieval, prompt building, streaming, handoff routing. - Elena — Agent Studio specialist for implementation/value depth. Zero tools today. Text-in/text-out. - Bruno — Agent Studio specialist for architecture/scale depth. Zero tools today. Text-in/text-out. - Algolia NeuralSearch — retrieval backend (mixes policy and execution today) - Redis — session memory (8-signal discovery state) - SSE streaming — real-time response delivery with 15 event types - Frontend — XML-like tag parsing, specialist artifact rendering, discovery cards, handoff banners

Runtime Flow

Browser → useChat → useChatStream/useSpecialist → POST /api/search → search transport
  → igniteMaverick (local: session → signals → retrieval → prompt → Gemini → stream → handoff)
  → OR igniteSpecialist (Agent Studio: /completions → text stream → JSON→XML conversion)
  → SSE events → frontend state machine → ChatMessage rendering

What's Good

  • Real multi-agent workflow, not a thin chatbot wrapper
  • Deterministic discovery and handoff control
  • Algolia NeuralSearch + Atlas retrieval grounding
  • Rich observability (pipeline steps, turn snapshots, audit traces)
  • Tests exist for handoff routing, discovery, SSE parsing, auditor behavior

What's Bad

  • Architecture is implicit in code, not explicit in contracts
  • Largest files are product-critical and hard to reason about
  • Frontend and backend share fragile hidden contracts (SSE events + XML-like tags)
  • Agent Studio is used as a text endpoint, not as the tool-use platform it actually is
  • Elena/Bruno have zero tools, take 30+ seconds, produce text that requires parsing/conversion
  • Stream adapter converts Agent Studio JSON→XML tags (fighting the platform)
  • Post-generation content mutation can alter user-visible answers

Module Risk Tiers

Tier 0 — Do NOT touch until traced: Maverick orchestrator, stream processor, frontend chat hooks, ChatMessage renderer Tier 1 — Extract contracts from: discovery analyzer, question expander, retrieval context, specialist request Tier 2 — Refactor after traces: API search transport, retrieval orchestrator, metadata manager Tier 3 — Cleanup later: README drift, lint debt, duplicate message types, frontend tag stripping

Contracts That Need To Be Named

  1. Conversation turn contract
  2. Session state contract
  3. Discovery policy contract
  4. Retrieval request and result contract
  5. SSE event contract (15 event types documented)
  6. Handoff contract (ready → verify → accepted → complete)
  7. Specialist artifact contract
  8. Trust and audit mutation contract
  9. Persona authority contract
  10. Ingestion and indexing contract (new for RC3)

Part 4: Agent Studio — Pointer to the Wiki

The Agent Studio knowledge synthesis is the source of truth for any prompt refactor, agent refactor, tool design, multi-index strategy, or UI/InstantSearch refactor work. It pulls from ~34 official Algolia documentation pages, 50 demo agents in app Q6N17K5UHW, and our own 5 agents in app 0EXRPAXB56 — collapsed into 12 numbered sections plus evidence cards. The headline finding: Agent Studio's own team converged from multi-agent shopping to single-agent + N indices, which is the architecture we should adopt; Elena/Bruno should follow the AskAI archetype, not the Shopping Assistant archetype; output shape should be hybrid (narrative text + tool calls), not XML-in-text. Detailed patterns, gap analysis, and migration ordering live in the wiki — do not re-derive them here.

Route to: Projects/Algolia-Central/Knowledge/AgentStudio/README.md (routing table inside).

Part 5: Where We're Going (UX Direction + Architectural Q&A)

From Arijit, 2026-04-24 — directional commitments. Where 2026-04-25 wiki work updated a position, the update is inline.

1. Open persona, dynamic detection

No fixed ICP. The agent detects the user's role from conversation and adapts tone and depth. Developer → technical. Business owner → strategic. Merchandiser → operational. Detection IS the intelligence.

2. Agent model — single agent, N indices (updated 2026-04-25)

Decision (2026-04-25): Single agent with N indices (Option B, like DocSearch / SW-Financial). NOT orchestrator + SME-per-index. Algolia's own team deprecated multi-agent shopping; we'd be reinventing the deprecated pattern. Full rationale in wiki §06.

This supersedes the earlier "orchestrator + SME agents per content type" direction. The user never sees agent-to-agent routing — there is no agent-to-agent routing in v1. SME-style decomposition can be reconsidered for v2 if production data justifies it.

Claude Desktop remains the UX reference: one conversational agent, opens artifacts/cards in a right panel.

Open question: Index split granularity — how many indices, sliced by what (content type, source, vertical)? This depends on R1-R6 research outputs and is captured in wiki §06.

3. "Arijit chat" as the brand

The main conversational agent may be branded as "Arijit." Scope TBD — rebrand or codebase merge.

4. Two-panel UI (Claude Desktop reference)

Left panel: chat conversation. Right panel: opens on click — roadmaps, deep-dive analyses, content cards, code samples. Clickable components in the chat trigger the right panel. Chat is the vehicle, not the product.

5. Beyond pure chat

Content cards, drop-down cards, clickable components. This maps directly to Agent Studio's client-side tool pattern — structured JSON → frontend renders interactive components.

6. Cross-business framework

The same pattern applies to every implementation. Sherwin Williams, MasterCard, NRG. Same architecture, different index, different tools, different prompt.

Architecture-level Q&A (open questions, current status)

ID Question Current position (2026-04-25)
Q-AS1 One agent or two? Single agent with all tools vs. discovery + specialist? Partially answered — see wiki §04 + §06. Decision: single conversational face per pilot, with N indices. Open sub-question: do Maverick (discovery) and Elena/Bruno (specialist) collapse to one agent in v1 or stay split?
Q-AS2 What are the clickable components for the right panel? Partially answered — see wiki §02 + §08. Decision: per-tool layoutComponent is the mechanism. Open sub-question: which specific components ship in v1 (roadmap card, content card, code sample card, etc.)?
Q-AS3 "Arijit chat" scope — rebrand or codebase merge? Not answered. Branding decision deferred.
Q-AS4 What content is in the Algolia Central index? Partially answered — see wiki §06. Decision: N indices, not one mega-index. Open sub-question: which N (by content type? by vertical? by source?) — depends on R1-R6 outputs.
Q-AS5 Does the 2-panel UI ship with or after agent re-architecture? Partially answered — see wiki §12. Decision: UI refactor is a parallel workstream — replace custom hooks with native <Chat> widget + per-tool layoutComponent. Open sub-question: cutover ordering vs. agent migration steps.

AG2 (merge Elena + Bruno into one specialist, if two-agent model): Two specialists (Elena + Bruno) for v1. Re-evaluate convergence for v2. (Updated 2026-04-25, supersedes earlier "Likely yes if two-agent model.")

Part 8: Operating Principles

  1. Validation before execution when a plan comes from AI structuring
  2. Live refactor, not big-bang rewrite — Algolia Central stays demoable
  3. Move toward native Algolia, not custom reinvention
  4. Agent Studio is a tool-use platform — use it as one
  5. Contracts before code changes — name the implicit agreements first
  6. Research and agent re-architecture are BOTH mandatory, not either/or
  7. No module gets rewritten because it looks ugly — only when we know what behavior it owns and what tests protect it
  8. Treat production readiness as architecture, not QA
  9. The reference implementation IS the product — prescriptive, not a toolkit
  10. Neural search tuning is proprietary IP

Cross-references

  • Operational state (this-release task lists, R-IDs, AG-IDs, CF-IDs, dependency graph, file pointers): repo RC3-BRIEF.md
  • Agent Studio knowledge: vault Projects/Algolia-Central/Knowledge/AgentStudio/README.md
  • Active context (where are we now): vault Projects/Algolia-Central/Active-Context.md
  • Release history: vault Projects/Algolia-Central/Releases.md
  • Pivot decisions log: vault Projects/Algolia-Central/Messaging-Positioning-Pivot.md