Back to projects
LLM & Agentic Systems

Djezzy Commercial Copilot

Multi-agent business-intelligence assistant for Djezzy's commercial department: natural-language questions over 13 months of daily commercial data, answered with narrative text and live charts through a durable, asynchronous agent pipeline.

InternalNo public repoEnterprise multi-agent BI assistant / 2026

Problem

Djezzy's commercial teams depend on BI and technical staff to extract and interpret data across five feeds (Revenue, Sales, Activation, Flexy, Active Clients), each with a 13-month daily history. That dependency slows time-to-insight, bottlenecks the BI team on repetitive requests, and invites interpretation errors, most notably unfair chronological comparisons like measuring a holiday against an ordinary day a year earlier.

Solution

Build an orchestrator-led multi-agent system: a LangGraph orchestrator reasons about user intent and selects from a tool suite (guarded text-to-SQL, shared semantic memory, date normalization, and human-approved web search) instead of always translating straight to SQL. Work runs asynchronously through Temporal so heavy analytical turns never block behind a loading spinner, and results deliver in real time over Kafka and WebSocket.

Key Features

Three switchable personas (Explorer for descriptive work, Researcher for diagnostic, Planner for prescriptive) that change reasoning depth and which tools the agent can use
Natural-language-to-SQL generation validated by sqlglot before it ever touches the read-only analytical warehouse
Date-normalization engine that enforces event-aware baselines (Eid, Ramadan, exam periods, campaigns) so period comparisons stay statistically fair
Shared semantic memory over pgvector that caches solved analyses and gates hits by KPI availability and time-range validity before serving them
Human-in-the-loop web search through a domain-whitelisted MCP proxy, so the agent never reaches the open internet unsupervised
Hidden-correlation tool that cross-references approved external events against internal segments instead of trusting a naive before/after average
Asynchronous-first execution: submit returns a task ID immediately, a Temporal workflow runs the agent turn durably with bounded retries, and a Kafka-to-WebSocket path delivers the result the moment it's ready
Strict multi-modal output contract: every answer is conversational text plus chart specs, never free-form prose, so the frontend renders consistent widgets
Self-hosted LLM serving (Qwen via vLLM) instead of a third-party API, keeping commercial data inside Djezzy's own infrastructure
Role-based auth (analyst/manager/admin/viewer) with purpose-scoped JWTs and a full signup/login/refresh/reset flow

Async query pipeline

never blocks
SYNCHRONOUSChat UIReact · ViteFastAPI BFFPOST /queriestask_idreturned at oncequestionin msDURABLETemporalworkflowSemantic cachepgvectorLangGraphpersona routingtool orchestrationhand offmisstext_to_sqlsqlglot validatedwarehouse13 months, read-onlyweb searchhuman-approvedreadDELIVERYKafkacompletion eventWebSocketpush to clientanswerchart specsTEAM5 engineers · 6-week internship sprint · I led 4GUARANTEEno generated SQL runs unparsed
The two lanes are the point. Synchronous: the request returns a task_id in milliseconds and the connection is free. Durable: a Temporal workflow does the slow work and the answer arrives over a socket whenever it is ready. Every generated SQL statement is parsed by sqlglot before it reaches a read-only warehouse, and any web lookup stops for human approval.