Spaces:
Running
Running
Download agents/smartdocs_graph.py from Sahilalaknur/smartdocs-ui: direct link, hf CLI and curl.
- Browser
- Download file 24.9 kB
-
https://huggingface.co/spaces/Sahilalaknur/smartdocs-ui/resolve/main/agents/smartdocs_graph.py
- Command line
-
hf download hf://spaces/Sahilalaknur/smartdocs-ui/agents/smartdocs_graph.py
-
curl -L -o smartdocs_graph.py https://huggingface.co/spaces/Sahilalaknur/smartdocs-ui/resolve/main/agents/smartdocs_graph.py
24.9 kB
| # agents/smartdocs_graph.py | |
| # WHY THIS EXISTS: Complete LangGraph agentic loop. LAW 8 + LAW 9. | |
| # Not a pipeline β a stateful graph with conditional edges and retry cycles. | |
| # Every decision point is a conditional edge. Every failure has a fallback. | |
| # Streaming via astream_events v2 β sources before answer tokens. | |
| import logging | |
| import time | |
| from typing import Optional, TypedDict | |
| from langgraph.graph import StateGraph, START, END | |
| from config.settings import get_settings | |
| from retrieval.language_detector import ( | |
| detect_language, | |
| build_language_system_prompt_instruction, | |
| LanguageDetectionResult, | |
| ) | |
| from retrieval.query_classifier import classify_query, QueryClassificationResult | |
| from retrieval.query_transformer import transform_query, TransformedQueries | |
| from retrieval.hybrid_retriever import retrieve_multi_query, RetrievedChunk | |
| from retrieval.cache import get_cached_response, set_cached_response | |
| from retrieval.crag_fallback import crag_web_search, build_crag_context_note, CRAGResult | |
| from reranking.reranker import rerank_chunks, RerankedResult, RerankerDecision | |
| from generation.context_assembler import assemble_context, AssembledContext | |
| from generation.sarvam_client import ( | |
| stream_answer, | |
| build_system_prompt, | |
| get_no_info_response, | |
| GenerationResult, | |
| ) | |
| from generation.self_critique import critique_answer, CritiqueResult | |
| from guardrails.output_guardrail import run_guardrail, GuardrailResult | |
| from observability.cost_tracker import calculate_query_cost, QueryCost | |
| from observability.langsmith_tracer import TraceMetadata, build_run_metadata | |
| settings = get_settings() | |
| logger = logging.getLogger(__name__) | |
| MAX_RETRIES = 2 | |
| # ββ Graph State βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| class SmartDocsState(TypedDict, total=False): | |
| """ | |
| Complete state passed between all LangGraph nodes. | |
| total=False β all fields are optional (not required at init). | |
| Nodes update only the fields they own. | |
| """ | |
| # ββ Input fields (required at graph entry) ββββββββββββββββββββββββββββββββ | |
| query: str | |
| user_id: str | |
| doc_id: Optional[str] | |
| doc_title: str | |
| # ββ Language and classification βββββββββββββββββββββββββββββββββββββββββββ | |
| lang_result: Optional[LanguageDetectionResult] | |
| query_classification: Optional[QueryClassificationResult] | |
| # ββ Cache βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| cache_hit: bool | |
| cached_response: Optional[dict] | |
| # ββ Query transformation ββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| transformed_queries: Optional[TransformedQueries] | |
| # ββ Retrieval and reranking βββββββββββββββββββββββββββββββββββββββββββββββ | |
| retrieved_chunks: list[RetrievedChunk] | |
| rerank_result: Optional[RerankedResult] | |
| # ββ CRAG ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| crag_result: Optional[CRAGResult] | |
| crag_triggered: bool | |
| # ββ Context and generation ββββββββββββββββββββββββββββββββββββββββββββββββ | |
| assembled_context: Optional[AssembledContext] | |
| system_prompt: str | |
| raw_answer: str | |
| stream_tokens: list[str] | |
| input_tokens: int | |
| output_tokens: int | |
| # ββ Self-critique βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| critique_result: Optional[CritiqueResult] | |
| retry_count: int | |
| active_query: str # May be refined query on retry | |
| # ββ Guardrail βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| guardrail_result: Optional[GuardrailResult] | |
| # ββ Final output ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| final_answer: str | |
| cited_sources: list[dict] | |
| cost: Optional[QueryCost] | |
| total_latency_ms: float | |
| graph_start_time: float | |
| # ββ Node functions ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| async def preprocess_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 1: Language detection + query classification + cache check. | |
| All three run before any retrieval or API call. | |
| Cache hit β short-circuits entire graph. | |
| """ | |
| query = state["query"] | |
| user_id = state["user_id"] | |
| # Language detection | |
| lang_result = detect_language(query) | |
| # Query classification | |
| query_classification = classify_query(query) | |
| # Cache check | |
| cached = await get_cached_response(query=query, user_id=user_id) | |
| if cached: | |
| logger.info( | |
| "Cache hit β short-circuiting graph", | |
| extra={"user_id": user_id, "similarity": cached.get("cache_similarity")}, | |
| ) | |
| return { | |
| "lang_result": lang_result, | |
| "query_classification": query_classification, | |
| "cache_hit": True, | |
| "cached_response": cached, | |
| "active_query": query, | |
| } | |
| return { | |
| "lang_result": lang_result, | |
| "query_classification": query_classification, | |
| "cache_hit": False, | |
| "cached_response": None, | |
| "active_query": query, | |
| } | |
| async def transform_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 2: Multi-query + HyDE + step-back transformation. | |
| Runs in parallel via asyncio.gather inside transform_query(). | |
| """ | |
| transformed = await transform_query( | |
| query=state["active_query"], | |
| lang_result=state["lang_result"], | |
| ) | |
| return {"transformed_queries": transformed} | |
| async def retrieve_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 3: Hybrid retrieval across all transformed query variants. | |
| Uses active_query (may be refined query on retry cycles). | |
| Dense 0.7 + BM25 0.3 + RRF. top-20 candidates. | |
| """ | |
| # ββ DEPENDENCY INJECTION FIX FOR LANGGRAPH STUDIO ββ | |
| # Intercepts manual JSON payloads from the UI to test documents without a database. | |
| if state.get("retrieved_chunks"): | |
| raw_chunks = state["retrieved_chunks"] | |
| if len(raw_chunks) > 0 and isinstance(raw_chunks[0], dict): | |
| from retrieval.hybrid_retriever import RetrievedChunk | |
| try: | |
| # Convert Studio's raw JSON dicts into your strict Python objects | |
| object_chunks = [RetrievedChunk(**c) for c in raw_chunks] | |
| return {"retrieved_chunks": object_chunks} | |
| except Exception as e: | |
| logger.warning(f"Mock injection failed kwargs mapping: {e}") | |
| return {"retrieved_chunks": raw_chunks} | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| transformed = state.get("transformed_queries") | |
| queries = ( | |
| transformed.all_queries | |
| if transformed and transformed.all_queries | |
| else [state["active_query"]] | |
| ) | |
| chunks = await retrieve_multi_query( | |
| queries=queries, | |
| user_id=state["user_id"], | |
| lang_result=state["lang_result"], | |
| doc_id=state.get("doc_id"), | |
| top_k_candidates=20, | |
| ) | |
| return {"retrieved_chunks": chunks} | |
| async def rerank_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 4: FlashRank reranking of top-20 candidates β top-5. | |
| Score thresholds determine next node: | |
| > 0.7 β assemble_context_node | |
| 0.3β0.7 β crag_node | |
| < 0.3 β END (insufficient) | |
| """ | |
| chunks = state.get("retrieved_chunks", []) | |
| query = state["active_query"] | |
| rerank_result = rerank_chunks( | |
| query=query, | |
| chunks=chunks, | |
| top_k=5, | |
| ) | |
| return {"rerank_result": rerank_result} | |
| async def crag_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 5: Tavily web search fallback. LAW 13. | |
| Only runs when reranker score is 0.3β0.7. | |
| Results are ephemeral β never stored in pgvector. | |
| """ | |
| crag_result = await crag_web_search(query=state["active_query"]) | |
| return { | |
| "crag_result": crag_result, | |
| "crag_triggered": crag_result.triggered, | |
| } | |
| async def assemble_context_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 6: Context assembly with citation injection and delimiter wrapping. | |
| Combines document chunks + CRAG web chunks if present. | |
| Builds full system prompt for Sarvam-30B. | |
| """ | |
| rerank_result = state["rerank_result"] | |
| lang_result = state["lang_result"] | |
| query_classification = state["query_classification"] | |
| crag_result = state.get("crag_result") | |
| # Assemble context | |
| assembled = assemble_context( | |
| chunks=rerank_result.chunks, | |
| crag_result=crag_result, | |
| ) | |
| # Build context text β prepend CRAG note if web results included | |
| context_text = assembled.context_text | |
| if state.get("crag_triggered"): | |
| context_text = build_crag_context_note() + context_text | |
| # Build system prompt | |
| language_instruction = build_language_system_prompt_instruction(lang_result) | |
| system_prompt = build_system_prompt( | |
| language_instruction=language_instruction, | |
| context_with_citations=context_text, | |
| detected_language=lang_result.language_name, | |
| query_type=query_classification.query_type.value, | |
| doc_title=state.get("doc_title", "your document"), | |
| ) | |
| return { | |
| "assembled_context": assembled, | |
| "system_prompt": system_prompt, | |
| "cited_sources": assembled.cited_sources, | |
| } | |
| async def generate_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 7: Sarvam-30B generation with streaming. | |
| Streams tokens into state. FastAPI SSE reads from state in Part 5. | |
| """ | |
| full_answer, input_tokens, output_tokens = await stream_answer( | |
| query=state["active_query"], | |
| system_prompt=state["system_prompt"], | |
| ) | |
| return { | |
| "raw_answer": full_answer, | |
| "input_tokens": input_tokens, | |
| "output_tokens": output_tokens, | |
| } | |
| async def critique_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 8: Self-critique β faithfulness + language match. LAW 8. | |
| faithfulness < 0.75 β retry_needed=True | |
| language_match = False β retry_needed=True | |
| retry_count >= 2 β passed=False β graceful failure | |
| """ | |
| assembled = state.get("assembled_context") | |
| context = assembled.context_text if assembled else "" | |
| retry_count = state.get("retry_count", 0) | |
| critique_result = await critique_answer( | |
| query=state["active_query"], | |
| answer=state["raw_answer"], | |
| context=context, | |
| query_language=state["lang_result"].language_name, | |
| retry_count=retry_count, | |
| ) | |
| # If retry needed β use refined query if critique provided one | |
| active_query = state["active_query"] | |
| if critique_result.retry_needed and critique_result.refined_query: | |
| active_query = critique_result.refined_query | |
| logger.info( | |
| "Critique refined query for retry", | |
| extra={"refined": active_query[:80]}, | |
| ) | |
| return { | |
| "critique_result": critique_result, | |
| "retry_count": retry_count + (1 if critique_result.retry_needed else 0), | |
| "active_query": active_query, | |
| } | |
| async def guardrail_node(state: SmartDocsState) -> dict: | |
| """ | |
| Node 9: Final output guardrail β PII, injection, off-topic. | |
| Calculates final cost. Stores in cache. Returns clean answer. | |
| """ | |
| guardrail_result = run_guardrail(state["raw_answer"]) | |
| # Calculate total cost | |
| cost = calculate_query_cost( | |
| input_tokens=state.get("input_tokens", 0), | |
| output_tokens=state.get("output_tokens", 0), | |
| crag_triggered=state.get("crag_triggered", False), | |
| ) | |
| # Total latency | |
| start_time = state.get("graph_start_time", time.perf_counter()) | |
| total_latency_ms = round((time.perf_counter() - start_time) * 1000, 2) | |
| final_answer = guardrail_result.clean_answer | |
| # Store in cache (non-blocking) | |
| try: | |
| await set_cached_response( | |
| query=state["query"], | |
| user_id=state["user_id"], | |
| response={ | |
| "answer": final_answer, | |
| "cited_sources": state.get("cited_sources", []), | |
| "cost_inr": cost.total_inr, | |
| "language": state["lang_result"].language_code, | |
| }, | |
| ) | |
| except Exception as e: | |
| logger.warning("Cache store failed β non-fatal", extra={"error": str(e)}) | |
| return { | |
| "guardrail_result": guardrail_result, | |
| "final_answer": final_answer, | |
| "cost": cost, | |
| "total_latency_ms": total_latency_ms, | |
| } | |
| # ββ Routing functions βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def route_after_preprocess(state: SmartDocsState) -> str: | |
| """Cache hit β return cached answer. No cache β transform query.""" | |
| if state.get("cache_hit"): | |
| return "serve_cache_node" | |
| return "transform_node" | |
| def route_after_rerank(state: SmartDocsState) -> str: | |
| """ | |
| Routes based on reranker decision: | |
| PROCEED β assemble context | |
| CRAG β web search fallback | |
| INSUFFICIENT β return no-info response | |
| """ | |
| rerank_result = state.get("rerank_result") | |
| if not rerank_result: | |
| return "insufficient_node" | |
| decision = rerank_result.decision | |
| if decision == RerankerDecision.PROCEED: | |
| return "assemble_context_node" | |
| elif decision == RerankerDecision.CRAG_FALLBACK: | |
| return "crag_node" | |
| else: | |
| return "insufficient_node" | |
| def route_after_critique(state: SmartDocsState) -> str: | |
| """ | |
| Routes based on critique result: | |
| passed=True β guardrail | |
| retry_needed=True AND retry_count < MAX_RETRIES β retrieve again | |
| all else β graceful failure | |
| """ | |
| critique_result = state.get("critique_result") | |
| if not critique_result: | |
| return "guardrail_node" | |
| if critique_result.passed: | |
| return "guardrail_node" | |
| if critique_result.retry_needed and state.get("retry_count", 0) <= MAX_RETRIES: | |
| logger.info( | |
| "Self-critique retry", | |
| extra={ | |
| "retry_count": state.get("retry_count"), | |
| "issues": critique_result.issues, | |
| }, | |
| ) | |
| return "retrieve_node" | |
| return "insufficient_node" | |
| # ββ Terminal nodes ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| async def serve_cache_node(state: SmartDocsState) -> dict: | |
| """Returns cached response directly β zero retrieval or generation.""" | |
| cached = state.get("cached_response", {}) | |
| return { | |
| "final_answer": cached.get("answer", ""), | |
| "cited_sources": cached.get("cited_sources", []), | |
| "cost": calculate_query_cost(0, 0), | |
| "total_latency_ms": 0.0, | |
| } | |
| async def insufficient_node(state: SmartDocsState) -> dict: | |
| """ | |
| Returns graceful no-information response. | |
| Triggered when: reranker score < 0.3, or critique fails after max retries. | |
| Response is in the user's detected language. | |
| """ | |
| lang_code = state.get("lang_result").language_code if state.get("lang_result") else "en" | |
| no_info = get_no_info_response(lang_code) | |
| logger.info( | |
| "Insufficient information β returning graceful response", | |
| extra={"language": lang_code}, | |
| ) | |
| return { | |
| "final_answer": no_info, | |
| "cited_sources": [], | |
| "cost": calculate_query_cost(0, 0), | |
| "total_latency_ms": 0.0, | |
| } | |
| # ββ Graph builder βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def build_graph(): | |
| """ | |
| Builds and compiles the complete SmartDocs LangGraph. | |
| Called once at application startup. | |
| Graph topology: | |
| START | |
| β preprocess_node | |
| β [cache_hit] serve_cache_node β END | |
| β [no_cache] transform_node | |
| β retrieve_node | |
| β rerank_node | |
| β [proceed] assemble_context_node | |
| β [crag] crag_node β assemble_context_node | |
| β [insufficient] insufficient_node β END | |
| β generate_node | |
| β critique_node | |
| β [pass] guardrail_node β END | |
| β [retry] retrieve_node (cycle β max 2x) | |
| β [fail] insufficient_node β END | |
| """ | |
| builder = StateGraph(SmartDocsState) | |
| # Register all nodes | |
| builder.add_node("preprocess_node", preprocess_node) | |
| builder.add_node("serve_cache_node", serve_cache_node) | |
| builder.add_node("transform_node", transform_node) | |
| builder.add_node("retrieve_node", retrieve_node) | |
| builder.add_node("rerank_node", rerank_node) | |
| builder.add_node("crag_node", crag_node) | |
| builder.add_node("assemble_context_node", assemble_context_node) | |
| builder.add_node("generate_node", generate_node) | |
| builder.add_node("critique_node", critique_node) | |
| builder.add_node("guardrail_node", guardrail_node) | |
| builder.add_node("insufficient_node", insufficient_node) | |
| # Entry | |
| builder.add_edge(START, "preprocess_node") | |
| # After preprocess β cache hit or continue | |
| builder.add_conditional_edges( | |
| "preprocess_node", | |
| route_after_preprocess, | |
| { | |
| "serve_cache_node": "serve_cache_node", | |
| "transform_node": "transform_node", | |
| }, | |
| ) | |
| # Cache hit β END | |
| builder.add_edge("serve_cache_node", END) | |
| # Linear path: transform β retrieve β rerank | |
| builder.add_edge("transform_node", "retrieve_node") | |
| builder.add_edge("retrieve_node", "rerank_node") | |
| # After rerank β proceed, CRAG, or insufficient | |
| builder.add_conditional_edges( | |
| "rerank_node", | |
| route_after_rerank, | |
| { | |
| "assemble_context_node": "assemble_context_node", | |
| "crag_node": "crag_node", | |
| "insufficient_node": "insufficient_node", | |
| }, | |
| ) | |
| # CRAG β assemble context | |
| builder.add_edge("crag_node", "assemble_context_node") | |
| # Linear path: assemble β generate β critique | |
| builder.add_edge("assemble_context_node", "generate_node") | |
| builder.add_edge("generate_node", "critique_node") | |
| # After critique β pass, retry, or fail | |
| builder.add_conditional_edges( | |
| "critique_node", | |
| route_after_critique, | |
| { | |
| "guardrail_node": "guardrail_node", | |
| "retrieve_node": "retrieve_node", # Retry cycle | |
| "insufficient_node": "insufficient_node", | |
| }, | |
| ) | |
| # Terminal nodes β END | |
| builder.add_edge("guardrail_node", END) | |
| builder.add_edge("insufficient_node", END) | |
| return builder.compile() | |
| # ββ Singleton graph βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| from functools import lru_cache | |
| def get_smartdocs_graph(): | |
| """ | |
| Singleton compiled graph β built once at startup. | |
| LangGraph compilation validates all nodes and edges. | |
| """ | |
| graph = build_graph() | |
| logger.info("SmartDocs graph compiled and ready") | |
| return graph | |
| # ββ Public API ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| async def run_query( | |
| query: str, | |
| user_id: str, | |
| doc_id: Optional[str] = None, | |
| doc_title: str = "your document", | |
| ) -> dict: | |
| """ | |
| Main entry point for SmartDocs queries. | |
| Runs the complete graph β returns final state. | |
| """ | |
| graph = get_smartdocs_graph() | |
| initial_state: SmartDocsState = { | |
| "query": query, | |
| "user_id": user_id, | |
| "doc_id": doc_id, | |
| "doc_title": doc_title, | |
| "retry_count": 0, | |
| "crag_triggered": False, | |
| "cache_hit": False, | |
| "stream_tokens": [], | |
| "retrieved_chunks": [], | |
| "cited_sources": [], | |
| "active_query": query, | |
| "graph_start_time": time.perf_counter(), | |
| } | |
| # ββ LANGSMITH TRACING INJECTION βββββββββββββββββββββββββββββββββββββββββββ | |
| trace_data = TraceMetadata( | |
| user_id=user_id, | |
| language_code="pending", | |
| query_type="pending", | |
| top_reranker_score=0.0, | |
| crag_triggered=False, | |
| sarvam_model="sarvam-m", | |
| retry_count=0, | |
| cache_hit=False, | |
| total_cost_inr=0.0 | |
| ) | |
| run_config = { | |
| "metadata": build_run_metadata(trace_data), | |
| "tags": ["smartdocs_v1", f"user:{user_id}"] | |
| } | |
| # ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| final_state = await graph.ainvoke(initial_state, config=run_config) | |
| logger.info( | |
| "SmartDocs query complete", | |
| extra={ | |
| "user_id": user_id, | |
| "language": final_state.get("lang_result", {}).language_code | |
| if final_state.get("lang_result") else "unknown", | |
| "cache_hit": final_state.get("cache_hit", False), | |
| "crag_triggered": final_state.get("crag_triggered", False), | |
| "cost_inr": final_state.get("cost", {}).total_inr | |
| if final_state.get("cost") else 0.0, | |
| "latency_ms": final_state.get("total_latency_ms", 0), | |
| }, | |
| ) | |
| return final_state | |
| async def stream_query( | |
| query: str, | |
| user_id: str, | |
| doc_id: Optional[str] = None, | |
| doc_title: str = "your document", | |
| ): | |
| """ | |
| Streaming entry point β yields events for FastAPI SSE. | |
| """ | |
| graph = get_smartdocs_graph() | |
| initial_state: SmartDocsState = { | |
| "query": query, | |
| "user_id": user_id, | |
| "doc_id": doc_id, | |
| "doc_title": doc_title, | |
| "retry_count": 0, | |
| "crag_triggered": False, | |
| "cache_hit": False, | |
| "stream_tokens": [], | |
| "retrieved_chunks": [], | |
| "cited_sources": [], | |
| "active_query": query, | |
| "graph_start_time": time.perf_counter(), | |
| } | |
| # ββ LANGSMITH TRACING INJECTION βββββββββββββββββββββββββββββββββββββββββββ | |
| trace_data = TraceMetadata( | |
| user_id=user_id, | |
| language_code="pending", | |
| query_type="pending", | |
| top_reranker_score=0.0, | |
| crag_triggered=False, | |
| sarvam_model="sarvam-m", | |
| retry_count=0, | |
| cache_hit=False, | |
| total_cost_inr=0.0 | |
| ) | |
| run_config = { | |
| "metadata": build_run_metadata(trace_data), | |
| "tags": ["smartdocs_v1", f"user:{user_id}"] | |
| } | |
| # ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| async for event in graph.astream_events(initial_state, version="v2", config=run_config): | |
| yield event | |
| # ββ LANGGRAPH STUDIO EXPORT βββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| # Expose the compiled graph as a module-level variable for the langgraph-cli. | |
| graph = get_smartdocs_graph() |