Skip to content

Retriever upgrade#28

Merged
OscarArroyoVega merged 12 commits into
mainfrom
retriever-upgrade
Mar 12, 2026
Merged

Retriever upgrade#28
OscarArroyoVega merged 12 commits into
mainfrom
retriever-upgrade

Conversation

@OscarArroyoVega

Copy link
Copy Markdown
Member

Retriever Agent Upgrade

Summary

  • Complete rewrite of the retriever service from a simple query-response API to an agentic architecture with a ReAct loop, modular tools, and multi-source event discovery
  • Move legacy services (frontend, parser, scraper, old retriever) to legacy/ directory
  • Add pusher service for event ingestion with embeddings support

What changed

Agentic Architecture

  • ReAct-based orchestrator that reasons step-by-step before taking actions, supporting up to 5 reasoning loops per request
  • Modular tool system: QueryBuilder (Cypher generation + semantic ranking), SafetyGuard (injection detection + LlamaGuard content moderation), LocationTool, InternetSearchTool
  • LLM-powered intent classification routing queries to the right action (QUERY_DB, NEEDS_INFO, OUT_OF_SCOPE, BYE_MESSAGE, UNSAFE_INPUT)

Location-Aware Search

  • LocationTool detects proximity queries ("near me", "nearby", "cerca de mí", "in der Nähe", etc.)
  • Progressive radius expansion: starts at 5 km, widens through 10 → 15 → 20 → 30 km until at least 10 events are found
  • Geo-spatial Neo4j queries using point.distance() on venue coordinates

Parallel Internet Search

  • InternetSearchTool runs in parallel with knowledge graph queries via ThreadPoolExecutor
  • Uses Brave Search API for web discovery + LLM extraction to parse results into structured event data
  • Results labeled by source: "Verified Source" (knowledge graph) vs "Internet Source" (web) — KG results prioritized in output

Safety & Quality

  • Multi-layer safety: regex injection detection, APOC procedure blocking, LlamaGuard semantic validation
  • Read-only Cypher enforcement with forbidden pattern detection
  • Optional output safety validation (configurable, off by default for performance)

API & Streaming

  • SSE streaming endpoint (/chat/stream) with character-by-character delivery for frontend integration
  • JSON endpoint (/chat) for programmatic use
  • Request logging to JSONL for observability and evals

Evals Framework

  • Component-level evals: intent classification, query generation, safety
  • End-to-end conversation evals
  • Dataset management utilities with quality filtering and log-to-dataset extraction

Infrastructure

  • Langfuse integration for LLM tracing and observability
  • Configurable models per task (query builder, conversation, safety, extraction)
  • Docker and devcontainer setup updated for new architecture

Test plan

  • Run make test-retriever, unit tests for orchestrator, query builder, safety guard, formatters, API endpoints, error handling
  • Verify /health endpoint reports all services healthy
  • Test a search query via /chat and confirm verified results are returned with source labels
  • Test with BRAVE_SEARCH_API_KEY set and confirm internet results appear alongside verified ones
  • Test a proximity query ("events near me") with location payload and confirm progressive radius behavior
  • Test safety: injection attempts, out-of-scope queries, farewell messages
  • Verify SSE streaming works via /chat/stream with the frontend

OscarArroyoVega and others added 12 commits January 9, 2026 12:03
…deration

Implements comprehensive safety improvements including enhanced Cypher query validation with regex word boundaries, comment/string filtering to prevent false positives, dangerous APOC procedure detection, and LlamaGuard integration for input/output content moderation. Adds multi-layer security architecture with validation at input, query generation, and output stages.
Add OpenAI and OpenRouter API keys, embeddings model, and guardrail model configuration to .example.env and service configs for retriever and pusher services.
Update README to reflect the refactored architecture using tools pattern instead of agents pattern.
Remove deprecated agent files that have been replaced by the new tools-based architecture.
Add metrics tracking for monitoring component performance, latency, and token usage. Add pusher service embeddings functionality with migration script. Enhance Neo4j client with schema caching and APOC support. Improve retriever API endpoints with better error handling.
Update pyproject.toml for both retriever and pusher services with required dependencies.
Update uv.lock files for retriever and pusher services.
Ignore Claude Code artifacts directory.
Add empty line at beginning of test file per linter requirements.
Add SSE streaming endpoint compatible with frontend expectations, create event formatters to convert Neo4j data to frontend format (artist, tagline, venue, time, price), implement markdown formatting for chat display, support OpenAI-style streaming response format, maintain backward compatibility with legacy JSON endpoint.

- formatters.py: Convert Neo4j events to frontend structure
- api_sse.py: SSE streaming endpoint at /chat/stream
- FRONTEND_INTEGRATION.md: Complete integration guide
- test_formatting.py: Comprehensive formatting tests
Add LocationTool for proximity-based event queries with progressive
radius expansion (5→30 km) and geo-spatial Neo4j filtering.

Add InternetSearchTool that searches the web (Brave Search API) for
live music events in parallel with the knowledge graph query. Uses
LLM extraction to parse search results into structured event data.

Results are labeled by source: "verified" (knowledge graph) and
"internet" (web search), displayed distinctly in both markdown and
frontend formats. KG results are prioritized in merged output.

Update orchestrator ReAct loop with search_nearby action, parallel
search execution via ThreadPoolExecutor, and source-aware prompts.
Signed-off-by: Oscar Arroyo Vega <103512255+OscarArroyoVega@users.noreply.github.com>
@OscarArroyoVega OscarArroyoVega merged commit 542952f into main Mar 12, 2026
0 of 2 checks passed
@OscarArroyoVega OscarArroyoVega deleted the retriever-upgrade branch March 12, 2026 15:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant