Initial commit

.gitattributes

@@ -1,3 +1,4 @@
+# Common large ML / data files
 *.7z filter=lfs diff=lfs merge=lfs -text
 *.arrow filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
@@ -24,13 +25,13 @@
 *.rar filter=lfs diff=lfs merge=lfs -text
 *.safetensors filter=lfs diff=lfs merge=lfs -text
 saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
 *.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
 *.tgz filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
 *.wasm filter=lfs diff=lfs merge=lfs -text
 *.xz filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
-kb/vector_db/*.faiss filter=lfs diff=lfs merge=lfs -text
+kb/vector_db/*.faiss filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,11 +1,30 @@
-.env
-.env.local
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+venv/
+.venv/
+.env/
+pip-log.txt
+pip-delete-this-directory.txt
 
+.env
+.env.*
+*.env
 *.log
 nutrition_planner.log
+.vscode/
+.idea/
+*.sublime-*
 
-__pycache__/
-venv/
-*.pyc
+kb/raw_data/
+kb/raw_data/pdf/
+kb/vector_db/vector_index_metadata.json
 
-kb/raw_data/pdf/
+*.bak
+*.swp
+*.tmp
+.DS_Store
+Thumbs.db

README.md

@@ -1,14 +1,38 @@
----
-title: Pawspal Nutrition Api
-emoji: 📊
-colorFrom: indigo
-colorTo: blue
-sdk: docker
-pinned: false
-license: apache-2.0
-app_port: 7860
-base_path: /docs
-short_description: AI-Powered Pet Health nutrition & diet planner
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# PawsPalConnect Pet Nutrition API
+
+Generate personalized veterinary-grade nutrition plans for dogs and cats.
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run API
+uvicorn app:app --reload
+```
+
+
+## API 
+
+**POST** `/nutrition/plan`
+
+```json
+{
+  "pet_type": "dog",
+  "breed": "Golden Retriever",
+  "gender": "male",
+  "pregnant_lactating": "none",
+  "weight_kg": 14,
+  "activity_level": "low",
+  "life_stage": "adult",
+  "bcs": 4,
+  "neutered_spayed": "yes",
+  "allergies": "almonds",
+  "diseases": "distemper",
+  "diet_preference": "vegetarian",
+  "current_food_format": "wet"
+}
+```
+
+**Response**: Personalized nutrition targets + meal plans with ingredients and preparation instructions

app.py

@@ -1,10 +1,114 @@
+from contextlib import asynccontextmanager
+import logging
+
 from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
 from router import router
+from kb.document_processor import DocumentProcessor
+from rag.embed import EmbeddingLayer
+from rag.vectorstore import VectorStore
+from rag.retriever import Retriever, KnowledgeRetriever
+from llm.gemini_client import GeminiClient
+from sentence_transformers import CrossEncoder
+from config import settings
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+class AppState:
+    embedder: EmbeddingLayer = None
+    vectorstore: VectorStore = None
+    cross_encoder: CrossEncoder = None
+    retriever: KnowledgeRetriever = None
+    llm_client: GeminiClient = None
+
+state = AppState()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+   
+    logger.info("STARTING PAWSPALCONNECT NUTRITION API")
+    
+    logger.info("Loading embedding model...")
+    try:
+        state.embedder = EmbeddingLayer()
+        state.embedder._load_model()  # Load model at startup
+        logger.info(f"Embedding model loaded: {settings.EMBEDDING_MODEL}")
+    except Exception as e:
+        logger.error(f"Failed to load embedder: {e}")
+        raise
+    
+    logger.info("Loading vector store...")
+    try:
+        state.vectorstore = VectorStore.create_vectorstore()
+        if not state.vectorstore.load():
+            logger.warning("No existing vector store found - needs rebuild")
+            pdf_dir = settings.RAW_DATA_DIR / "pdf"
+            processor = DocumentProcessor.create_processor()
+            documents = processor.process_all_pdfs(pdf_dir)
+            texts = [doc.page_content for doc in documents]
+            metadatas = [doc.metadata for doc in documents]
+            embeddings = state.embedder.embed_texts(texts)
+            state.vectorstore.add(embeddings, texts, metadatas)
+            state.vectorstore.persist()
+            logger.info(f"Vector store built: {len(documents)} chunks")
+        else:
+            logger.info(f"Vector store loaded: {len(state.vectorstore.records)} chunks")
+    except Exception as e:
+        logger.error(f"Failed to load vector store: {e}")
+        raise
+    
+    logger.info("Loading reranking model...")
+    try:
+        state.cross_encoder = CrossEncoder(settings.RERANK_MODEL)
+        logger.info(f"Cross-encoder loaded: {settings.RERANK_MODEL}")
+    except Exception as e:
+        logger.error(f"Failed to load cross-encoder: {e}")
+        raise
+    
+    logger.info("Initializing retriever...")
+    try:
+        retriever = Retriever(state.embedder, state.vectorstore, state.cross_encoder)
+        state.retriever = KnowledgeRetriever(retriever)
+        logger.info("Retriever ready")
+    except Exception as e:
+        logger.error(f"Failed to initialize retriever: {e}")
+        raise
+    
+    logger.info("Initializing Gemini client...")
+    try:
+        state.llm_client = GeminiClient.create()
+        logger.info("Gemini ready")
+    except Exception as e:
+        logger.error(f"Failed to initialize Gemini: {e}")
+        raise
+    
+    logger.info("API STARTUP COMPLETE")
+    
+    yield  
+    
+    logger.info("Shutting down...")
 
 app = FastAPI(
-    title="PawsPal Pet Nutrition API",
-    version="1.0.0",
-    )
+    title="PawsPalConnect Pet Nutrition API",
+    version="2.0.0",
+    description="Generate personalized veterinary-grade nutrition plans for dogs and cats.",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
 
 app.include_router(router)
-    
+
+# Make state accessible to routes
+app.state.app_state = state

chunker.py

@@ -1,165 +0,0 @@
-"""
-Semantic text chunking for documents.
-"""
-import logging
-from typing import List, Tuple, Dict, Any
-import re
-from dataclasses import dataclass
-from config import settings
-
-logger = logging.getLogger(__name__)
-
-@dataclass
-class DocumentChunk:
-    content: str
-    metadata: Dict[str, Any]
-
-
-class SemanticChunker:
-
-    #Splits by headings, merges small chunks and maintains overlap.
-
-    @staticmethod
-    def create_chunker() -> "SemanticChunker":
-        return SemanticChunker()
-
-    def __init__(self):
-        self.chunk_size = settings.CHUNK_SIZE
-        self.overlap_ratio = settings.CHUNK_OVERLAP_RATIO
-        self.min_chunk_size = settings.MIN_CHUNK_SIZE
-        self.drop_front_matter_pages = settings.DROP_FRONT_MATTER_PAGES
-
-    def chunk_document(self, content: str, source_file: str) -> Tuple[List[DocumentChunk], Dict[str, Any]]:
-        
-        # Chunk document semantically. Returns chunks and stats.
-        pages = content.split("--- Page")
-        if len(pages) > self.drop_front_matter_pages:
-            content = "--- Page".join(pages[self.drop_front_matter_pages:])
-        else:
-            logger.warning("Document has fewer pages than drop_front_matter_pages")
-
-        sections = self._split_by_headings(content)
-
-        merged_sections = self._merge_small_sections(sections)
-
-        chunks = self._create_overlapping_chunks(merged_sections, source_file)
-
-        stats = {
-            "total_sections": len(sections),
-            "merged_sections": len(merged_sections),
-            "final_chunks": len(chunks),
-        }
-
-        return chunks, stats
-
-    def _split_by_headings(self, content: str) -> List[Dict[str, Any]]:
-
-        # Pattern for headings (# ## ### etc.)
-        heading_pattern = r'(^#{1,6}\s+.*$)'
-        parts = re.split(heading_pattern, content, flags=re.MULTILINE)
-
-        sections = []
-        current_heading = ""
-        current_content = []
-
-        for part in parts:
-            if re.match(heading_pattern, part.strip()):
-
-                if current_content:
-                    sections.append({
-                        "heading": current_heading,
-                        "content": "\n".join(current_content).strip(),
-                    })
-       
-                current_heading = part.strip()
-                current_content = [part]
-            else:
-                current_content.append(part)
-
-        if current_content:
-            sections.append({
-                "heading": current_heading,
-                "content": "\n".join(current_content).strip(),
-            })
-
-        return sections
-
-    def _merge_small_sections(self, sections: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-
-        merged = []
-        current = None
-
-        for section in sections:
-            content_tokens = len(section["content"].split())  
-
-            if current is None:
-                current = section.copy()
-            elif len(current["content"].split()) + content_tokens < self.min_chunk_size:
-                # Merge
-                current["content"] += "\n\n" + section["content"]
-                current["heading"] += " + " + section["heading"]
-            else:
-                merged.append(current)
-                current = section.copy()
-
-        if current:
-            merged.append(current)
-
-        return merged
-
-    def _create_overlapping_chunks(self, sections: List[Dict[str, Any]], source_file: str) -> List[DocumentChunk]:
-    
-        chunks = []
-        chunk_id = 0
-        overlap_tokens = int(self.chunk_size * self.overlap_ratio)
-
-        current_chunk_content = ""
-        current_chunk_sections = []
-        page_start = 1  
-
-        for section in sections:
-            section_tokens = len(section["content"].split())
-
-            if len(current_chunk_content.split()) + section_tokens > self.chunk_size:
-                # Create chunk
-                if current_chunk_content:
-                    chunk = DocumentChunk(
-                        content=current_chunk_content.strip(),
-                        metadata={
-                            "chunk_id": chunk_id,
-                            "source_file": source_file,
-                            "page_range": f"{page_start}-",  
-                            "section_heading": current_chunk_sections[0]["heading"] if current_chunk_sections else "",
-                        }
-                    )
-                    chunks.append(chunk)
-                    chunk_id += 1
-
-                # Start new chunk with overlap
-                overlap_content = self._get_overlap_content(current_chunk_content, overlap_tokens)
-                current_chunk_content = overlap_content + "\n\n" + section["content"]
-                current_chunk_sections = [section]
-            else:
-                current_chunk_content += "\n\n" + section["content"]
-                current_chunk_sections.append(section)
-
-        if current_chunk_content:
-            chunk = DocumentChunk(
-                content=current_chunk_content.strip(),
-                metadata={
-                    "chunk_id": chunk_id,
-                    "source_file": source_file,
-                    "page_range": f"{page_start}-",
-                    "section_heading": current_chunk_sections[0]["heading"] if current_chunk_sections else "",
-                }
-            )
-            chunks.append(chunk)
-
-        return chunks
-
-    def _get_overlap_content(self, content: str, overlap_tokens: int) -> str:
-    
-        words = content.split()
-        if len(words) <= overlap_tokens:
-            return content
-        return " ".join(words[-overlap_tokens:])

config.py

@@ -13,11 +13,9 @@ class Settings(BaseSettings):
     PROCESSED_DOCS_DIR: Path = BASE_DIR / "processed_docs"
     VECTOR_DB_DIR: Path = BASE_DIR / "kb" / "vector_db"
 
-    # Chunking
     CHUNK_SIZE: int = 1200
     CHUNK_OVERLAP_RATIO: float = 0.12
     MIN_CHUNK_SIZE: int = 250
-    DROP_FRONT_MATTER_PAGES: int = 30
 
     # Retrieval
     RETRIEVAL_TOP_K: int = 20
@@ -38,27 +36,125 @@ class Settings(BaseSettings):
 
     # APIs
     USDA_API_KEY: str
+    USDA_BASE_URL: str = "https://api.nal.usda.gov/fdc/v1"
+    USDA_TIMEOUT: int = 20
     LANGSMITH_API_KEY: str
 
     # Logging
     LOG_LEVEL: str = "INFO"
-
+    
     # MER Multipliers 
-    MER_MULTIPLIERS: Dict[str, Dict[str, float]] = {
+    ENERGY_MULTIPLIERS: Dict[str, Dict[str, float]] = {
         "dog": {
             "adult_intact": 1.8,
             "adult_neutered": 1.6,
+            "adult_obesity_prone": 1.4,
             "puppy_under_4m": 3.0,
             "puppy_over_4m": 2.0,
+            "pregnant": 1.8,  
+            "lactating_peak": 3.0,     
+            "senior_active": 1.6,
+            "senior_sedentary": 1.4,
         },
         "cat": {
             "adult_intact": 1.4,
             "adult_neutered": 1.2,
+            "adult_obesity_prone": 1.0,
             "kitten": 2.5,
+            "pregnant": 1.4,
+            "lactating_peak": 2.5,
+            "senior_active": 1.2,
+            "senior_sedentary": 1.1,
+        }
+    }
+    
+    MACRONUTRIENT_TARGETS: Dict[str, Dict[str, Dict[str, float]]] = {
+        "dog": {
+            "adult_maintenance": {
+                "protein_pct": 20.0,  
+                "fat_pct": 25.0,
+                "min_protein_pct": 18.0,
+                "max_protein_pct": 35.0,
+                "min_fat_pct": 20.0,
+                "max_fat_pct": 40.0,
+            },
+            "puppy_growth": {
+                "protein_pct": 25.0,
+                "fat_pct": 30.0,
+                "min_protein_pct": 22.5,
+                "max_protein_pct": 35.0,
+                "min_fat_pct": 25.0,
+                "max_fat_pct": 45.0,
+            },
+            "senior": {
+                "protein_pct": 22.0,  
+                "fat_pct": 20.0,
+                "min_protein_pct": 20.0,
+                "max_protein_pct": 30.0,
+                "min_fat_pct": 15.0,
+                "max_fat_pct": 30.0,
+            },
+        },
+        "cat": {
+            "adult_maintenance": {
+                "protein_pct": 30.0,  
+                "fat_pct": 30.0,
+                "min_protein_pct": 26.0,
+                "max_protein_pct": 45.0,
+                "min_fat_pct": 22.0,
+                "max_fat_pct": 40.0,
+            },
+            "kitten_growth": {
+                "protein_pct": 35.0,
+                "fat_pct": 35.0,
+                "min_protein_pct": 30.0,
+                "max_protein_pct": 50.0,
+                "min_fat_pct": 25.0,
+                "max_fat_pct": 45.0,
+            },
+            "senior": {
+                "protein_pct": 32.0,
+                "fat_pct": 25.0,
+                "min_protein_pct": 28.0,
+                "max_protein_pct": 40.0,
+                "min_fat_pct": 20.0,
+                "max_fat_pct": 35.0,
+            },
+        }
+    }
+
+    ENERGY_DENSITIES: Dict[str, float] = {
+        "protein": 4.0,
+        "carbohydrate": 4.0,
+        "fat": 9.0,
+    }
+    
+    DIGESTIBILITY_FACTOR: float = 0.9
+    
+    WATER_ML_PER_KCAL: float = 1.0
+    
+    WATER_MULTIPLIERS: Dict[str, float] = {
+        "lactating": 2.0,
+        "pregnant": 1.5,
+        "puppy": 1.5,
+        "kitten": 1.5,
+        "senior": 1.2,
+        "high_activity": 1.5,
+    }
+    
+    WEIGHT_RANGES: Dict[str, Dict[str, tuple]] = {
+        "dog": {
+            "toy": (0.5, 5.0),
+            "small": (5.0, 10.0),
+            "medium": (10.0, 25.0),
+            "large": (25.0, 45.0),
+            "giant": (45.0, 90.0),
+        },
+        "cat": {
+            "all": (2.0, 12.0), 
         }
     }
 
-    # Nutrition Rules 
     NUTRITION_RULES: Dict[str, Dict[str, Any]] = {
         "senior_adjustment": {
             "condition": {"life_stage": "senior"},

kb/document_processor.py

@@ -0,0 +1,143 @@
+import logging
+from typing import List, Dict, Any
+from pathlib import Path
+
+from langchain_community.document_loaders import PyMuPDFLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain.schema import Document
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class DocumentProcessor:
+    
+    def __init__(self):
+        """Initialize document processor with configured text splitter."""
+        self.text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=settings.CHUNK_SIZE,
+            chunk_overlap=int(settings.CHUNK_SIZE * settings.CHUNK_OVERLAP_RATIO),
+            length_function=len,
+            separators=["\n\n", "\n", ". ", " ", ""],
+            is_separator_regex=False,
+        )
+        logger.debug(
+            f"Initialized DocumentProcessor: chunk_size={settings.CHUNK_SIZE}, "
+            f"overlap={int(settings.CHUNK_SIZE * settings.CHUNK_OVERLAP_RATIO)}"
+        )
+    
+    @staticmethod
+    def create_processor() -> "DocumentProcessor":
+        """Factory method to create processor instance."""
+        return DocumentProcessor()
+    
+    def process_pdf(self, pdf_path: Path) -> List[Document]:
+       
+        logger.info(f"Processing PDF: {pdf_path.name}")
+        
+        try:
+            loader = PyMuPDFLoader(str(pdf_path))
+            raw_docs = loader.load()
+            
+            logger.info(f"Loaded {len(raw_docs)} pages from {pdf_path.name}")
+            
+            chunks = self.text_splitter.split_documents(raw_docs)
+            
+            logger.info(f"Split into {len(chunks)} chunks from {pdf_path.name}")
+        
+            for i, chunk in enumerate(chunks):
+                chunk.metadata = {
+                    "chunk_id": f"{pdf_path.stem}_{i}",
+                    "source_file": pdf_path.name,
+                    "page": chunk.metadata.get("page", 0),  # Preserve page number
+                    "species": self._extract_species(chunk.page_content, pdf_path.name),
+                    "topic": self._extract_topic(chunk.page_content),
+                }
+            
+            logger.info(f"Created {len(chunks)} enriched chunks from {pdf_path.name}")
+            
+            return chunks
+        
+        except Exception as e:
+            logger.error(f"Failed to process {pdf_path.name}: {e}")
+            raise
+    
+    def _extract_species(self, content: str, filename: str) -> str:
+        
+        content_lower = content.lower()
+        filename_lower = filename.lower()
+        
+        has_dog = (
+            "dog" in content_lower or 
+            "canine" in content_lower or 
+            "dog" in filename_lower or
+            "puppy" in content_lower
+        )
+        has_cat = (
+            "cat" in content_lower or 
+            "feline" in content_lower or 
+            "cat" in filename_lower or
+            "kitten" in content_lower
+        )
+        
+        if has_dog and has_cat:
+            return "both"
+        elif has_dog:
+            return "dog"
+        elif has_cat:
+            return "cat"
+        else:
+            return "general"
+    
+    def _extract_topic(self, content: str) -> str:
+        
+        content_lower = content.lower()
+        
+        topics = {
+            "nutrition": ["nutrient", "protein", "vitamin", "mineral", "diet", "energy", "calorie"],
+            "feeding": ["feed", "meal", "portion", "schedule", "frequency"],
+            "health": ["disease", "condition", "medical", "health", "disorder", "illness"],
+            "safety": ["toxic", "danger", "avoid", "harmful", "poisonous", "forbidden"],
+            "pregnancy": ["pregnant", "lactating", "gestation", "nursing", "reproduction"],
+            "growth": ["puppy", "kitten", "growth", "weaning", "development"],
+            "weight": ["weight", "obesity", "overweight", "underweight", "bcs"],
+            "senior": ["senior", "geriatric", "aging", "elderly", "old"],
+        }
+        
+        for topic, keywords in topics.items():
+            if any(kw in content_lower for kw in keywords):
+                return topic
+        
+        return "general"
+    
+    def process_all_pdfs(self, pdf_dir: Path) -> List[Document]:
+        
+        pdf_files = sorted(pdf_dir.glob("*.pdf"))
+        
+        if not pdf_files:
+            raise ValueError(f"No PDF files found in {pdf_dir}")
+        
+        logger.info(f"Found {len(pdf_files)} PDF files to process")
+        
+        all_documents = []
+        failed_files = []
+        
+        for pdf_path in pdf_files:
+            try:
+                docs = self.process_pdf(pdf_path)
+                all_documents.extend(docs)
+            except Exception as e:
+                logger.error(f"Failed to process {pdf_path.name}: {e}")
+                failed_files.append(pdf_path.name)
+                continue
+        
+        if failed_files:
+            logger.warning(f"Failed to process {len(failed_files)} files: {failed_files}")
+        
+        logger.info(
+            f"Successfully processed {len(pdf_files) - len(failed_files)}/{len(pdf_files)} PDFs, "
+            f"total {len(all_documents)} chunks"
+        )
+        
+        return all_documents

kb/usda_client.py

@@ -1,71 +1,157 @@
 """
-USDA API client for food data retrieval.
+USDA FoodData Central API client.
 """
 import logging
-import time
-import json
-from typing import Dict, List, Optional
-from pathlib import Path
 import requests
+from typing import Optional, List, Dict, Any
+from functools import lru_cache
 
 from config import settings
-from schema import USDAFoodItem, USDAFoodNutrients, USDAFoodData
+from schema import USDAFoodData, USDAFoodItem, USDANutrient
 
 logger = logging.getLogger(__name__)
 
-class USDAClient:
-
-    @staticmethod
-    def create_client() -> "USDAClient":
-        return USDAClient()
 
+class USDAClient:
+    
     def __init__(self):
+        """Initialize USDA client with API credentials."""
         self.api_key = settings.USDA_API_KEY
-        self.base_url = "https://api.nal.usda.gov/fdc/v1"
-        self.cache_dir = settings.CACHE_DIR / "usda"
-        self.cache_dir.mkdir(parents=True, exist_ok=True)
-
-        if not self.api_key:
-            raise ValueError("USDA_API_KEY missing")
-
+        self.base_url = settings.USDA_BASE_URL
+        self.timeout = settings.USDA_TIMEOUT
         self.session = requests.Session()
-        self.timeout = 20
-
-    def search_foods(self, query: str, limit: int = 10) -> Dict:
-        url = f"{self.base_url}/foods/search"
-        params = {
-            "api_key": self.api_key,
-            "query": query,
-            "pageSize": limit,
-        }
-        r = self.session.get(url, params=params, timeout=self.timeout)
-        r.raise_for_status()
-        return r.json()
-
+        
+        # In-memory cache for food details
+        self._cache: Dict[int, USDAFoodData] = {}
+        
+        logger.debug(f"USDAClient initialized: base_url={self.base_url}")
+    
+    @staticmethod
+    def create() -> "USDAClient":
+        """Factory method to create client."""
+        return USDAClient()
+    
+    def search_foods(
+        self, 
+        query: str, 
+        limit: int = 10,
+        data_type: Optional[List[str]] = None
+    ) -> List[Dict[str, Any]]:
+        
+        try:
+            url = f"{self.base_url}/foods/search"
+            params = {
+                "api_key": self.api_key,
+                "query": query,
+                "pageSize": limit,
+            }
+            
+            if data_type:
+                params["dataType"] = ",".join(data_type)
+            
+            logger.debug(f"Searching USDA for: {query}")
+            response = self.session.get(url, params=params, timeout=self.timeout)
+            response.raise_for_status()
+            
+            data = response.json()
+            foods = data.get("foods", [])
+            
+            logger.info(f"Found {len(foods)} results for '{query}'")
+            return foods
+        
+        except requests.exceptions.RequestException as e:
+            logger.error(f"USDA search failed for '{query}': {e}")
+            return []
+    
     def get_food_details(self, fdc_id: int) -> Optional[USDAFoodData]:
-        url = f"{self.base_url}/food/{fdc_id}"
-        params = {"api_key": self.api_key}
-        r = self.session.get(url, params=params, timeout=self.timeout)
-        r.raise_for_status()
-        return self._parse_food_data(r.json())
-
-    def _parse_food_data(self, data: Dict) -> USDAFoodData:
-        food_item = USDAFoodItem(
-            fdc_id=data["fdcId"],
-            description=data["description"],
-            brand_owner=data.get("brandOwner"),
-            ingredients=data.get("ingredients"),
-        )
-
-        nutrients = []
-        for n in data.get("foodNutrients", []):
-            nutrients.append(
-                USDAFoodNutrients(
-                    nutrient_id=n["nutrient"]["id"],
-                    nutrient_name=n["nutrient"]["name"],
-                    unit_name=n["nutrient"]["unitName"],
-                    value=n.get("amount", 0.0),
-                )
+        
+        if fdc_id in self._cache:
+            logger.debug(f"Using cached data for FDC ID {fdc_id}")
+            return self._cache[fdc_id]
+        
+        try:
+            url = f"{self.base_url}/food/{fdc_id}"
+            params = {"api_key": self.api_key}
+            
+            logger.debug(f"Fetching USDA food details: FDC ID {fdc_id}")
+            response = self.session.get(url, params=params, timeout=self.timeout)
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            food_item = USDAFoodItem(
+                fdc_id=data["fdcId"],
+                description=data.get("description", "Unknown"),
+                brand_owner=data.get("brandOwner"),
+                ingredients=data.get("ingredients"),
             )
-
-        return USDAFoodData(food_item=food_item, nutrients=nutrients)
+            
+            # Extract nutrients
+            nutrients = []
+            for nutrient_data in data.get("foodNutrients", []):
+                if "nutrient" in nutrient_data:
+                    nutrients.append(USDANutrient(
+                        nutrient_id=nutrient_data["nutrient"]["id"],
+                        nutrient_name=nutrient_data["nutrient"]["name"],
+                        unit_name=nutrient_data["nutrient"]["unitName"],
+                        value=nutrient_data.get("amount", 0.0),
+                    ))
+            
+            food_data = USDAFoodData(
+                food_item=food_item,
+                nutrients=nutrients,
+            )
+            
+            # Cache result
+            self._cache[fdc_id] = food_data
+            logger.info(f"Retrieved {len(nutrients)} nutrients for FDC ID {fdc_id}")
+            
+            return food_data
+        
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Failed to get food details for FDC ID {fdc_id}: {e}")
+            return None
+    
+    def get_nutrition_for_ingredient(
+        self, 
+        ingredient: str,
+        quantity_grams: Optional[float] = 100.0
+    ) -> Optional[Dict[str, Any]]:
+        
+        search_results = self.search_foods(ingredient, limit=1)
+        
+        if not search_results:
+            logger.warning(f"No USDA results for '{ingredient}'")
+            return None
+        
+        top_result = search_results[0]
+        fdc_id = top_result["fdcId"]
+        description = top_result["description"]
+        
+        food_data = self.get_food_details(fdc_id)
+        
+        if not food_data:
+            return None
+        
+        scale_factor = quantity_grams / 100.0
+        
+        nutrients_map = {n.nutrient_name: n.value for n in food_data.nutrients}
+        
+        calories = nutrients_map.get("Energy", 0.0) * scale_factor
+        protein = nutrients_map.get("Protein", 0.0) * scale_factor
+        fat = nutrients_map.get("Total lipid (fat)", 0.0) * scale_factor
+        carbs = nutrients_map.get("Carbohydrate, by difference", 0.0) * scale_factor
+        
+        return {
+            "calories": round(calories, 2),
+            "protein_g": round(protein, 2),
+            "fat_g": round(fat, 2),
+            "carbs_g": round(carbs, 2),
+            "source": "USDA",
+            "fdc_id": fdc_id,
+            "description": description,
+        }
+    
+    def clear_cache(self):
+        self._cache.clear()
+        logger.info("USDA cache cleared")

kb/vector_db/vector_index.faiss

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:e2a6749cb5685d0395126c5f911004959556f9bedf90def552fe2bd2fb99b3dd
-size 2333466
+oid sha256:0448a5bff20379241e506aac936fc075e0c6ac8768aaf5562e4203c7a6e652bb
+size 5614102

llm/chains.py

@@ -0,0 +1,65 @@
+"""
+LangChain multi-chain architecture for meal planning.
+"""
+import logging
+from typing import Dict, Any, List
+
+from langchain_core.prompts import PromptTemplate
+from langchain_core.runnables import RunnableParallel, RunnableLambda
+
+logger = logging.getLogger(__name__)
+
+
+class MealPlanningChains:
+    
+    def __init__(self, llm):
+    
+        self.llm = llm
+        logger.debug("MealPlanningChains initialized")
+    
+    @staticmethod
+    def create(llm) -> "MealPlanningChains":
+        """Factory method to create chains."""
+        return MealPlanningChains(llm)
+
+    def create_unified_chain(self, prompt_template: PromptTemplate):
+    
+        return prompt_template | self.llm
+    
+    def create_scheduling_chain(self):
+        
+        logger.warning("Scheduling chain not yet implemented, using unified chain")
+        return None
+
+    
+    def create_meal_options_chain(self):
+        
+        logger.warning("Meal options chain not yet implemented, using unified chain")
+        return None
+    
+    def create_validation_chain(self):
+        
+        logger.warning("Validation chain not yet implemented, requires Phase 5 & 6")
+        return None
+    
+    def create_parallel_options_chain(self, meal_slots: List[str]):
+        
+        logger.warning("Parallel chain not yet implemented")
+        return None
+=
+
+def split_meal_plan_sections(plan_text: str) -> Dict[str, str]:
+    
+    logger.debug("Using postprocessor for section splitting (Phase 6 will replace)")
+    return {}
+
+
+def calculate_meal_nutrition(ingredients: List[str], quantities: List[float]) -> Dict[str, float]:
+    
+    logger.warning("USDA lookup not yet implemented, returning placeholder")
+    return {
+        "calories": 0.0,
+        "protein_g": 0.0,
+        "fat_g": 0.0,
+        "carbs_g": 0.0
+    }

llm/output_parsers.py

@@ -0,0 +1,83 @@
+"""
+Pydantic output parsers for structured LLM responses.
+
+"""
+import logging
+from typing import Optional
+
+from langchain_core.output_parsers import PydanticOutputParser
+from langchain_core.exceptions import OutputParserException
+
+from schema import NutritionPlanOutput
+
+logger = logging.getLogger(__name__)
+
+
+class NutritionPlanParser:
+    
+    def __init__(self):
+        """Initialize parser with NutritionPlanOutput schema."""
+        self.parser = PydanticOutputParser(pydantic_object=NutritionPlanOutput)
+        logger.debug("NutritionPlanParser initialized")
+    
+    @staticmethod
+    def create() -> "NutritionPlanParser":
+        """Factory method to create parser."""
+        return NutritionPlanParser()
+    
+    def get_format_instructions(self) -> str:
+        
+        return self.parser.get_format_instructions()
+    
+    def parse(self, llm_output: str) -> Optional[NutritionPlanOutput]:
+       
+        try:
+            logger.debug("Parsing LLM output with Pydantic...")
+            parsed = self.parser.parse(llm_output)
+            logger.info("Successfully parsed nutrition plan")
+            return parsed
+        
+        except OutputParserException as e:
+            logger.error(f"Failed to parse LLM output: {e}")
+            # Log the problematic output for debugging
+            logger.debug(f"Problematic output: {llm_output[:500]}...")
+            raise
+        
+        except Exception as e:
+            logger.error(f" Unexpected parsing error: {e}")
+            raise
+    
+    def parse_with_retry(
+        self, 
+        llm_output: str, 
+        llm_client=None,
+        max_retries: int = 2
+    ) -> Optional[NutritionPlanOutput]:
+       
+        try:
+            # Try initial parse
+            return self.parse(llm_output)
+        
+        except OutputParserException as e:
+            if llm_client and max_retries > 0:
+                logger.warning(f"Parse failed, attempting retry with LLM fix...")
+                
+                pass
+            
+            logger.error("Parse failed and no retry available")
+            return None
+
+class SimpleNutritionParser:
+
+    @staticmethod
+    def extract_text_plan(llm_output: str) -> dict:
+        
+        logger.warning("Using fallback text extraction (structured parse failed)")
+        
+        lines = [line.strip() for line in llm_output.splitlines() if line.strip()]
+        
+        return {
+            "text_lines": lines,
+            "source": "fallback_extraction",
+            "warning": "Structured parsing failed, using text fallback"
+        }

llm/prompt_templates.py

@@ -12,7 +12,7 @@ class PromptBuilder:
 
         INSTRUCTIONS:
 
-        1. Generate a meal plan with proper meals per day, distributed in percentage (for example, for 2 meals -> 50%-50%, for 3 meals ->33%-33%-33%, depending on the user input.)
+        1. Generate a meal plan with proper meals per day. Determine the number of meals (typically 2-3 for adults, 3-4 for puppies/kittens) based on the pet's life stage, activity level, and veterinary context. Distribute calories appropriately (e.g., for 2 meals: 50%-50%, for 3 meals: 33%-33%-34%).
 
         2. For EACH meal slot, generate AT LEAST TWO distinct HOME-COOKED OPTIONS.
         - Clearly label them as Option A and Option B.
@@ -23,71 +23,55 @@ class PromptBuilder:
 
         3. Include proper feeding instructions and safety notes, specific to the inputs.
 
-        4. Ensure the plan is safe and based on veterinary guidelines.
+        4. Ensure the plan is safe and based on veterinary guidelines from the context.
 
         5. Output in plain text format (human readable language) as specified.
 
         6. DO NOT repeat or echo any raw user input values in the output - treat them as internal context only.
 
-        7. Focus output on computed nutrition targets and the meal plan only.
+        7. Focus output on the meal plan only - nutrition targets are already provided separately.
 
-        8. STRICTLY follow this exact output structure - no deviations:
+        8.  CRITICAL: DO NOT include any nutrition target values (Daily Calorie Target, Protein, Fat, Carbohydrates, Water) in the output. These are handled separately.
 
-            PET NUTRITION PLAN 
+        9. STRICTLY follow this exact output structure - no deviations:
 
-            DAILY NUTRITION TARGETS
-
-            Energy Requirements
-            RER: ___ kcal/day
-            MER: ___ kcal/day
-            Daily Calorie Target: ___ kcal/day
-
-            Macronutrients (Approx.)
-            Protein: ___ g/day
-            Fat: ___ g/day
-            Carbohydrates: ___ g/day
+            Pet Nutrition Plan
 
-            Water Intake: ___ ml/day
+            Recommended Meal Plan with Feeding Schedule
+            Number of Meals: [Determine from context: 2-4 meals based on life stage]
+            Meal Distribution: [Calculate % based on number of meals]
 
-            RECOMMENDED MEAL PLAN WITH FEEDING SCHEDULE
-            Number of Meals: _______
-            Meal Distribution: ________
-
-            8:00 AM — Morning Meal
+            [Time] — [Meal Name] (Approx. ___ kcal)
 
             Option A
             Type: ________
             Calories: __________
-            Ingredients: [list actual ingredients, no examples]
-            Preparation: [list actual preparation steps]
+            Ingredients: [list actual ingredients with quantities]
+            Preparation: [numbered steps]
 
             Option B
             Type: ________
             Calories: __________
-            Ingredients: [list actual ingredients, no examples]
-            Preparation: [list actual preparation steps]
+            Ingredients: [list actual ingredients with quantities]
+            Preparation: [numbered steps]
 
             [Repeat for each meal slot]
 
-            FEEDING INSTRUCTIONS
-            [numbered pointers with actual instructions, max 5]
+            Feeding Instructions
+            [numbered pointers with actual instructions, max 7]
 
-            FOOD CATEGORIES  [return 3 numbered pointers, MAX 5 food items for each of the three categories.]
-            Dangerous: [list]
-            Avoid: [list]
-            Safe: [list]
+            Food Categories
+            {food_categories}
 
-            SAFETY NOTES
+            Safety Notes
             [numbered pointers, MAX 5]
 
-            DISCLAIMER
+            Disclaimer
             This nutrition plan is AI-generated guidance and not a medical prescription. Consult a veterinarian for medical conditions or major diet changes.
 
-        9. FORBID any generic/example language: NO "Example calculation", "hypothetical", "illustrative", "vague guidance", "non actionable text".
-
-        10. Use real, specific, actionable content only. Adapt dynamically based on retrieved knowledge and reasoning.
+        10. FORBID any generic/example language: NO "Example calculation", "hypothetical", "illustrative", "vague guidance", "non actionable text".
 
-        11. No hardcoded food logic - LLM reasoning handle the data context naturally.
+        11. Use real, specific, actionable content only. Adapt dynamically based on retrieved knowledge and reasoning.
 
         12. Ensure both Option A and Option B strictly avoid all allergies and diseases mentioned in the internal context.
 
@@ -100,18 +84,93 @@ class PromptBuilder:
         """
 
         self.generation_template = PromptTemplate(
-            input_variables=["pet_profile", "nutrition_targets", "retrieved_context", "instructions"],
+            input_variables=["pet_profile", "daily_calorie_target", "daily_protein_g", "daily_fat_g", "daily_carbohydrates_g", "daily_water_ml", "retrieved_context"],
             template=
 
             """ You are an expert veterinary nutritionist. Generate a safe, explainable pet nutrition diet plan based on the following information.
 
             INTERNAL CONTEXT (DO NOT REPEAT IN OUTPUT): {pet_profile}
 
-            NUTRITION TARGETS: {nutrition_targets}
+            COMPUTED NUTRITION TARGETS (Use these exact values):
+            - Daily Calorie Target: {daily_calorie_target} kcal/day
+            - Protein: {daily_protein_g} g/day
+            - Fat: {daily_fat_g} g/day
+            - Carbohydrates: {daily_carbohydrates_g} g/day
+            - Water: {daily_water_ml} ml/day
+
+            RETRIEVED VETERINARY KNOWLEDGE: {retrieved_context}
+
+            INSTRUCTIONS:
+
+            1. Generate a meal plan with proper meals per day. Determine the number of meals (typically 2-3 for adults, 3-4 for puppies/kittens) based on the pet's life stage, activity level, and veterinary context. Distribute calories appropriately (e.g., for 2 meals: 50%-50%, for 3 meals: 33%-33%-34%).
+
+            2. For EACH meal slot, generate AT LEAST TWO distinct HOME-COOKED OPTIONS.
+            - Clearly label them as Option A and Option B.
+            - Each option must include its own Type, Calories, Ingredients, and Preparation.
+            - Both options must independently satisfy the nutrition intent of that meal.
+            - DO NOT include any commercial food, packaged food, or brand names anywhere.
+            - Pet owner must be able to choose either option freely.
+
+            3. Include proper feeding instructions and safety notes, specific to the pet's profile.
+
+            4. Ensure the plan is safe and based on veterinary guidelines from the context.
+
+            5. Output in plain text format (human readable language) as specified.
+
+            6. DO NOT repeat or echo any raw user input values in the output - treat them as internal context only.
+
+            7. CRITICAL: DO NOT include RER (Resting Energy Requirement) or MER (Maintenance Energy Requirement) in the output. These are internal calculations only. Only show the Daily Calorie Target provided above.
+
+            8. STRICTLY follow this exact output structure:
+
+            PET NUTRITION PLAN
+
+            DAILY NUTRITION TARGETS
+
+            Daily Calorie Target: {daily_calorie_target} kcal/day
 
-            RETRIEVED KNOWLEDGE: {retrieved_context}
+            Macronutrients
+            Protein: {daily_protein_g} g/day
+Fat: {daily_fat_g} g/day
+            Carbohydrates: {daily_carbohydrates_g} g/day
+
+            Water Intake: {daily_water_ml} ml/day
+
+            RECOMMENDED MEAL PLAN WITH FEEDING SCHEDULE
+            Number of Meals: [Determine from context: 2-4 meals based on life stage]
+            Meal Distribution: [Calculate % based on number of meals]
+
+            [Time] — [Meal Name] (Approx. ___ kcal)
+
+            Option A
+            Type: ________
+            Calories: __________
+            Ingredients: [list actual ingredients with quantities]
+            Preparation: [numbered steps]
+
+            Option B
+            Type: ________
+            Calories: __________
+            Ingredients: [list actual ingredients with quantities]
+            Preparation: [numbered steps]
+
+            [Repeat for each meal slot]
+
+            FEEDING INSTRUCTIONS
+            [numbered pointers with actual instructions, max 7]
+
+            FOOD CATEGORIES
+            Dangerous: [list MAX 10 toxic foods specific to this pet type]
+            Avoid: [list MAX 10 foods to avoid based on pet's allergies/conditions]
+            Safe: [list MAX 10 safe foods appropriate for this pet]
+
+            SAFETY NOTES
+            [numbered pointers, MAX 5]
+
+            DISCLAIMER
+            This nutrition plan is AI-generated guidance and not a medical prescription. Consult a veterinarian for medical conditions or major diet changes.
 
-            {instructions}
+            Generate the nutrition plan now.
             """
         )
 
@@ -133,11 +192,7 @@ class PromptBuilder:
         if pet_profile.diseases:
             query_parts.append(f"Diseases: {pet_profile.diseases}")
 
-        query_parts.extend([
-            f"RER: {nutrition_targets.get('rer', 'unknown')} kcal/day",
-            f"MER: {nutrition_targets.get('mer', 'unknown')} kcal/day",
-            "Nutrient requirements for dogs and cats"
-        ])
+        query_parts.append("Nutrient requirements for dogs and cats")
 
         query = " ".join(query_parts)
         logger.info(f"Built retrieval query: {query}")

load_kb.py

@@ -1,74 +1,124 @@
 """
-Knowledge base loading and processing.
+Knowledge base loading with LangChain document processing.
+
+This file orchestrates:
+1. PDF loading and chunking (via DocumentProcessor)
+2. Embedding generation (via EmbeddingLayer)
+3. Vector store persistence (via VectorStore)
+
+Key improvements over old version:
+- Uses LangChain document processing
+- Processes ALL PDF content 
+- Incremental loading support
 """
 import logging
 from pathlib import Path
-from typing import Dict, List, Tuple
-import numpy as np
+from typing import Dict, List
 import time
 
 from config import settings
-from kb.pdf_ingestor import create_pdf_ingestor
-from chunker import SemanticChunker, DocumentChunk
+from kb.document_processor import DocumentProcessor
 from rag.embed import EmbeddingLayer
 from rag.vectorstore import VectorStore
 
 logger = logging.getLogger(__name__)
 
-class KnowledgeBaseLoader:
-
-    @staticmethod
-    def create_loader() -> "KnowledgeBaseLoader":
-        return KnowledgeBaseLoader()
 
+class KnowledgeBaseLoader:
+    
     def __init__(self):
+        """Initialize KB loader with required components."""
         self.pdf_dir = settings.RAW_DATA_DIR / "pdf"
-
-        self.ingestor = create_pdf_ingestor(settings)
-        self.chunker = SemanticChunker.create_chunker()
+        self.processor = DocumentProcessor.create_processor()
         self.embedder = EmbeddingLayer.create_embedder()
         self.vector_store = VectorStore.create_vectorstore()
-
+        
+        logger.debug(f"KnowledgeBaseLoader initialized with pdf_dir={self.pdf_dir}")
+    
+    @staticmethod
+    def create_loader() -> "KnowledgeBaseLoader":
+        """Factory method to create loader instance."""
+        return KnowledgeBaseLoader()
+    
     def load_knowledge_base(self, force_rebuild: bool = False) -> Dict:
+       
         start = time.time()
-
+       
         if not force_rebuild and self.vector_store.load():
-            logger.info("Knowledge base loaded successfully from existing index")
+            logger.info(" Knowledge base loaded from existing vector store")
             return {
                 "status": "loaded",
                 "chunks": len(self.vector_store.records),
                 "time_sec": round(time.time() - start, 2),
             }
-
-        logger.info("Rebuilding knowledge base from data")
-
-        logger.info(f"Looking for data in {self.pdf_dir}")
-        pdf_files = list(self.pdf_dir.glob("*.pdf"))
-        logger.info(f"Found {len(pdf_files)} PDF files: {[str(p) for p in pdf_files]}")
+        
+        # Rebuild from scratch
+        logger.info("Rebuilding knowledge base from PDFs...")
+        
+        # Find all PDFs
+        pdf_files = sorted(self.pdf_dir.glob("*.pdf"))
         if not pdf_files:
-            raise ValueError(f"No data found in {self.pdf_dir}")
-
-        all_chunks: List[DocumentChunk] = []
-
+            raise ValueError(f"No PDF files found in {self.pdf_dir}")
+        
+        logger.info(f"Found {len(pdf_files)} PDF files to process:")
         for pdf in pdf_files:
-            docs = self.ingestor.ingest_pdf(pdf)
-            content = "\n\n".join([d.text for d in docs])
-            chunks, _ = self.chunker.chunk_document(content, pdf.name)
-            all_chunks.extend(chunks)
-
-        texts = [c.content for c in all_chunks]
+            logger.info(f"  - {pdf.name}")
+        
+        # Process all PDFs with DocumentProcessor
+        try:
+            all_documents = self.processor.process_all_pdfs(self.pdf_dir)
+        except Exception as e:
+            logger.error(f"Failed to process PDFs: {e}")
+            raise
+        
+        if not all_documents:
+            raise ValueError("No documents extracted from PDFs")
+        
+        logger.info(f"Total documents created: {len(all_documents)}")
+        
+        self._log_metadata_stats(all_documents)
+        
+        texts = [doc.page_content for doc in all_documents]
+        metadatas = [doc.metadata for doc in all_documents]
+        
+        logger.info("Generating embeddings...")
         embeddings = self.embedder.embed_texts(texts)
-
-        metadatas = [c.metadata.model_dump() for c in all_chunks]
+        logger.info(f"Generated {len(embeddings)} embeddings")
+        
+        # Store in vector database
+        logger.info("Storing in vector database...")
         self.vector_store.add(embeddings, texts, metadatas)
         self.vector_store.persist()
-
-        logger.info(f"Knowledge base rebuilt: {len(all_chunks)} chunks")
-
+        logger.info(f"Vector store persisted to {settings.VECTOR_DB_DIR}")
+        
+        elapsed = round(time.time() - start, 2)
+        logger.info(
+            f"Knowledge base rebuilt successfully: "
+            f"{len(all_documents)} chunks from {len(pdf_files)} PDFs in {elapsed}s"
+        )
+        
         return {
             "status": "rebuilt",
             "pdfs": len(pdf_files),
-            "chunks": len(all_chunks),
-            "vectors": len(all_chunks),
-            "time_sec": round(time.time() - start, 2),
+            "chunks": len(all_documents),
+            "time_sec": elapsed,
         }
+    
+    def _log_metadata_stats(self, documents: List):
+        """
+        Log statistics about document metadata.
+        
+        Useful for verifying metadata extraction quality.
+        """
+        from collections import Counter
+        
+        species_counts = Counter(doc.metadata.get("species", "unknown") for doc in documents)
+        logger.info(f"Species distribution: {dict(species_counts)}")
+        
+        topic_counts = Counter(doc.metadata.get("topic", "unknown") for doc in documents)
+        logger.info(f"Topic distribution: {dict(topic_counts)}")
+        
+        source_counts = Counter(doc.metadata.get("source_file", "unknown") for doc in documents)
+        logger.info(f"Chunks per file:")
+        for source, count in sorted(source_counts.items()):
+            logger.info(f"  - {source}: {count} chunks")

main.py

@@ -1,182 +0,0 @@
-import logging
-import json
-
-from config import settings
-from input_handler import InputHandler
-from load_kb import KnowledgeBaseLoader
-from nutrition_engine import NutritionEngine
-from postprocess import PostProcessor
-from rules_engine import RulesEngine
-from rag.retriever import KnowledgeRetriever
-from llm.gemini_client import GeminiClient, LLMResponse
-from llm.prompt_templates import PromptBuilder
-
-logger = logging.getLogger(__name__)
-
-def setup_logging():
-    logging.getLogger("sentence_transformers").setLevel(logging.WARNING)
-    logging.getLogger("tqdm").setLevel(logging.WARNING)
-    logging.getLogger("httpx").setLevel(logging.WARNING)
-
-    logger = logging.getLogger()
-    logger.setLevel(logging.INFO) 
-
-    for handler in logger.handlers[:]:
-        logger.removeHandler(handler)
-
-    file_handler = logging.FileHandler("nutrition_planner.log")
-    file_handler.setLevel(logging.INFO)
-    file_handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
-
-    console_handler = logging.StreamHandler()
-    console_handler.setLevel(logging.WARNING)
-    console_handler.setFormatter(logging.Formatter("%(levelname)s - %(message)s"))
-
-    logger.addHandler(file_handler)
-    logger.addHandler(console_handler)
-
-
-def collect_user_input() -> dict:
-    print("\n" + "=" * 60)
-    print("PET NUTRITION DIET PLANNER")
-    print("=" * 60)
-    print("Hello! I'm here to help create a personalized nutrition plan for your pet.")
-    print("Please answer the following questions about your furry friend.\n")
-
-    pet_type = input("What type of pet do you have? (dog/cat): ").strip()
-    breed = input("What is your pet's breed? ").strip()
-    gender = input("Is your pet male or female? (male/female): ").strip()
-
-    pregnant_lactating = None
-    if gender.lower() == "female":
-        pregnant_lactating = input("Is your pet pregnant or lactating? (choose one: none/pregnant/lactating): ").strip() or None
-
-    weight_kg = float(input("How much does your pet weigh in kilograms? ").strip())
-    activity_level = input("How would you describe your pet's activity level? (low/moderate/high): ").strip()
-    life_stage = input("What is your pet's life stage? (puppy/adult/senior for dogs, kitten/adult/senior for cats): ").strip()
-    bcs = int(input("On a scale of 1-9, what is your pet's body condition score?: ").strip())
-    neutered_spayed = input("Has your pet been neutered or spayed? (yes/no): ").strip()
-
-    allergies = input("Does your pet have any allergies? (leave blank if none): ").strip() or None
-    diseases = input("Does your pet have any medical conditions or diseases? (leave blank if none): ").strip() or None
-    diet_preference = input("What type of diet does your pet prefer? (vegetarian/non-vegetarian/mixed): ").strip()
-    current_food_format = input("What format is your pet's current food? (home-cooked/dry/wet/mixed): ").strip()
-
-    return {
-        "pet_type": pet_type,
-        "breed": breed,
-        "gender": gender,
-        "weight_kg": weight_kg,
-        "activity_level": activity_level,
-        "life_stage": life_stage,
-        "bcs": bcs,
-        "neutered_spayed": neutered_spayed,
-        "pregnant_lactating": pregnant_lactating,
-        "allergies": allergies,
-        "diseases": diseases,
-        "diet_preference": diet_preference,
-        "current_food_format": current_food_format,
-    }
-
-
-def main():
-    setup_logging()
-    logger.info("Starting Pet Nutrition Planner")
-
-    # Step 1 — Collect and validate input
-    raw_input = collect_user_input()
-    input_handler = InputHandler.create_handler()
-    pet_profile = input_handler.validate_and_parse(raw_input)
-    if pet_profile is None:
-        print("Invalid input. Please restart.")
-        return
-
-    nutrition_engine = NutritionEngine.create_engine()
-    rules_engine = RulesEngine.create_engine()
-
-    # Load knowledge base after input collection
-    kb_loader = KnowledgeBaseLoader.create_loader()
-    try:
-        kb_result = kb_loader.load_knowledge_base(force_rebuild=False)
-    except Exception as e:
-        logger.warning(f"Failed to load knowledge base: {e}")
-        logger.info("Attempting to rebuild knowledge base...")
-        try:
-            kb_result = kb_loader.load_knowledge_base(force_rebuild=True)
-        except Exception as e2:
-            logger.error(f"Failed to rebuild knowledge base: {e2}")
-            print("Error: Knowledge base not available. Please ensure PDF files are in raw_data/pdf directory.")
-            return
-
-    retriever = KnowledgeRetriever.create()
-    llm_client = GeminiClient.create()
-    prompt_builder = PromptBuilder()
-
-    # Step 2 — calculate nutrition targets
-    nutrition_targets = nutrition_engine.calculate_nutrition_targets(pet_profile)
-    rules_adjustments = rules_engine.apply_rules(pet_profile, nutrition_targets)
-    safety_warnings = rules_engine.validate_plan_safety(pet_profile, nutrition_targets)
-
-    if safety_warnings:
-        print("\nSAFETY WARNINGS:")
-        for warning in safety_warnings:
-            print(f"- {warning}")
-        print("Please consult a veterinarian for these concerns.\n")
-
-    # Step 3 — Retrieve knowledge 
-    query = prompt_builder.build_retrieval_query(pet_profile, nutrition_targets)
-    retrieved_chunks = retriever.retrieve(query, top_k=settings.RETRIEVAL_TOP_K)
-
-    logger.info(
-        f"Retrieved {len(retrieved_chunks)} chunks for generation"
-    )
-    
-    # Step 4 - chaining
-    chain = prompt_builder.generation_template | llm_client.llm
-
-    inputs = {
-        "pet_profile": f"- Pet: {pet_profile.pet_type}, {pet_profile.breed}, {pet_profile.gender}, {pet_profile.life_stage}, {pet_profile.weight_kg}kg, activity: {pet_profile.activity_level}, BCS: {pet_profile.bcs}, neutered/spayed: {pet_profile.neutered_spayed}, allergies: {pet_profile.allergies or 'none'}, diseases: {pet_profile.diseases or 'none'}, diet preference: {pet_profile.diet_preference}, current food format: {pet_profile.current_food_format}",
-        "nutrition_targets": f"- RER: {nutrition_targets.get('rer', 'unknown')} kcal/day\n- MER: {nutrition_targets.get('mer', 'unknown')} kcal/day\n- Daily Calorie Target: {nutrition_targets.get('mer', 'unknown')} kcal/day",
-        "retrieved_context": "\n\n".join([chunk["content"] for chunk in retrieved_chunks]), "instructions": prompt_builder.instructions
-    }
-    # Step 5 - response generation
-    response = chain.invoke(inputs)
-    text = response.content.strip()
-
-    response = LLMResponse(success=True, json_text=text, error_message="")
-
-    if not response.success:
-        logger.error("Generation failed")
-        print("\nSystem failed to generate a valid plan safely.")
-        print(response.error_message)
-        return
-
-    # Step 6 — Post-process and display result
-    post_processor = PostProcessor.create_processor()
-    final_plan = post_processor.validate_and_clean(response.json_text)
-
-    extracted_values = post_processor.extract_nutrition_values(final_plan)
-    nutrition_targets.update(extracted_values)
-    
-    final_plan = final_plan.replace("–", "-").replace("—", "-").replace("→", "->")
-
-    print(final_plan)
-
-    # Option to save as JSON
-    save_option = input("\nDo you want to save this plan? (yes/no): ").strip().lower()
-    if save_option == "yes":
-        plan_data = {
-        "pet_profile": pet_profile.model_dump(),
-        "nutrition_targets": nutrition_targets,
-        "plan": {
-            "text_lines": [line.strip() for line in final_plan.splitlines() if line.strip()],
-            "sections": post_processor.parse_plan_sections(final_plan)
-        }
-    }
-
-    with open("nutrition_plan.json", "w", encoding="utf-8") as f:
-        json.dump(plan_data, f, indent=2, ensure_ascii=False)
-        print("Plan saved as nutrition_plan.json")
-
-if __name__ == "__main__":
-    main()

nutrition_engine.py

@@ -1,55 +1,361 @@
 """
-Deterministic nutrition calculation engine.
+Deterministic nutrition calculation engine based on authoritative sources.
+
+All calculations use NRC/AAFCO/WSAVA guidelines with full source attribution.
+
+Key Principles:
+1. RER/MER are calculated but kept internal (in audit trail, not user response)
+2. Macronutrients calculated deterministically 
+3. All calculations cite authoritative sources
+4. Weight validation to catch implausible inputs
+
+Sources:
+- NRC 2006: Nutrient Requirements of Dogs and Cats
+- AAFCO 2024: Dog and Cat Food Nutrient Profiles
+- WSAVA: Global Nutrition Guidelines
+- FEDIAF: European Pet Food Guidelines
 """
 import logging
-from typing import Dict, Any
-import math
+from typing import Dict, Any, Optional, Tuple
+from datetime import datetime
 
 from config import settings
-from schema import PetProfile, PetType, LifeStage, NeuteredSpayed, NutritionTargets
+from schema import (
+    PetProfile, 
+    PetType, 
+    LifeStage, 
+    NeuteredSpayed, 
+    PregnantLactating,
+    ActivityLevel,
+    NutritionSource,
+    CalculationAudit
+)
 
 logger = logging.getLogger(__name__)
 
-class NutritionEngine:
 
+class NutritionEngine:
+    
+    def __init__(self):
+        self.energy_densities = settings.ENERGY_DENSITIES
+        self.digestibility_factor = settings.DIGESTIBILITY_FACTOR
+        
+        # Source citations
+        self.nrc_source = NutritionSource(
+            source_type="NRC",
+            citation="National Research Council. 2006. Nutrient Requirements of Dogs and Cats. Washington, DC: The National Academies Press."
+        )
+        
+        self.aafco_source = NutritionSource(
+            source_type="AAFCO",
+            citation="AAFCO 2024 Official Publication - Dog and Cat Food Nutrient Profiles"
+        )
+    
     @staticmethod
     def create_engine() -> "NutritionEngine":
-        return NutritionEngine()
 
+        return NutritionEngine()
+    
     def calculate_nutrition_targets(self, profile: PetProfile) -> Dict[str, Any]:
-        rer = 70 * (profile.weight_kg ** 0.75)
-
-        pet_type_key = profile.pet_type.value.lower()
-        multipliers = settings.MER_MULTIPLIERS.get(pet_type_key, {})
-
-        if profile.pet_type == PetType.DOG:
-            if profile.life_stage == LifeStage.PUPPY:
-                multiplier_key = "puppy_under_4m"
-            elif profile.neutered_spayed == NeuteredSpayed.YES:
-                multiplier_key = "adult_neutered"
-            else:
-                multiplier_key = "adult_intact"
-        else:
-            if profile.life_stage == LifeStage.KITTEN:
-                multiplier_key = "kitten"
-            elif profile.neutered_spayed == NeuteredSpayed.YES:
-                multiplier_key = "adult_neutered"
-            else:
-                multiplier_key = "adult_intact"
-
-        multiplier = multipliers.get(multiplier_key, 1.0)
+        """
+        Calculate complete nutrition targets with audit trail.
+        
+        Process:
+        1. Validate weight plausibility
+        2. Calculate RER (Resting Energy Requirement)
+        3. Select MER multiplier from authoritative table
+        4. Calculate MER (Maintenance Energy Requirement)
+        5. Calculate macronutrients (% → calories → grams)
+        6. Calculate water requirement
+        7. Create audit trail
+        
+        Args:
+            profile: Validated pet profile
+        
+        Returns:
+            {
+                "daily_calorie_target": float,
+                "protein_g": float,
+                "fat_g": float,
+                "carbohydrates_g": float,
+                "water_ml": float,
+                "_audit": CalculationAudit (internal only)
+            }
+        
+        Note: RER and MER are in _audit, NOT in user-facing response
+        """
+        self._validate_weight(profile) 
+        rer = self._calculate_rer(profile.weight_kg)
+        multiplier, multiplier_key = self._select_mer_multiplier(profile)
         mer = rer * multiplier
-        water_ml = profile.weight_kg * 25
-
-        targets = {
-            "rer": round(rer, 2),
-            "mer": round(mer, 2),
-            "daily_calorie_target": round(mer, 2),
-            "protein_g": 0,
-            "fat_g": 0,
-            "carbohydrates_g": 0,
+        daily_calorie_target = mer
+        macros = self._calculate_macronutrients(daily_calorie_target, profile)
+        water_ml = self._calculate_water(daily_calorie_target, profile)
+        audit = CalculationAudit(
+            rer=round(rer, 2),
+            mer=round(mer, 2),
+            mer_multiplier=multiplier,
+            mer_source=self.nrc_source,
+            protein_pct_source=self.aafco_source,
+            fat_pct_source=self.aafco_source,
+            timestamp=datetime.utcnow().isoformat()
+        )
+        
+        logger.info(
+            f"Nutrition calculated for {profile.pet_type.value} ({profile.weight_kg}kg): "
+            f"RER={rer:.2f} kcal/day, MER={mer:.2f} kcal/day (multiplier={multiplier}, key={multiplier_key})"
+        )
+        
+        logger.info(
+            f"Macros: protein={macros['protein_g']:.2f}g, fat={macros['fat_g']:.2f}g, "
+            f"carbs={macros['carbohydrates_g']:.2f}g, water={water_ml:.2f}ml"
+        )
+        
+        return {
+            "daily_calorie_target": round(daily_calorie_target, 2),
+            "protein_g": round(macros["protein_g"], 2),
+            "fat_g": round(macros["fat_g"], 2),
+            "carbohydrates_g": round(macros["carbohydrates_g"], 2),
             "water_ml": round(water_ml, 2),
+            "_audit": audit,  
         }
-
-        logger.info(f"Calculated nutrition targets: RER={targets['rer']}, MER={targets['mer']}")
-        return targets
+    
+    def _validate_weight(self, profile: PetProfile):
+        ranges = settings.WEIGHT_RANGES.get(profile.pet_type.value, {})
+        
+        if profile.pet_type == PetType.CAT:
+            min_w, max_w = ranges.get("all", (2.0, 12.0))
+            if not (min_w <= profile.weight_kg <= max_w):
+                raise ValueError(
+                    f"Implausible weight for cat: {profile.weight_kg}kg. "
+                    f"Typical domestic cats: {min_w}-{max_w}kg. "
+                    f"Please verify this is correct."
+                )
+        
+        elif profile.pet_type == PetType.DOG:
+            all_ranges = list(ranges.values())
+            if all_ranges:
+                min_w = min(r[0] for r in all_ranges)
+                max_w = max(r[1] for r in all_ranges)
+                if not (min_w <= profile.weight_kg <= max_w):
+                    raise ValueError(
+                        f"Implausible weight for dog: {profile.weight_kg}kg. "
+                        f"Typical dogs: {min_w}-{max_w}kg. "
+                        f"Please verify this is correct."
+                    )
+        
+        logger.debug(f"Weight validation passed: {profile.weight_kg}kg for {profile.pet_type.value}")
+    
+    def _calculate_rer(self, weight_kg: float) -> float:
+        """
+        Calculate Resting Energy Requirement using NRC formula.
+        
+        Formula: RER = 70 × (weight_kg ** 0.75)
+        
+        Source: NRC 2006 - Nutrient Requirements of Dogs and Cats
+        
+        Args:
+            weight_kg: Body weight in kilograms
+        
+        Returns:
+            RER in kcal/day
+        """
+        rer = 70 * (weight_kg ** 0.75)
+        logger.debug(f"RER calculated: {rer:.2f} kcal/day for {weight_kg}kg")
+        return rer
+    
+    def _select_mer_multiplier(self, profile: PetProfile) -> Tuple[float, str]:
+        """
+        Select MER multiplier based on life stage, neuter status, activity, BCS.
+         
+        Uses authoritative multiplier tables from MSD Vet Manual.
+        
+        Args:
+            profile: Pet profile
+        
+        Returns:
+            (multiplier, multiplier_key) - multiplier value and lookup key used
+        """
+        pet_type = profile.pet_type.value
+        multipliers = settings.ENERGY_MULTIPLIERS.get(pet_type, {})
+        
+        key = self._build_multiplier_key(profile)
+        
+        multiplier = multipliers.get(key, 1.6)  
+        
+        logger.debug(f"MER multiplier selected: {multiplier} (key: {key})")
+        
+        return multiplier, key
+    
+    def _build_multiplier_key(self, profile: PetProfile) -> str:
+        
+        if profile.pregnant_lactating == PregnantLactating.LACTATING:
+            return "lactating_peak"
+        if profile.pregnant_lactating == PregnantLactating.PREGNANT:
+            return "pregnant"
+        
+        if profile.life_stage == LifeStage.PUPPY:
+            return "puppy_over_4m"
+        if profile.life_stage == LifeStage.KITTEN:
+            return "kitten"
+        
+        if profile.life_stage == LifeStage.SENIOR:
+            
+            if profile.activity_level == ActivityLevel.LOW:
+                return "senior_sedentary"
+            else:
+                return "senior_active"
+        
+        if profile.neutered_spayed == NeuteredSpayed.YES:
+            if profile.bcs > 6:
+                return "adult_obesity_prone"
+            return "adult_neutered"
+        else:
+            if profile.bcs > 6:
+                return "adult_obesity_prone"
+            return "adult_intact"
+    
+    def _calculate_macronutrients(
+        self, 
+        daily_calorie_target: float, 
+        profile: PetProfile
+    ) -> Dict[str, Any]:
+        """
+        Calculate protein, fat, carbs in grams using % targets.
+        
+        Process (as specified in requirements):
+        1. Select % of calories targets from AAFCO/NRC tables
+        2. Convert to calories using daily_calorie_target
+        3. Convert to grams using energy densities (4/9/4 kcal/g)
+        4. Apply digestibility factor
+        5. Validate against minimums
+        
+        Args:
+            daily_calorie_target: Total daily calories (MER)
+            profile: Pet profile
+        
+        Returns:
+            {
+                "protein_g": float,
+                "fat_g": float,
+                "carbohydrates_g": float,
+            }
+        """
+        pet_type = profile.pet_type.value
+        
+        life_stage_key = self._get_macro_life_stage_key(profile)
+        
+        macro_table = settings.MACRONUTRIENT_TARGETS.get(pet_type, {}).get(
+            life_stage_key, {}
+        )
+        
+        if not macro_table:
+            logger.warning(f"No macro table for {pet_type}/{life_stage_key}, using adult_maintenance")
+            macro_table = settings.MACRONUTRIENT_TARGETS.get(pet_type, {}).get("adult_maintenance", {})
+        
+        protein_pct = macro_table.get("protein_pct", 20.0)
+        fat_pct = macro_table.get("fat_pct", 25.0)
+        
+        protein_pct, fat_pct = self._adjust_macros_for_conditions(protein_pct, fat_pct, profile)
+        
+        protein_calories = daily_calorie_target * (protein_pct / 100)
+        fat_calories = daily_calorie_target * (fat_pct / 100)
+        carb_calories = daily_calorie_target - protein_calories - fat_calories
+        
+        protein_g = (protein_calories / self.energy_densities["protein"]) * self.digestibility_factor
+        fat_g = (fat_calories / self.energy_densities["fat"]) * self.digestibility_factor
+        carbohydrates_g = carb_calories / self.energy_densities["carbohydrate"]
+        
+        min_protein_pct = macro_table.get("min_protein_pct", 18.0)
+        if protein_pct < min_protein_pct:
+            logger.warning(f"Protein {protein_pct}% below minimum {min_protein_pct}%, adjusting")
+            protein_pct = min_protein_pct
+            protein_calories = daily_calorie_target * (protein_pct / 100)
+            protein_g = (protein_calories / self.energy_densities["protein"]) * self.digestibility_factor
+        
+        logger.debug(
+            f"Macros calculated: protein={protein_pct}%→{protein_g:.2f}g, "
+            f"fat={fat_pct}%→{fat_g:.2f}g, carbs→{carbohydrates_g:.2f}g"
+        )
+        
+        return {
+            "protein_g": protein_g,
+            "fat_g": fat_g,
+            "carbohydrates_g": carbohydrates_g,
+        }
+    
+    def _get_macro_life_stage_key(self, profile: PetProfile) -> str:
+        if profile.life_stage == LifeStage.SENIOR:
+            return "senior"
+        elif profile.life_stage in [LifeStage.PUPPY, LifeStage.KITTEN]:
+            return "puppy_growth" if profile.pet_type == PetType.DOG else "kitten_growth"
+        else:
+            return "adult_maintenance"
+    
+    def _adjust_macros_for_conditions(
+        self, 
+        protein_pct: float, 
+        fat_pct: float, 
+        profile: PetProfile
+    ) -> Tuple[float, float]:
+    
+        
+        # Pregnancy: increase protein by 25%
+        if profile.pregnant_lactating == PregnantLactating.PREGNANT:
+            protein_pct *= 1.25
+            logger.debug(f"Pregnancy adjustment: protein increased 25% to {protein_pct:.1f}%")
+        
+        # Lactation: increase protein by 50%
+        if profile.pregnant_lactating == PregnantLactating.LACTATING:
+            protein_pct *= 1.5
+            logger.debug(f"Lactation adjustment: protein increased 50% to {protein_pct:.1f}%")
+        
+        
+        return protein_pct, fat_pct
+    
+    def _calculate_water(self, daily_calorie_target: float, profile: PetProfile) -> float:
+        """
+        Calculate water requirement.
+        
+        Base rule: 1 ml water per kcal consumed daily
+        Adjustments for lactation, growth, activity, senior
+        
+        Source: General veterinary guidelines (WSAVA, Merck Vet Manual)
+        
+        Args:
+            daily_calorie_target: MER in kcal/day
+            profile: Pet profile
+        
+        Returns:
+            Water requirement in ml/day
+        """
+        # Base calculation
+        water_ml = daily_calorie_target * settings.WATER_ML_PER_KCAL
+        
+        # Apply multipliers for special conditions
+        multiplier = 1.0
+        multiplier_reason = "base"
+        
+        if profile.pregnant_lactating == PregnantLactating.LACTATING:
+            multiplier = settings.WATER_MULTIPLIERS.get("lactating", 2.0)
+            multiplier_reason = "lactating"
+        elif profile.pregnant_lactating == PregnantLactating.PREGNANT:
+            multiplier = settings.WATER_MULTIPLIERS.get("pregnant", 1.5)
+            multiplier_reason = "pregnant"
+        elif profile.life_stage in [LifeStage.PUPPY, LifeStage.KITTEN]:
+            key = "puppy" if profile.pet_type == PetType.DOG else "kitten"
+            multiplier = settings.WATER_MULTIPLIERS.get(key, 1.5)
+            multiplier_reason = "growth"
+        elif profile.life_stage == LifeStage.SENIOR:
+            multiplier = settings.WATER_MULTIPLIERS.get("senior", 1.2)
+            multiplier_reason = "senior"
+        elif profile.activity_level == ActivityLevel.HIGH:
+            multiplier = settings.WATER_MULTIPLIERS.get("high_activity", 1.5)
+            multiplier_reason = "high_activity"
+        
+        water_ml *= multiplier
+        
+        if multiplier > 1.0:
+            logger.debug(f"Water adjusted: {multiplier}x for {multiplier_reason} → {water_ml:.2f}ml")
+        
+        return water_ml

nutrition_plan.json

@@ -1,38 +0,0 @@
-{
-  "pet_profile": {
-    "pet_type": "cat",
-    "breed": "siamese cat",
-    "gender": "female",
-    "pregnant_lactating": "pregnant",
-    "weight_kg": 35.0,
-    "activity_level": "low",
-    "life_stage": "adult",
-    "bcs": 7,
-    "neutered_spayed": "no",
-    "allergies": "none",
-    "diseases": "none",
-    "diet_preference": "mixed",
-    "current_food_format": "dry"
-  },
-  "nutrition_targets": {
-    "rer": 1007.28,
-    "mer": 1410.19,
-    "daily_calorie_target": 1410.19,
-    "protein_g": 153.1,
-    "fat_g": 46.5,
-    "carbohydrates_g": 137.2,
-    "water_ml": 875.0
-  },
-  "plan": {
-    "text": "PET NUTRITION PLAN -\n\nDAILY NUTRITION TARGETS\n\nEnergy Requirements\nRER: 1007.28 kcal/day\nMER: 1410.19 kcal/day\nDaily Calorie Target: 1410.19 kcal/day\n\nMacronutrients (Approx.)\nProtein: 153.1 g/day\nFat: 46.5 g/day\nCarbohydrates: 137.2 g/day\n\nHydration\nWater Intake: 900-1000 ml/day (inclusive of food moisture)\n\nRECOMMENDED MEAL PLAN WITH FEEDING SCHEDULE\nNumber of Meals: 3\nMeal Distribution: 33%-33%-34%\n\n8:00 AM - Morning Protein Bowl\nType: Home-Cooked / Wet Commercial\nCalories: 465 kcal\nIngredients: 250g cooked boneless, skinless chicken breast, 20g cooked chicken liver, 20g steamed green beans, 1/2 teaspoon salmon oil, veterinarian-prescribed complete and balanced vitamin/mineral supplement for home-cooked diets.\nPreparation: Cook chicken breast and liver thoroughly without seasoning. Steam green beans until tender. Dice all solid ingredients finely or mash. Mix thoroughly with salmon oil and the prescribed supplement.\nCommercial Alternative: 1.5 cans (e.g., 5.5 oz / 156g cans) of a high-protein, moderate-fat canned cat food (e.g., Wellness CORE Tuna & Salmon or Weruva Paw Lickin' Chicken) with approximately 300 kcal per can, ensuring the total calories match the target.\n\n1:00 PM - Mid-day Balanced Meal\nType: Home-Cooked / Wet Commercial\nCalories: 475 kcal\nIngredients: 200g cooked salmon fillet (skinless, boneless), 40g cooked mashed sweet potato, 1/2 teaspoon olive oil, veterinarian-prescribed complete and balanced vitamin/mineral supplement for home-cooked diets.\nPreparation: Bake or steam salmon until thoroughly cooked and flaked. Boil or steam sweet potato until soft, then mash. Mix salmon, mashed sweet potato, olive oil, and the prescribed supplement thoroughly.\nCommercial Alternative: 1.5 cans (e.g., 5.5 oz / 156g cans) of a different flavor of high-protein, moderate-fat canned cat food (e.g., Merrick Purrfect Bistro Beef Pate or Tiki Cat After Dark Chicken & Lamb), ensuring the total calories match the target.\n\n7:00 PM - Evening Nutritious Feast\nType: Home-Cooked / Dry Commercial\nCalories: 470 kcal\nIngredients: 180g cooked lean ground beef (90% lean or higher), 20g plain pumpkin puree, 1/4 cooked egg yolk (mashed), 1/4 teaspoon salmon oil, veterinarian-prescribed complete and balanced vitamin/mineral supplement for home-cooked diets.\nPreparation: Brown ground beef thoroughly, drain all fat. Mix with plain pumpkin puree, mashed cooked egg yolk, salmon oil, and the prescribed supplement. Ensure no seasonings.\nCommercial Alternative: 120-130g (approximately 4.2-4.6 oz) of a high-quality, high-protein dry cat food (e.g., Orijen Cat & Kitten or Acana Wild Prairie) with approximately 400 kcal per 100g, ensuring the total calories match the target. This can be served with a small amount of warm water to create a gravy.\n\nFEEDING INSTRUCTIONS\n1.  Measure all food ingredients or commercial portions precisely using a kitchen scale for accuracy, as the daily calorie target is high and portion control is critical.\n2.  Always ensure fresh, clean water is available at all times. Consider multiple water bowls or a pet water fountain to encourage increased hydration.\n3.  Monitor your cat's body condition regularly. Given the BCS of 7, the ultimate goal is safe and gradual weight loss, which will require subsequent calorie adjustments under veterinary supervision.\n4.  Introduce any new food ingredients or commercial diets gradually over a period of 7-10 days, mixing increasing amounts of the new food with decreasing amounts of the old food to prevent digestive upset.\n5.  All home-cooked meals MUST be formulated with a veterinary nutritionist-approved complete and balanced vitamin and mineral supplement designed for home-cooked cat diets to prevent nutritional deficiencies.\n\nFOOD CATEGORIES\nDangerous: Onions, garlic (all forms), chocolate, grapes, raisins, xylitol, avocado, alcohol, raw yeast dough.\nAvoid: Raw meat (due to bacterial contamination risks), excessive amounts of tuna (mercury concerns), large or cooked bones (choking hazard, splintering), dairy products (many cats are lactose intolerant), caffeinated beverages.\nSafe: Cooked lean meats (chicken, turkey, beef, lamb), cooked fish (salmon, cod, tilapia, ensuring no bones), cooked eggs, plain pumpkin puree, cooked green beans, cooked carrots, cooked sweet potato (in moderation), small amounts of cooked whole grains (e.g., plain oats, brown rice) in balanced diets.\n\nSAFETY NOTES\n1.  The provided daily calorie target of 1410.19 kcal/day is exceptionally high for a cat and typically corresponds to a much larger animal. Immediate veterinary consultation is crucial to verify this target, investigate the listed 35kg weight, and develop a safe and effective weight management plan for a cat with a BCS of 7 (obese).\n2.  Home-cooked diets, especially for specific calorie targets and conditions, require precise formulation by a veterinary nutritionist to ensure they are nutritionally complete and balanced. The provided home-cooked recipes are examples based on the calorie target but must be completed with a veterinary-approved supplement.\n3.  Closely monitor your cat for any adverse reactions to new foods, including vomiting, diarrhea, lethargy, or changes in appetite. Contact your veterinarian if any concerns arise.\n4.  Ensure all food is served at an appropriate temperature (room temperature) and remove any uneaten food after 30-60 minutes to prevent spoilage and bacterial growth, especially with wet or home-cooked meals.\n5.  Regular veterinary check-ups are essential to monitor your cat's overall health, track weight loss progress, and make any necessary adjustments to the diet plan.\n\nDISCLAIMER\nThis nutrition plan is AI-generated guidance and not a medical prescription. Consult a veterinarian for medical conditions or major diet changes.",
-    "sections": {
-      "header": "PET NUTRITION PLAN -",
-      "nutrition_targets": "DAILY NUTRITION TARGETS\n\nEnergy Requirements\nRER: 1007.28 kcal/day\nMER: 1410.19 kcal/day\nDaily Calorie Target: 1410.19 kcal/day\n\nMacronutrients (Approx.)\nProtein: 153.1 g/day\nFat: 46.5 g/day\nCarbohydrates: 137.2 g/day\n\nHydration\nWater Intake: 900-1000 ml/day (inclusive of food moisture)",
-      "meal_plan": "RECOMMENDED MEAL PLAN WITH FEEDING SCHEDULE\nNumber of Meals: 3\nMeal Distribution: 33%-33%-34%\n\n8:00 AM - Morning Protein Bowl\nType: Home-Cooked / Wet Commercial\nCalories: 465 kcal\nIngredients: 250g cooked boneless, skinless chicken breast, 20g cooked chicken liver, 20g steamed green beans, 1/2 teaspoon salmon oil, veterinarian-prescribed complete and balanced vitamin/mineral supplement for home-cooked diets.\nPreparation: Cook chicken breast and liver thoroughly without seasoning. Steam green beans until tender. Dice all solid ingredients finely or mash. Mix thoroughly with salmon oil and the prescribed supplement.\nCommercial Alternative: 1.5 cans (e.g., 5.5 oz / 156g cans) of a high-protein, moderate-fat canned cat food (e.g., Wellness CORE Tuna & Salmon or Weruva Paw Lickin' Chicken) with approximately 300 kcal per can, ensuring the total calories match the target.\n\n1:00 PM - Mid-day Balanced Meal\nType: Home-Cooked / Wet Commercial\nCalories: 475 kcal\nIngredients: 200g cooked salmon fillet (skinless, boneless), 40g cooked mashed sweet potato, 1/2 teaspoon olive oil, veterinarian-prescribed complete and balanced vitamin/mineral supplement for home-cooked diets.\nPreparation: Bake or steam salmon until thoroughly cooked and flaked. Boil or steam sweet potato until soft, then mash. Mix salmon, mashed sweet potato, olive oil, and the prescribed supplement thoroughly.\nCommercial Alternative: 1.5 cans (e.g., 5.5 oz / 156g cans) of a different flavor of high-protein, moderate-fat canned cat food (e.g., Merrick Purrfect Bistro Beef Pate or Tiki Cat After Dark Chicken & Lamb), ensuring the total calories match the target.\n\n7:00 PM - Evening Nutritious Feast\nType: Home-Cooked / Dry Commercial\nCalories: 470 kcal\nIngredients: 180g cooked lean ground beef (90% lean or higher), 20g plain pumpkin puree, 1/4 cooked egg yolk (mashed), 1/4 teaspoon salmon oil, veterinarian-prescribed complete and balanced vitamin/mineral supplement for home-cooked diets.\nPreparation: Brown ground beef thoroughly, drain all fat. Mix with plain pumpkin puree, mashed cooked egg yolk, salmon oil, and the prescribed supplement. Ensure no seasonings.\nCommercial Alternative: 120-130g (approximately 4.2-4.6 oz) of a high-quality, high-protein dry cat food (e.g., Orijen Cat & Kitten or Acana Wild Prairie) with approximately 400 kcal per 100g, ensuring the total calories match the target. This can be served with a small amount of warm water to create a gravy.",
-      "feeding_instructions": "FEEDING INSTRUCTIONS\n1.  Measure all food ingredients or commercial portions precisely using a kitchen scale for accuracy, as the daily calorie target is high and portion control is critical.\n2.  Always ensure fresh, clean water is available at all times. Consider multiple water bowls or a pet water fountain to encourage increased hydration.\n3.  Monitor your cat's body condition regularly. Given the BCS of 7, the ultimate goal is safe and gradual weight loss, which will require subsequent calorie adjustments under veterinary supervision.\n4.  Introduce any new food ingredients or commercial diets gradually over a period of 7-10 days, mixing increasing amounts of the new food with decreasing amounts of the old food to prevent digestive upset.\n5.  All home-cooked meals MUST be formulated with a veterinary nutritionist-approved complete and balanced vitamin and mineral supplement designed for home-cooked cat diets to prevent nutritional deficiencies.",
-      "food_categories": "FOOD CATEGORIES\nDangerous: Onions, garlic (all forms), chocolate, grapes, raisins, xylitol, avocado, alcohol, raw yeast dough.\nAvoid: Raw meat (due to bacterial contamination risks), excessive amounts of tuna (mercury concerns), large or cooked bones (choking hazard, splintering), dairy products (many cats are lactose intolerant), caffeinated beverages.\nSafe: Cooked lean meats (chicken, turkey, beef, lamb), cooked fish (salmon, cod, tilapia, ensuring no bones), cooked eggs, plain pumpkin puree, cooked green beans, cooked carrots, cooked sweet potato (in moderation), small amounts of cooked whole grains (e.g., plain oats, brown rice) in balanced diets.",
-      "safety_notes": "SAFETY NOTES\n1.  The provided daily calorie target of 1410.19 kcal/day is exceptionally high for a cat and typically corresponds to a much larger animal. Immediate veterinary consultation is crucial to verify this target, investigate the listed 35kg weight, and develop a safe and effective weight management plan for a cat with a BCS of 7 (obese).\n2.  Home-cooked diets, especially for specific calorie targets and conditions, require precise formulation by a veterinary nutritionist to ensure they are nutritionally complete and balanced. The provided home-cooked recipes are examples based on the calorie target but must be completed with a veterinary-approved supplement.\n3.  Closely monitor your cat for any adverse reactions to new foods, including vomiting, diarrhea, lethargy, or changes in appetite. Contact your veterinarian if any concerns arise.\n4.  Ensure all food is served at an appropriate temperature (room temperature) and remove any uneaten food after 30-60 minutes to prevent spoilage and bacterial growth, especially with wet or home-cooked meals.\n5.  Regular veterinary check-ups are essential to monitor your cat's overall health, track weight loss progress, and make any necessary adjustments to the diet plan.",
-      "disclaimer": "DISCLAIMER\nThis nutrition plan is AI-generated guidance and not a medical prescription. Consult a veterinarian for medical conditions or major diet changes."
-    }
-  }
-}

postprocess.py

@@ -63,48 +63,6 @@ class PostProcessor:
                     pass
         return values
 
-    # def extract_nutrition_values(self, final_plan: str) -> dict:
-    #     values = {}
-    #     lines = final_plan.split('\n')
-    #     for line in lines:
-    #         line = line.strip()
-    #         if line.startswith('RER:'):
-    #             try:
-    #                 values['rer'] = float(line.split('kcal/day')[0].split('RER:')[1].strip())
-    #             except:
-    #                 pass
-    #         elif line.startswith('MER:'):
-    #             try:
-    #                 values['mer'] = float(line.split('kcal/day')[0].split('MER:')[1].strip())
-    #             except:
-    #                 pass
-    #         elif line.startswith('Daily Calorie Target:'):
-    #             try:
-    #                 values['daily_calorie_target'] = float(line.split('kcal/day')[0].split('Daily Calorie Target:')[1].strip())
-    #             except:
-    #                 pass
-    #         elif line.startswith('Protein:'):
-    #             try:
-    #                 values['protein_g'] = float(line.split('g/day')[0].split('Protein:')[1].strip())
-    #             except:
-    #                 pass
-    #         elif line.startswith('Fat:'):
-    #             try:
-    #                 values['fat_g'] = float(line.split('g/day')[0].split('Fat:')[1].strip())
-    #             except:
-    #                 pass
-    #         elif line.startswith('Carbohydrates:'):
-    #             try:
-    #                 values['carbohydrates_g'] = float(line.split('g/day')[0].split('Carbohydrates:')[1].strip())
-    #             except:
-    #                 pass
-    #         elif line.startswith('Water Intake:'):
-    #             try:
-    #                 values['water_ml'] = float(line.split('ml/day')[0].split('Water Intake:')[1].strip())
-    #             except:
-    #                 pass
-    #     return values
-
     def parse_plan_sections(self, final_plan: str) -> dict:
         sections = {}
         lines = final_plan.split('\n')
@@ -163,11 +121,51 @@ class PostProcessor:
         return text
     
     def format_sections_for_api(self, sections: dict) -> dict:
-        """
-        Convert sections with \n into array of lines for better API response
-        """
         formatted = {}
         for key, value in sections.items():
-            # Split by \n and remove empty strings
-            formatted[key] = [line for line in value.split('\n') if line.strip()]
+            if key == 'food_categories':
+                formatted[key] = self._parse_food_categories(value)
+            else:
+                formatted[key] = [line for line in value.split('\n') if line.strip()]
         return formatted
+    
+    def _parse_food_categories(self, text: str) -> dict:
+    
+        result = {
+            "dangerous": [],
+            "avoid": [],
+            "safe": []
+        }
+        
+        lines = text.split('\n')
+        current_category = None
+        
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+            
+            if line.lower().startswith('dangerous:'):
+                current_category = 'dangerous'
+                items_text = line.split(':', 1)[1].strip()
+                if items_text:
+                    items = [item.strip() for item in items_text.split(',') if item.strip()]
+                    result['dangerous'].extend(items)
+            elif line.lower().startswith('avoid:'):
+                current_category = 'avoid'
+                items_text = line.split(':', 1)[1].strip()
+                if items_text:
+                    items = [item.strip() for item in items_text.split(',') if item.strip()]
+                    result['avoid'].extend(items)
+            elif line.lower().startswith('safe:'):
+                current_category = 'safe'
+                items_text = line.split(':', 1)[1].strip()
+                if items_text:
+                    items = [item.strip() for item in items_text.split(',') if item.strip()]
+                    result['safe'].extend(items)
+            else:
+                if current_category:
+                    items = [item.strip() for item in line.split(',') if item.strip()]
+                    result[current_category].extend(items)
+        
+        return result

rag/embed.py

@@ -1,5 +1,5 @@
 """
-Embedding layer for vectorization.
+Embedding layer.
 """
 import logging
 from typing import List

rag/retriever.py

@@ -12,10 +12,10 @@ from config import settings
 logger = logging.getLogger(__name__)
 
 class Retriever:
-    def __init__(self, embedder: EmbeddingLayer, vectorstore: VectorStore):
+    def __init__(self, embedder: EmbeddingLayer, vectorstore: VectorStore, cross_encoder: CrossEncoder):
         self.embedder = embedder
         self.vectorstore = vectorstore
-        self.cross_encoder = CrossEncoder(settings.RERANK_MODEL)
+        self.cross_encoder = cross_encoder
 
     def retrieve(self, query: str, top_k: int = 20) -> List[Dict[str, Any]]:
         query_vec = self.embedder.embed_query(query)
@@ -61,14 +61,6 @@ class Retriever:
 
 class KnowledgeRetriever:
 
-    @staticmethod
-    def create() -> 'KnowledgeRetriever':
-        embedder = EmbeddingLayer.create_embedder()
-        vectorstore = VectorStore.create_vectorstore()
-        vectorstore.load()
-        retriever = Retriever(embedder, vectorstore)
-        return KnowledgeRetriever(retriever)
-
     def __init__(self, retriever: Retriever):
         self.retriever = retriever
 

requirements.txt

@@ -1,23 +1,26 @@
+# Core
 python-dotenv==1.0.0
 pydantic==2.5.0
 pydantic-settings==2.1.0
 
-langchain==0.1.0
-langchain-community==0.0.10
-langchain-google-genai==0.0.5
-langchain-core
+langchain==1.2.10
+langchain-community==1.2.10
+langchain-google-genai==2.0.5
+langchain-core==1.2.10
 
+# Vector Store & Embeddings
 faiss-cpu
 sentence-transformers>=2.2.2
+torch
 
-torch 
+# PDF Processing 
+pymupdf>=1.23.0
 
-numpy==1.26.2
+# API
+fastapi==0.115.12
+uvicorn[standard]==0.34.2
 requests==2.31.0
-google-generativeai==0.3.2
-pymupdf4llm>=0.0.3
-tqdm==4.66.1
-tiktoken>=0.5.2
 
-fastapi==0.115.12
-uvicorn[standard]==0.34.2
+# Utilities
+tqdm==4.66.1
+tiktoken>=0.5.2

router.py

@@ -1,66 +1,160 @@
-from fastapi import APIRouter, HTTPException
-from schema import NutritionRequest, NutritionResponse
+from fastapi import APIRouter, HTTPException, Request
+import logging
+
+from schema import NutritionRequest, NutritionResponse, DailyTargets
  
 from input_handler import InputHandler
 from nutrition_engine import NutritionEngine
 from rules_engine import RulesEngine
-from load_kb import KnowledgeBaseLoader
-from rag.retriever import KnowledgeRetriever
-from llm.gemini_client import GeminiClient
 from llm.prompt_templates import PromptBuilder
 from postprocess import PostProcessor
+from validators.calorie_validator import CalorieDriftValidator
+from validators.dynamic_food_categories import DynamicFoodCategoryBuilder
 from config import settings
 
 router = APIRouter(prefix="/nutrition", tags=["Pet Nutrition"])
+logger = logging.getLogger(__name__)
 
+SECTION_ORDER = [
+    "meal_plan",
+    "feeding_instructions",
+    "food_categories",
+    "safety_notes",
+    "disclaimer",
+]
 
 @router.post("/plan", response_model=NutritionResponse)
-def generate_plan(payload: NutritionRequest):
-
+def generate_plan(request: Request, payload: NutritionRequest):
+    
+    app_state = request.app.state.app_state
+    
+    # Validate input
     input_handler = InputHandler.create_handler()
     pet_profile = input_handler.validate_and_parse(payload.model_dump())
 
     if not pet_profile:
         raise HTTPException(status_code=400, detail="Invalid input")
 
+    # Calculate nutrition targets (deterministic, lightweight)
     nutrition_engine = NutritionEngine.create_engine()
-    rules_engine = RulesEngine.create_engine()
+    
+    try:
+        nutrition_targets = nutrition_engine.calculate_nutrition_targets(pet_profile)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    
+    audit = nutrition_targets.pop("_audit")
+    
+    logger.info(
+        f"Nutrition calculated: RER={audit.rer} kcal/day, MER={audit.mer} kcal/day "
+        f"(multiplier={audit.mer_multiplier})"
+    )
+    logger.info(
+        f"Daily targets: {nutrition_targets['daily_calorie_target']} kcal, "
+        f"{nutrition_targets['protein_g']}g protein, {nutrition_targets['fat_g']}g fat"
+    )
 
-    kb_loader = KnowledgeBaseLoader.create_loader()
-    kb_loader.load_knowledge_base(force_rebuild=False)
-
-    nutrition_targets = nutrition_engine.calculate_nutrition_targets(pet_profile)
+    rules_engine = RulesEngine.create_engine()
     rules_engine.apply_rules(pet_profile, nutrition_targets)
 
-    retriever = KnowledgeRetriever.create()
+    # USE SHARED STATE 
+    # Step 1: Retrieve relevant context 
     prompt_builder = PromptBuilder()
-
     query = prompt_builder.build_retrieval_query(pet_profile, nutrition_targets)
-    retrieved_chunks = retriever.retrieve(query, top_k=settings.RETRIEVAL_TOP_K)
-
-    llm_client = GeminiClient.create()
-    chain = prompt_builder.generation_template | llm_client.llm
-
+    
+    logger.debug(f"Retrieval query: {query[:100]}...")
+    retrieved_chunks = app_state.retriever.retrieve(query, top_k=settings.RETRIEVAL_TOP_K)
+    logger.info(f"Retrieved {len(retrieved_chunks)} chunks")
+    
+    # Step 2: Build food categories (uses retrieved_chunks)
+    logger.info("Building food categories...")
+    food_builder = DynamicFoodCategoryBuilder.create_builder()
+    food_categories = food_builder.build_categories(
+        pet_profile.model_dump(),
+        retrieved_chunks
+    )
+    food_categories_text = (
+        f"Dangerous: {', '.join(food_categories.dangerous)}\n"
+        f"Avoid: {', '.join(food_categories.avoid)}\n"
+        f"Safe: {', '.join(food_categories.safe)}"
+    )
+    logger.info(f" Food categories built - {len(food_categories.dangerous)} dangerous, {len(food_categories.avoid)} avoid, {len(food_categories.safe)} safe")
+
+    # Step 3: Generate meal plan
+    chain = prompt_builder.generation_template | app_state.llm_client.llm
+
+    logger.info("Generating meal plan with Gemini...")
     response = chain.invoke({
         "pet_profile": pet_profile.model_dump(),
-        "nutrition_targets": nutrition_targets,
+        "daily_calorie_target": nutrition_targets["daily_calorie_target"],
+        "daily_protein_g": nutrition_targets["protein_g"],
+        "daily_fat_g": nutrition_targets["fat_g"],
+        "daily_carbohydrates_g": nutrition_targets["carbohydrates_g"],
+        "daily_water_ml": nutrition_targets["water_ml"],
         "retrieved_context": "\n\n".join(c["content"] for c in retrieved_chunks),
-        "instructions": prompt_builder.instructions,
+        "food_categories": food_categories_text,
     })
+    logger.info("Meal plan generated")
 
+    # Step 4: Post-process the LLM response
     post_processor = PostProcessor.create_processor()
     final_plan = post_processor.validate_and_clean(response.content)
 
-    extracted_values = post_processor.extract_nutrition_values(final_plan)
-    nutrition_targets.update(extracted_values)
-
-    clean_lines = [line.strip() for line in final_plan.splitlines() if line.strip()]
+    # Step 5: Parse sections
+    sections = post_processor.parse_plan_sections(final_plan)
+    formatted_sections = post_processor.format_sections_for_api(sections)
+    
+    # Step 6: CALORIE DRIFT VALIDATION (±15% tolerance)
+    logger.info("Validating calorie drift...")
+    calorie_validator = CalorieDriftValidator()
+    calorie_validator.TOLERANCE = 0.15  # ±15%
+    
+    # Extract meal plan text for validation
+    meal_text = "\\n".join(formatted_sections.get("meal_plan", []))
+    corrected_meal_text, validation_result = calorie_validator.validate_and_correct(
+        meal_text,
+        nutrition_targets["daily_calorie_target"]
+    )
+    
+    if validation_result.get("corrected"):
+        logger.info(f"Calorie drift corrected: scaled by {validation_result['scaling_factor']}")
+        formatted_sections["meal_plan"] = corrected_meal_text.split("\\n")
+    elif validation_result["within_tolerance"]:
+        logger.info(f"Calorie validation passed: {validation_result['deviation_pct']}% deviation")
+    else:
+        logger.warning(f"Calorie validation: {validation_result.get('message', 'No data')}")
+    
+    clean_sections = {}
+    for key in SECTION_ORDER:
+        section_data = formatted_sections.get(key, [])
+        
+        if section_data and isinstance(section_data, list) and len(section_data) > 0:
+            first_line = section_data[0]
+            uppercase_labels = [
+                "DISCLAIMER", "SAFETY NOTES", "FEEDING INSTRUCTIONS",
+                "FOOD CATEGORIES", "RECOMMENDED MEAL PLAN WITH FEEDING SCHEDULE",
+                "MEAL PLAN", "PET NUTRITION PLAN", "DAILY NUTRITION TARGETS"
+            ]
+            if first_line.strip().upper() in uppercase_labels:
+                section_data = section_data[1:]  
+        
+        clean_sections[key] = section_data if section_data else []
+    
+    logger.info(f"Sections ordered and cleaned: {list(clean_sections.keys())}")
+
+    daily_targets_dict = {
+        "daily_calorie_target": nutrition_targets["daily_calorie_target"],
+        "daily_protein_g": nutrition_targets["protein_g"],
+        "daily_fat_g": nutrition_targets["fat_g"],
+        "daily_carbohydrates_g": nutrition_targets["carbohydrates_g"],
+        "daily_water_ml": nutrition_targets["water_ml"],
+    }
 
     return {
         "pet_profile": pet_profile.model_dump(),
-        "nutrition_targets": nutrition_targets,
+        "nutrition_targets": daily_targets_dict,
         "plan": {
-            "text_lines": clean_lines,
-            "sections": post_processor.format_sections_for_api(post_processor.parse_plan_sections(final_plan))
+            "sections": clean_sections
         }
     }
+

schema.py

@@ -127,13 +127,108 @@ class NutritionRequest(BaseModel):
 
 
 class NutritionResponse(BaseModel):
-    pet_profile: Dict[str, Any]
-    nutrition_targets: Dict[str, Any]
-    plan: dict
-
-
-
 
+    pet_profile: Dict[str, Any]
+    nutrition_targets: Dict[str, float]  # Plain dict - more flexible
+    plan: Dict[str, Any]
+
+# USDA FoodData Central Schemas
+class USDANutrient(BaseModel):
+    """Single nutrient from USDA FoodData Central."""
+    nutrient_id: int
+    nutrient_name: str
+    unit_name: str
+    value: float
+
+
+class USDAFoodItem(BaseModel):
+    """USDA food item metadata."""
+    fdc_id: int
+    description: str
+    brand_owner: Optional[str] = None
+    ingredients: Optional[str] = None
+
+
+class USDAFoodData(BaseModel):
+    """Complete USDA food data with nutrients."""
+    food_item: USDAFoodItem
+    nutrients: List[USDANutrient]
+    source: str = "USDA FoodData Central"
+
+class NutritionSource(BaseModel):
+    """Track authoritative sources for calculations (NRC, AAFCO, WSAVA, etc)."""
+    source_type: str = Field(..., description="Source type: NRC, AAFCO, WSAVA, FEDIAF, USDA")
+    citation: str = Field(..., description="Full citation text")
+    url: Optional[str] = Field(None, description="Reference URL if available")
+    year: Optional[int] = Field(None, description="Publication year")
+
+
+class CalculationAudit(BaseModel):
+    """
+    Audit trail for nutrition calculations.
+    Contains internal calculations (RER/MER) that are logged but not shown to users.
+    """
+    rer: float = Field(..., description="Resting Energy Requirement (kcal/day)")
+    mer: float = Field(..., description="Maintenance Energy Requirement (kcal/day)")
+    mer_multiplier: float = Field(..., description="Multiplier used to calculate MER")
+    mer_source: NutritionSource = Field(..., description="Source for MER multiplier")
+    protein_pct_source: NutritionSource = Field(..., description="Source for protein percentage target")
+    fat_pct_source: NutritionSource = Field(..., description="Source for fat percentage target")
+    timestamp: str = Field(..., description="ISO timestamp of calculation")
+
+class DailyTargets(BaseModel):
+    
+    daily_calorie_target: float = Field(..., description="Total calories per day (kcal)")
+    protein_g: float = Field(..., description="Protein in grams per day")
+    fat_g: float = Field(..., description="Fat in grams per day")
+    carbohydrates_g: float = Field(..., description="Carbohydrates in grams per day")
+    water_ml: float = Field(..., description="Water in milliliters per day")
+
+# Structured Output Schemas 
+class MealOption(BaseModel):
+    """
+    Single meal option (Option A or B).
+    
+    Used for structured LLM output parsing.
+    """
+    option_label: str = Field(..., description="Option A or Option B")
+    meal_type: str = Field(..., description="e.g., Breakfast, Lunch, Dinner")
+    calories: float = Field(..., description="Estimated calories for this meal")
+    ingredients: List[str] = Field(..., min_length=1, description="List of ingredients")
+    quantities: List[str] = Field(..., min_length=1, description="Quantities with units (e.g., '100g', '1 cup')")
+    preparation_steps: List[str] = Field(..., min_length=1, description="Step-by-step preparation instructions")
+    nutrition_notes: Optional[str] = Field(None, description="Optional nutrition highlights")
+
+
+class Meal(BaseModel):
+
+    meal_time: str = Field(..., description="Time of day (e.g., 'Morning', 'Evening')")
+    meal_name: str = Field(..., description="Meal name (e.g., 'Breakfast', 'Dinner')")
+    options: List[MealOption] = Field(..., min_length=2, max_length=2, description="Option A and Option B")
+
+
+class MealPlan(BaseModel):
+    """
+    Complete daily meal plan with multiple meals.
+    """
+    num_meals: int = Field(..., ge=2, le=4, description="Number of meals per day (typically 2-3)")
+    meals: List[Meal] = Field(..., min_length=2, description="List of all meals")
+
+
+class FoodCategories(BaseModel):
+  
+    dangerous: List[str] = Field(..., max_length=10, description="Toxic/dangerous foods to NEVER feed")
+    avoid: List[str] = Field(..., max_length=10, description="Foods to avoid (not toxic but unhealthy)")
+    safe: List[str] = Field(..., max_length=10, description="Safe and healthy foods")
+
+
+class NutritionPlanOutput(BaseModel):
+
+    meal_plan: MealPlan = Field(..., description="Complete meal plan with options")
+    feeding_instructions: List[str] = Field(..., max_length=7, description="General feeding guidelines")
+    food_categories: FoodCategories = Field(..., description="Safe/dangerous food lists")
+    safety_notes: List[str] = Field(..., max_length=5, description="Important safety warnings")
+    hydration_tips: Optional[List[str]] = Field(None, max_length=3, description="Water intake recommendations")
 
 
 

scripts/rebuild_kb.py

@@ -0,0 +1,71 @@
+"""
+Script to rebuild the knowledge base from PDFs.
+
+"""
+import logging
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from load_kb import KnowledgeBaseLoader
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+def main():
+  
+    print("KNOWLEDGE BASE REBUILD SCRIPT")
+    print()
+    
+    try:
+        # Create loader
+        logger.info("Initializing knowledge base loader...")
+        kb_loader = KnowledgeBaseLoader.create_loader()
+        
+        # Force rebuild
+        logger.info("Starting KB rebuild (force_rebuild=True)...")
+        print()
+        
+        result = kb_loader.load_knowledge_base(force_rebuild=True)
+        
+        # Display results
+        print()
+      
+        print("KNOWLEDGE BASE REBUILD COMPLETE")
+  
+        print(f"Status:  {result['status']}")
+        print(f"PDFs:    {result.get('pdfs', 'N/A')}")
+        print(f"Chunks:  {result['chunks']}")
+        print(f"Time:    {result['time_sec']}s")
+ 
+        print()
+        
+        # Verification
+        if result['chunks'] > 3000:
+            print("Success! Expected ~3309 chunks, got", result['chunks'])
+        elif result['chunks'] > 2000:
+            print("Warning: Got", result['chunks'], "chunks (expected ~3309)")
+        else:
+            print("Error: Only", result['chunks'], "chunks (expected ~3309)")
+        
+        print()
+        print("Vector store saved to: kb/vector_db/")
+        print()
+        
+    except Exception as e:
+        logger.exception("Failed to rebuild knowledge base")
+        print()
+   
+        print("ERROR")
+
+        print(f"Failed to rebuild KB: {e}")
+ 
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

services/ingredient_nutrition.py

@@ -0,0 +1,71 @@
+"""
+Ingredient nutrition service with USDA fallback to LLM.
+"""
+import logging
+from typing import Dict, Any, Optional
+
+from kb.usda_client import USDAClient
+
+logger = logging.getLogger(__name__)
+
+
+class IngredientNutritionService:
+    
+
+    def __init__(self, usda_client: Optional[USDAClient] = None, llm_client=None):
+        
+        self.usda = usda_client or USDAClient.create()
+        self.llm = llm_client
+        logger.debug("IngredientNutritionService initialized")
+    
+    @staticmethod
+    def create(usda_client=None, llm_client=None) -> "IngredientNutritionService":
+    
+        return IngredientNutritionService(usda_client, llm_client)
+    
+    def get_nutrition(
+        self, 
+        ingredient: str, 
+        quantity_grams: float = 100.0
+    ) -> Dict[str, Any]:
+        
+        # Try USDA first
+        logger.debug(f"Looking up nutrition for '{ingredient}' ({quantity_grams}g)")
+        
+        usda_nutrition = self.usda.get_nutrition_for_ingredient(ingredient, quantity_grams)
+        
+        if usda_nutrition:
+            logger.info(f"USDA data found for '{ingredient}'")
+            return usda_nutrition
+        
+        logger.warning(f"USDA failed for '{ingredient}', using LLM fallback")
+        return self._llm_estimate(ingredient, quantity_grams)
+    
+    def _llm_estimate(self, ingredient: str, quantity_grams: float) -> Dict[str, Any]:
+        
+        if not self.llm:
+            logger.error("No LLM available for fallback estimation")
+            return self._default_fallback(ingredient, quantity_grams)
+        
+        try:
+       
+            logger.warning(f"LLM estimation not yet implemented, using defaults for '{ingredient}'")
+            return self._default_fallback(ingredient, quantity_grams)
+        
+        except Exception as e:
+            logger.error(f"LLM estimation failed: {e}")
+            return self._default_fallback(ingredient, quantity_grams)
+    
+    def _default_fallback(self, ingredient: str, quantity_grams: float) -> Dict[str, Any]:
+        
+        logger.error(f"All methods failed for '{ingredient}', returning zeros")
+        
+        return {
+            "calories": 0.0,
+            "protein_g": 0.0,
+            "fat_g": 0.0,
+            "carbs_g": 0.0,
+            "source": "UNKNOWN",
+            "description": ingredient,
+            "warning": "Nutrition data unavailable - both USDA and LLM failed"
+        }

validators/__init__.py

@@ -0,0 +1,4 @@
+from .calorie_validator import CalorieDriftValidator
+from .dynamic_food_categories import DynamicFoodCategoryBuilder, FoodCategories
+
+__all__ = ["CalorieDriftValidator", "DynamicFood CategoryBuilder", "FoodCategories"]

validators/calorie_validator.py

@@ -0,0 +1,129 @@
+import logging
+import re
+from typing import Dict, List, Tuple, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class CalorieDriftValidator:
+    
+    TOLERANCE = 0.05  # ±5% tolerance
+    
+    @staticmethod
+    def create_validator() -> 'CalorieDriftValidator':
+        return CalorieDriftValidator()
+    
+    def extract_meal_calories(self, meal_plan_text: str) -> List[Tuple[str, float]]:
+        
+        meals = []
+        
+        pattern = r'([\w\s]+)\s*\(Approx\.\s*(\d+(?:\.\d+)?)\s*kcal\)'
+        matches = re.findall(pattern, meal_plan_text, re.IGNORECASE)
+        
+        for meal_name, cal_value in matches:
+            try:
+                calories = float(cal_value)
+                meals.append((meal_name.strip(), calories))
+            except ValueError:
+                logger.warning(f"Could not parse calorie value: {cal_value}")
+                continue
+        
+        logger.info(f"Extracted {len(meals)} meals with calorie values")
+        return meals
+    
+    def validate_total_calories(
+        self,
+        meal_calories: List[Tuple[str, float]],
+        daily_target: float
+    ) -> Dict[str, any]:
+       
+        if not meal_calories:
+            return {
+                "valid": False,
+                "total_extracted": 0.0,
+                "target": daily_target,
+                "deviation_pct": 100.0,
+                "within_tolerance": False,
+                "message": "No meal calories extracted"
+            }
+        
+        total_extracted = sum(cal for _, cal in meal_calories)
+        deviation = abs(total_extracted - daily_target) / daily_target
+        deviation_pct = deviation * 100
+        
+        within_tolerance = deviation <= self.TOLERANCE
+        
+        result = {
+            "valid": True,
+            "total_extracted": total_extracted,
+            "target": daily_target,
+            "deviation_pct": round(deviation_pct, 2),
+            "within_tolerance": within_tolerance
+        }
+        
+        if within_tolerance:
+            logger.info(
+                f"Calorie validation PASSED: {total_extracted} kcal "
+                f"vs target {daily_target} kcal (deviation: {deviation_pct:.2f}%)"
+            )
+        else:
+            logger.warning(
+                f"Calorie validation FAILED: {total_extracted} kcal "
+                f"vs target {daily_target} kcal (deviation: {deviation_pct:.2f}% > {self.TOLERANCE*100}%)"
+            )
+        
+        return result
+    
+    def scale_meal_calories(
+        self,
+        meal_plan_text: str,
+        scaling_factor: float
+    ) -> str:
+        
+        def replace_calorie(match):
+            meal_name = match.group(1)
+            original_cal = float(match.group(2))
+            scaled_cal = round(original_cal * scaling_factor, 1)
+            return f"{meal_name} (Approx. {int(scaled_cal)} kcal)"
+        
+        pattern = r'([\w\s]+)\s*\(Approx\.\s*(\d+(?:\.\d+)?)\s*kcal\)'
+        scaled_text = re.sub(pattern, replace_calorie, meal_plan_text, flags=re.IGNORECASE)
+        
+        logger.info(f"Scaled meal calories by factor {scaling_factor:.3f}")
+        return scaled_text
+    
+    def validate_and_correct(
+        self,
+        meal_plan_text: str,
+        daily_calorie_target: float
+    ) -> Tuple[str, Dict[str, any]]:
+       
+        # Extract meals
+        meal_calories = self.extract_meal_calories(meal_plan_text)
+        
+        # Validate
+        validation = self.validate_total_calories(meal_calories, daily_calorie_target)
+        
+        # If within tolerance, return as-is
+        if validation["within_tolerance"] or not validation["valid"]:
+            return meal_plan_text, validation
+        
+        # Calculate scaling factor
+        total_extracted = validation["total_extracted"]
+        scaling_factor = daily_calorie_target / total_extracted
+        
+        logger.info(
+            f"Applying calorie correction: scaling by {scaling_factor:.3f} "
+            f"to bring {total_extracted} → {daily_calorie_target} kcal"
+        )
+        
+        # Scale calories
+        corrected_plan = self.scale_meal_calories(meal_plan_text, scaling_factor)
+        
+        # Re-validate
+        corrected_meals = self.extract_meal_calories(corrected_plan)
+        final_validation = self.validate_total_calories(corrected_meals, daily_calorie_target)
+        final_validation["corrected"] = True
+        final_validation["scaling_factor"] = round(scaling_factor, 3)
+        
+        return corrected_plan, final_validation

validators/dynamic_food_categories.py

@@ -0,0 +1,148 @@
+import logging
+from typing import Dict, List, Set
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class FoodCategories:
+    """Pet-specific food safety categories."""
+    dangerous: List[str]
+    avoid: List[str]
+    safe: List[str]
+
+
+class DynamicFoodCategoryBuilder:
+    """Builds dynamic food categories based on pet profile."""
+    
+    DOG_DANGEROUS = [
+        "chocolate", "xylitol", "grapes", "raisins", "onions", "garlic",
+        "macadamia nuts", "avocado", "alcohol", "caffeine"
+    ]
+    
+    CAT_DANGEROUS = [
+        "onions", "garlic", "grapes", "raisins", "alcohol", "caffeine",
+        "chocolate", "xylitol", "raw dough", "chives"
+    ]
+    
+    PUPPY_AVOID = ["adult dog food", "large bones", "high-fat treats"]
+    SENIOR_DOG_AVOID = ["high sodium foods", "overly rich foods"]
+    
+    KITTEN_AVOID = ["adult cat food", "dog food", "raw eggs"]
+    SENIOR_CAT_AVOID = ["high phosphorus foods", "excessive protein"]
+    
+    DISEASE_CONTRAINDICATIONS = {
+        "kidney": ["high phosphorus", "excessive protein", "high sodium"],
+        "liver": ["high copper foods", "high fat"],
+        "diabetes": ["high sugar", "simple carbs", "honey"],
+        "pancreatitis": ["high fat", "fatty meats", "fried foods"],
+        "heart": ["high sodium", "salt", "processed meats"],
+        "allergies": [],  
+    }
+    
+    @staticmethod
+    def create_builder() -> 'DynamicFoodCategoryBuilder':
+        return DynamicFoodCategoryBuilder()
+    
+    def build_categories(
+        self,
+        pet_profile: Dict,
+        retrieved_chunks: List[Dict] = None
+    ) -> FoodCategories:
+        
+        pet_type = pet_profile.get("pet_type", "dog").lower()
+        life_stage = pet_profile.get("life_stage", "adult").lower()
+        allergies = pet_profile.get("allergies") or ""
+        diseases = pet_profile.get("diseases") or ""
+        
+        dangerous = set(self.DOG_DANGEROUS if pet_type == "dog" else self.CAT_DANGEROUS)
+        avoid = set()
+        
+        if pet_type == "dog":
+            if life_stage == "puppy":
+                avoid.update(self.PUPPY_AVOID)
+            elif life_stage == "senior":
+                avoid.update(self.SENIOR_DOG_AVOID)
+        else:  # cat
+            if life_stage == "kitten":
+                avoid.update(self.KITTEN_AVOID)
+            elif life_stage == "senior":
+                avoid.update(self.SENIOR_CAT_AVOID)
+        
+        if allergies:
+            allergy_list = [a.strip().lower() for a in allergies.split(",")]
+            avoid.update(allergy_list)
+            logger.info(f"Added allergies to avoid list: {allergy_list}")
+        
+        if diseases:
+            disease_list = [d.strip().lower() for d in diseases.split(",")]
+            for disease in disease_list:
+                for key, contraindications in self.DISEASE_CONTRAINDICATIONS.items():
+                    if key in disease:
+                        avoid.update(contraindications)
+                        logger.info(f"Added {key} contraindications: {contraindications}")
+        
+        if retrieved_chunks:
+            rag_contraindications = self._extract_contraindications_from_rag(
+                retrieved_chunks, diseases
+            )
+            if rag_contraindications:
+                avoid.update(rag_contraindications)
+                logger.info(f"Added RAG contraindications: {rag_contraindications}")
+            
+            safe = self._get_safe_foods(pet_type, life_stage)
+        
+        return FoodCategories(
+            dangerous=sorted(list(dangerous)),
+            avoid=sorted(list(avoid)),
+            safe=safe
+        )
+    
+    def _extract_contraindications_from_rag(
+        self,
+        chunks: List[Dict],
+        diseases: str
+    ) -> Set[str]:
+        contraindications = set()
+        
+        keywords = ["avoid", "contraindicated", "not recommended", "toxic for"]
+        
+        for chunk in chunks:
+            content = chunk.get("content", "").lower()
+            
+            for keyword in keywords:
+                if keyword in content and (diseases.lower() in content):
+                    words = content.split()
+                    if keyword in words:
+                        idx = words.index(keyword)
+                        potential = words[idx+1:idx+5]
+                        for word in potential:
+                            if len(word) > 3 and word.isalpha():
+                                contraindications.add(word)
+        
+        return contraindications
+    
+    def _get_safe_foods(self, pet_type: str, life_stage: str) -> List[str]:
+        """Get general safe foods for this pet."""
+        if pet_type == "dog":
+            safe = [
+                "lean chicken", "turkey", "beef", "lamb",
+                "sweet potatoes", "carrots", "green beans", "peas",
+                "brown rice", "oatmeal", "pumpkin", "blueberries",
+                "plain yogurt", "eggs (cooked)"
+            ]
+        else: 
+            safe = [
+                "cooked chicken", "turkey", "salmon", "tuna (moderation)",
+                "cooked eggs", "cooked fish", "plain chicken broth",
+                "small amounts of cooked vegetables"
+            ]
+        
+        if life_stage == "puppy" or life_stage == "kitten":
+            safe.append("high-quality puppy/kitten formula food")
+        elif life_stage == "senior":
+            safe.append("easily digestible proteins")
+            safe.append("joint-supporting supplements")
+        
+        return safe