🏏 CricMind — About the Project
What Inspired Us
Cricket is the second most watched sport on the planet, yet when you ask an AI "Who is the best death bowler right now?" or "How has India's batting order evolved in the BGT series?" — you get generic, outdated answers. Every existing AI tool either has stale knowledge or requires someone to manually feed it data first.
That gap inspired CricMind. What if an AI could research cricket like a human analyst would — autonomously, on demand — and remember everything it learns forever?
What We Learned
Building CricMind taught us that the hardest part of agentic AI is not the LLM — it's orchestration and memory. Key lessons:
- Elasticsearch is far more powerful as a living knowledge store than a static search index. KNN vector search + BM25 + aggregations together create something genuinely intelligent.
- Multi-agent pipelines need clear contracts between agents. The Scout must produce research the Analyst can parse; the Analyst must produce JSON the Indexer can embed. Breaking those contracts breaks everything.
- Streaming via SSE transforms the user experience. Watching agents work in real time makes AI feel transparent rather than magical.
On the math side, semantic similarity between a query $q$ and a document $d$ is computed as cosine similarity over their embeddings:
$$ \text{similarity}(q, d) = \frac{\vec{q} \cdot \vec{d}}{|\vec{q}||\vec{d}|} $$
Elasticsearch's KNN search finds the top-$k$ documents maximising this score across 1536-dimensional embedding space — making retrieval fast even as the knowledge base scales to thousands of documents.
How We Built It
CricMind is built on a three-agent pipeline backed by Elastic Cloud:
1. Scout Agent (GPT-4o) Receives a cricket topic and generates deep research — player stats, match context, tactical trends, historical records.
2. Analyst Agent (GPT-4o) Reads the Scout's output and extracts structured JSON: categorised insights, named entities, confidence scores, and follow-up recommendations.
3. Indexer Agent (GPT-4o + text-embedding-3-small) Embeds each insight as a $\mathbb{R}^{1536}$ vector and stores it in Elastic Cloud with rich metadata: category, tags, entities, confidence, and source topic.
The backend is FastAPI with async SSE streaming so every agent decision is pushed to the frontend in real time. The frontend is React with a live activity feed, knowledge explorer, and streaming chat interface.
Every chat query performs KNN retrieval:
$$ \text{top-}k = \underset{d \in \mathcal{D}}{\arg\max^k} \ \frac{\vec{q} \cdot \vec{d}}{|\vec{q}||\vec{d}|} $$
...then passes retrieved context to GPT-4o to generate a grounded, cited answer.
Challenges We Faced
1. Python 3.14 compatibility
Our target machine had Python 3.14 — too new for pre-built pydantic
wheels. Solved by switching to flexible version pins so pip resolved
compatible binaries automatically.
2. Elastic Cloud connection
The app initially defaulted to localhost:9200 because .env wasn't
loading at startup. Fixed by calling load_dotenv() before any module
imports — a subtle but critical ordering issue in FastAPI's lifespan
context.
3. Structured output reliability
The Analyst Agent occasionally returned malformed JSON when the research
was very long. Solved by switching to OpenAI's response_format:
{ type: "json_object" } mode, which enforces valid JSON output at the
model level.
4. Streaming across the full stack
Getting SSE to flow correctly from Elasticsearch → FastAPI async
generator → React EventSource required careful handling of backpressure
and connection cleanup. Stale connections silently blocked new research
runs until we added explicit es.close() on completion and error.
5. Making the knowledge base feel alive
The biggest UX challenge was showing that the KB was growing in real
time. We solved this with a polling stats bar that updates every 8
seconds, and per-document document_indexed SSE events that visually
pop each new insight into the feed as it's stored.
What's Next
- Web search integration — let the Scout Agent pull live match scores and breaking news via search APIs
- Knowledge graph visualisation — render entity relationships (player ↔ team ↔ tournament) as an interactive graph
- Contradiction detection — flag when new research conflicts with existing indexed knowledge
- Multi-sport support — the Scout → Analyst → Indexer pipeline is fully domain-agnostic
Built With
- ai
- async
- cloud
- css
- dense
- elastic
- embeddings
- fastapi
- hooks
- javascript
- knn)
- llms
- pydantic
- python
- react
- rest
- uvicorn
- vite