Refactor DESIGN.md for clarity and consistency in problem definition and audience analysis

DESIGN.md

@@ -1,104 +1,103 @@
 # AIM AIE 6 Certification Challenge: AI-Driven Blog Chat Component
 
-## Task 1: Defining your Problem and Audience
+## Task 1: Defining the Problem and Audience
 
 ### Problem Statement
-Content-rich blogs are difficult for readers to navigate and extract specific information from, leading to poor information retention and reader engagement.
-
+Content-rich technical blogs are difficult to navigate, making information extraction challenging and resulting in reduced reader engagement and information retention.
 
 ### Target Audience Analysis
 
-For our first implementation, we will focus on content from [TheDataGuy](https://thedataguy.pro) blog, which caters to a technical audience primarily consisting of:
-
-1. **AI/ML Engineers & Researchers** - Professionals working on LLM applications and RAG systems who need guidance on evaluation frameworks and best practices.
-
-2. **Data Scientists & Engineers** - Individuals looking to implement robust data strategies and evaluation methodologies for AI systems.
-
-3. **Technical Leaders & Architects** - Decision-makers seeking insights on AI implementation, data strategy, and technical approaches for enterprise solutions.
+Our initial implementation focuses on [TheDataGuy](https://thedataguy.pro) blog, which serves a technical audience including:
 
-4. **Developers Building AI Applications** - Software engineers implementing AI/ML capabilities who need practical advice on topics like RAG systems, evaluation metrics, and feedback loops.
-
-5. **Data Strategists** - Professionals focused on leveraging data as a strategic asset for business success.
+1. **AI/ML Engineers & Researchers** - Professionals seeking guidance on LLM applications, RAG systems, and evaluation frameworks
+   
+2. **Data Scientists & Engineers** - Practitioners implementing data strategies and evaluation methodologies for AI systems
+   
+3. **Technical Leaders & Architects** - Decision-makers exploring AI implementation, data strategy, and enterprise solutions
+   
+4. **Developers Building AI Applications** - Engineers needing practical advice on RAG systems and evaluation metrics
+   
+5. **Data Strategists** - Professionals leveraging data as a strategic business asset
 
 
 ### Potential User Questions
 1. What is Ragas and how does it help evaluate LLM applications?
 2. How do I set up a basic evaluation workflow with Ragas?
 3. What are the key metrics to evaluate RAG systems?
-4. How can I generate synthetic test data for evaluating my RAG system?
-5. How do I create custom metrics in Ragas for my specific use case?
+4. How can I generate synthetic test data for my RAG system?
+5. How do I create custom metrics in Ragas for specific use cases?
 6. What's the difference between Faithfulness and Factual Correctness metrics?
-7. How can I build a research agent with RSS feed support like the one described in your blog?
-8. What technologies did you use to build your research agent?
-9. How can I implement feedback loops to continuously improve my LLM application?
-10. Why do you consider data strategy so important for business success?
+7. How can I build a research agent with RSS feed support?
+8. What technologies are optimal for building a research agent?
+9. How can I implement feedback loops to improve my LLM application?
+10. Why is data strategy critical for business success?
 
-These questions align with the main themes in the blog posts, which cover LLM evaluation, RAG systems, custom development of AI tools, and data strategy.
+These questions align with the blog's main themes: LLM evaluation, RAG systems, AI tool development, and data strategy.
 
 
 ## Task 2: Proposed Solution
 
-We propose an AI-driven chat assistant for [TheDataGuy](https://thedataguy.pro)'s blog that enables readers to interactively explore technical content. This component will:
+We propose an AI-driven chat assistant for [TheDataGuy](https://thedataguy.pro)'s blog that enables readers to interactively explore technical content. This solution will:
 
-- Provide contextually relevant responses about RAG systems, evaluation metrics, and data strategy
-- Allow users to ask clarifying questions about complex concepts without searching across multiple articles
-- Deliver code examples and detailed explanations tailored to the user's technical background
-- Function as a knowledge companion that has internalized the blog's expertise
-- Create a personalized learning experience that adapts to each visitor's specific interests
+- Provide contextually relevant responses on RAG systems, evaluation metrics, and data strategy
+- Enable users to ask clarifying questions without searching across multiple articles
+- Deliver code examples and explanations tailored to users' technical backgrounds
+- Function as a knowledge companion with the blog's expertise
+- Create personalized learning experiences based on visitors' specific interests
 
-The solution transforms passive reading into an interactive dialogue, significantly enhancing information discovery and retention.
+This solution transforms passive reading into interactive dialogue, enhancing information discovery and retention.
 
 ## Technology Stack
 
 1. **LLM Architecture**: 
-    - **Primary Model**: OpenAI `gpt-4.1` - Handles complex tasks including synthetic data generation, sophisticated evaluation workflows, and fine-tuning questions development
-    - **Inference Model**: OpenAI `gpt-4o-mini` - Powers the user-facing chat application, offering an optimal balance between performance and cost-efficiency for real-time responses
+   - **Primary Model**: OpenAI `gpt-4.1` - For complex tasks including synthetic data generation and evaluation workflows
+   - **Inference Model**: OpenAI `gpt-4o-mini` - Powers the chat application with optimal performance/cost balance
 
 2. **Embedding Model**: 
-    - **Base Model**: `Snowflake/snowflake-arctic-embed-l` - Provides foundation embedding capabilities optimized for technical content with robust semantic understanding
-    - **Fine-tuned Model**: `mafzaal/thedataguy_arctic_ft` - Custom-tuned embedding model using query-context pairs extracted from blog content, enhancing retrieval accuracy for domain-specific AI terminology and concepts
+   - **Base Model**: `Snowflake/snowflake-arctic-embed-l` - Foundation embedding capabilities for technical content
+   - **Fine-tuned Model**: `mafzaal/thedataguy_arctic_ft` - Custom-tuned using blog-specific query-context pairs
 
-3. **Orchestration**: LangChain - Provides flexible components for building LLM applications with robust RAG pipelines and context management tailored for technical blog content.
+3. **Orchestration**: LangChain - Flexible components for LLM applications with robust RAG pipelines and context management
 
-4. **Vector Database**: Qdrant - Stores embeddings generated through a `pipeline.py` script which also functions as a GitHub workflow to automatically incorporate new blog posts. Provides robust filtering capabilities for content categorization and delivers high performance with manageable operational complexity.
+4. **Vector Database**: Qdrant - Stores embeddings via `pipeline.py` with GitHub workflow automation for new blog posts
 
-5. **Monitoring**: LangSmith - Integrates seamlessly with LangChain while providing comprehensive tracing, debugging, and performance monitoring specific to LLM applications.
+5. **Monitoring**: LangSmith - Seamless LangChain integration with comprehensive tracing and performance monitoring
 
-6. **Evaluation**: Ragas - Aligns perfectly with [TheDataGuy](https://thedataguy.pro)'s expertise and blog content, enabling evaluation of the chat system on metrics like faithfulness and relevance. See following notebooks 
-    - [05_SDG_Eval](/py-src/notebooks/05_SDG_Eval.ipynb)
-    - [07_Fine_Tuning_Dataset](/py-src/notebooks/07_Fine_Tuning_Dataset.ipynb)
-    - [07_Fine_Tune_Embeddings](/py-src/notebooks/07_Fine_Tune_Embeddings.ipynb)
-    - [07_Fine_Tune_Eval](/py-src/notebooks/07_Fine_Tune_Eval.ipynb)
+6. **Evaluation**: Ragas - Perfect alignment with [TheDataGuy](https://thedataguy.pro)'s expertise for metrics like faithfulness and relevance:
+   - [05_SDG_Eval](/py-src/notebooks/05_SDG_Eval.ipynb)
+   - [07_Fine_Tuning_Dataset](/py-src/notebooks/07_Fine_Tuning_Dataset.ipynb)
+   - [07_Fine_Tune_Embeddings](/py-src/notebooks/07_Fine_Tune_Embeddings.ipynb)
+   - [07_Fine_Tune_Eval](/py-src/notebooks/07_Fine_Tune_Eval.ipynb)
     
 7. **User Interface**: 
-    - **Current Implementation**: Chainlit - Provides rapid prototyping capabilities with built-in chat UI components
-    - **Production Version**: Custom Svelte component - Delivers a lightweight, responsive interface that seamlessly integrates with the blog's existing design language while minimizing impact on page load performance
+   - **Current**: Chainlit - Rapid prototyping with built-in chat UI components
+   - **Production**: Custom Svelte component - Lightweight, responsive interface integrating with the blog's design
 
 ## Serving & Inference
-- **Development Environment**: Prototype deployed on Hugging Face Spaces for rapid testing and validation, visit [Let's Talk](https://huggingface.co/spaces/mafzaal/lets_talk)
+- **Development**: Prototype on Hugging Face Spaces ([Let's Talk](https://huggingface.co/spaces/mafzaal/lets_talk))
 ### Future
-- **Production Infrastructure**: Azure Container Apps - Provides event-driven autoscaling and enterprise-grade security while integrating with [TheDataGuy](https://thedataguy.pro)'s existing Azure-based technical ecosystem
-- **API Layer**: FastAPI - Delivers high-performance endpoints with automatic OpenAPI documentation, facilitating seamless integration with the blog's frontend
-- **Deployment Strategy**: CI/CD pipeline using GitHub Actions - Ensures consistent testing and deployment with automated content indexing whenever new blog posts are published
+- **Production**: Azure Container Apps - Event-driven autoscaling with enterprise-grade security
+- **API Layer**: FastAPI - High-performance endpoints with automatic OpenAPI documentation
+- **Deployment**: CI/CD via GitHub Actions - Consistent testing with automated content indexing for new blog posts
 
 ## Agentic Reasoning
 
-Agentic reasoing will be added in future version.
+Agentic reasoning will be added in a future version.
 
 
 # Task 3: Dealing with the Data
 
 ## Data Collection
 
-The blog data from [TheDataGuy](https://thedataguy.pro) was collected and processed for our AI-driven chat component. Below is a summary of the collected blog posts:
+The blog data from [TheDataGuy](https://thedataguy.pro) was collected and processed for our chat component. Summary of collected posts:
 
-| Title | Date | Text Length | URL |
-|-------|------|-------------|-----|
+| Title | Date | Length | URL |
+|-------|------|--------|-----|
 | "Coming Back to AI Roots - My Professional Journey" | 2025-04-14 | 5,827 | [Link](https://thedataguy.pro/blog/coming-back-to-ai-roots/) |
 | "Data is King: Why Your Data Strategy IS Your Business Strategy" | 2025-04-15 | 6,197 | [Link](https://thedataguy.pro/blog/data-is-king/) |
 | "A C# Programmer's Perspective on LangChain Expression Language" | 2025-04-16 | 3,361 | [Link](https://thedataguy.pro/blog/langchain-experience-csharp-perspective/) |
 | "Building a Research Agent with RSS Feed Support" | 2025-04-20 | 7,320 | [Link](https://thedataguy.pro/blog/building-research-agent/) |
-| "Part 1: Introduction to Ragas: The Essential Evaluation Framework for LLM Applications" | 2025-04-26 | 6,999 | [Link](https://thedataguy.pro/blog/introduction-to-ragas/) |
+| "Part 1: Introduction to Ragas: The Essential Evaluation Framework" | 2025-04-26 | 6,999 | [Link](https://thedataguy.pro/blog/introduction-to-ragas/) |
 | "Part 2: Basic Evaluation Workflow with Ragas" | 2025-04-26 | 11,223 | [Link](https://thedataguy.pro/blog/basic-evaluation-workflow-with-ragas/) |
 | "Part 3: Evaluating RAG Systems with Ragas" | 2025-04-26 | 8,811 | [Link](https://thedataguy.pro/blog/evaluating-rag-systems-with-ragas/) |
 | "Part 4: Generating Test Data with Ragas" | 2025-04-27 | 14,682 | [Link](https://thedataguy.pro/blog/generating-test-data-with-ragas/) |
@@ -112,18 +111,17 @@ The blog data from [TheDataGuy](https://thedataguy.pro) was collected and proces
 
 ## Chunking Strategy
 
-For our blog chat component, we evaluated multiple chunking approaches to optimize retrieval performance:
+For our blog chat component, we evaluated multiple chunking approaches:
 
-1. **Initial Experimental Approach**: 
-    - Used RecursiveCharacterTextSplitter with chunk size of 1000 characters and 200 character overlap
-    - This approach provided granular context chunks for both baseline testing and embedding fine-tuning
+1. **Initial Experiment**: 
+   - RecursiveCharacterTextSplitter with 1000-character chunks and 200-character overlap
+   - Provided granular context chunks for baseline testing and embedding fine-tuning
 
-2. **Final Implementation Decision**:
-    - Opted to use whole blog posts as individual chunks rather than smaller text segments
-    - This approach ensures complete retention of article context and coherence
-    - Each blog post is treated as a distinct retrievable unit in the vector database
+2. **Final Implementation**:
+   - Whole blog posts as individual chunks to preserve complete article context
+   - Each post treated as a distinct retrievable unit in the vector database
 
-The whole-document chunking strategy was selected to retrieve relevant full blog posts for response generation. This approach preserves article narrative integrity while providing sufficient context for accurate responses.
+The whole-document strategy preserves article narrative integrity while providing sufficient context for accurate responses.
 
 ## Data Statistics Summary
 
@@ -131,25 +129,23 @@ The whole-document chunking strategy was selected to retrieve relevant full blog
 |-----------|-------|
 | Total Blog Posts | 14 |
 | Total Characters | 106,275 |
-| Minimum Post Length | 1,900 characters |
-| Maximum Post Length | 13,468 characters |
-| Average Post Length | 7,591 characters |
-
-With average post length under 8,000 characters, whole-document retrieval remains efficient while eliminating contextual fragmentation that occurs with smaller chunks. This approach optimizes for content coherence over granularity, supporting comprehensive responses to technical queries about RAG systems, evaluation frameworks, and data strategy.
+| Minimum Post Length | 1,900 chars |
+| Maximum Post Length | 13,468 chars |
+| Average Post Length | 7,591 chars |
 
+With average post length under 8,000 characters, whole-document retrieval remains efficient while maintaining content coherence, supporting comprehensive responses about RAG systems, evaluation frameworks, and data strategy.
 
 ## Tools and APIs
-We will also using [RSS Feed](https://thedataguy.pro/rss.xml) with tool call to get latest posts which are not yet vectorized
-
+We will use the [RSS Feed](https://thedataguy.pro/rss.xml) with tool calls to retrieve latest posts not yet vectorized.
 
 # Task 4: Building a Quick End-to-End Prototype
 
-Live demo at [Let's Talk](https://huggingface.co/spaces/mafzaal/lets_talk) 
+Live demo available at [Let's Talk](https://huggingface.co/spaces/mafzaal/lets_talk) 
 
 
 # Task 5: Creating a Golden Test Data Set
 
-Synthetic data is available at [Testset](/evals/testset_2.csv), [Eval set](/evals/rag_eval_2.csv) and [Results](/evals/rag_eval_result_2.csv) and here is summary
+Synthetic data available at [Testset](/evals/testset_2.csv), [Eval set](/evals/rag_eval_2.csv) and [Results](/evals/rag_eval_result_2.csv).
 
 ## Evaluation Results Summary
 
@@ -162,16 +158,15 @@ Synthetic data is available at [Testset](/evals/testset_2.csv), [Eval set](/eval
 | Context Recall | 0.1905 |
 | Context Entity Recall | 0.1503 |
 
-These results indicate strong faithfulness but opportunities for improvement in contextual relevance and factual accuracy. The relatively low context recall and entity recall scores suggest that the retrieval component may need refinement to better surface relevant information from the blog content.
+These results show strong faithfulness but opportunities for improvement in contextual relevance and factual accuracy. The low context recall and entity recall scores suggest the retrieval component needs refinement to better surface relevant information from blog content.
 
 # Task 6: Fine-Tuning Open-Source Embeddings
 
-Fine tuning dataset is available at [Link](/evals/ft_questions.csv) and also uploaded at [thedataguy_embed_ft](https://huggingface.co/datasets/mafzaal/thedataguy_embed_ft) and notebook is available at [07_Fine_Tune_Embeddings](/py-src/notebooks/07_Fine_Tune_Embeddings.ipynb)
-
+Fine-tuning dataset available at [Link](/evals/ft_questions.csv) and uploaded to [thedataguy_embed_ft](https://huggingface.co/datasets/mafzaal/thedataguy_embed_ft). Implementation in [07_Fine_Tune_Embeddings](/py-src/notebooks/07_Fine_Tune_Embeddings.ipynb).
 
 # Task 7: Assessing Performance
 
-Following is evalation based on finetuned embedding model.
+Evaluation based on fine-tuned embedding model:
 
 ## Fine-Tuned Embedding Model Evaluation Results
 
@@ -184,5 +179,5 @@ Following is evalation based on finetuned embedding model.
 | Context Recall | 0.2500 |
 | Context Entity Recall | 0.2175 |
 
-The fine-tuned embedding model shows improved answer relevancy and context recall compared to the base model. While faithfulness decreased, the system demonstrates better ability to retrieve relevant information. These results suggest that the fine-tuning process has shifted the model's strengths toward delivering more contextually appropriate responses, though further optimization is needed to improve faithfulness and factual accuracy.
+The fine-tuned model shows improved answer relevancy and context recall compared to the base model. While faithfulness decreased, the system better retrieves relevant information. These results suggest the fine-tuning process shifted strengths toward contextually appropriate responses, though further optimization is needed for faithfulness and factual accuracy.