HISTORY.md

History

0.2.0 (2025-12-10) - Context Caching & Image Workflows

Major Features

Context Caching System (NEW)

Added intelligent context caching for improved performance:

• New context_utils.py module for smart data reuse across conversation
• get_products_from_context() and get_sales_from_context() retrieve cached data
• update_products_cache() and update_sales_cache() manage cache with metadata
• Filter validation ensures cached data matches requested queries
• Reduces redundant JSON file I/O operations
• Improves response times for follow-up questions

Modified all tools to support context awareness:

• inventory_tools.py - Now checks context cache before loading files
• purchase_order_tools.py - Reuses cached product data when available
• mcp_server.py - ToolExecutor passes conversation state to tools
• Backward compatible: tools work with or without state parameter

Enhanced state management:

• langgraph_manager.py RAG node now populates context["products_cache"]
• Cache includes metadata: source, timestamp, filters applied
• Tool node passes state to ToolExecutor for context-aware execution

Image-Based Product Workflow (NEW)

Added complete image processing workflow:

• New workflow/ module for orchestrating multi-step operations
• ImageProductProcessor class implements end-to-end image workflow:
  1. Vision extraction (GPT-4o Vision product identification)
  2. Catalog search (RAG-based hybrid search)
  3. Inventory checking (automated stock level queries)
  4. Reorder recommendations (low-stock alerts with calculations)
• Confidence thresholds (MIN_CONFIDENCE_THRESHOLD = 0.3)
• Limits results to top 5 matches (MAX_MATCHES_TO_SHOW = 5)
• Comprehensive error handling and logging

Enhanced vision capabilities:

• Added identify_product_from_image() method to azure_openai_client.py
• Specialized product identification with structured JSON output
• Extracts: product_name, category, description, color, keywords, confidence
• Validates required fields before returning results
• Handles JSON parsing from markdown code blocks

Updated chatbot for image processing:

• chatbot.py now uses ImageProductProcessor for image queries
• Automatic workflow execution: vision → search → inventory → response
• Formatted responses with inventory status and recommendations
• Tool call tracking for state management

Test Coverage

Added comprehensive test suites:

• tests/unit/test_context_utils.py - 419 lines, context caching validation
• tests/unit/test_image_processor.py - 467 lines, image workflow tests
• tests/integration/test_tool_context_integration.py - 164 lines, end-to-end integration
• All tests passing across Python 3.10, 3.11, 3.12, 3.13

Architecture Improvements

Benefits of Context Caching:

• ✅ Performance: Reduced file I/O operations (3-5x faster for follow-up queries)
• ✅ Consistency: Tools work with same data user is discussing
• ✅ Efficiency: Reuses RAG-retrieved products without redundant retrieval
• ✅ Backward Compatible: Optional state parameter doesn't break existing code

Benefits of Image Workflow:

• ✅ Multi-Modal Support: Users can upload product images for identification
• ✅ Automated Processing: Complete workflow from image to purchase order
• ✅ Smart Matching: Hybrid search combines vision extraction with RAG retrieval
• ✅ Proactive Alerts: Automatic low-stock detection and reorder suggestions

Data Flow Architecture

Before (0.1.x):

User Query → LLM → Tool Call → Load JSON → Process → Response
User Follow-up → LLM → Tool Call → Load JSON → Process → Response  [redundant load]

After (0.2.0):

User Query → RAG → Cache Products → Tool Call → Use Cache → Response
User Follow-up → Tool Call → Check Cache → Reuse Data → Response  [no reload ✓]

Developer Notes

When adding new tools or modifying existing ones:

• Add optional state: ConversationState | None = None parameter
• Use get_products_from_context() / get_sales_from_context() before loading files
• Call update_products_cache() / update_sales_cache() after fresh loads
• Maintain backward compatibility (state parameter should be optional)

0.1.1 (2025-12-08) - HuggingFace Spaces Deployment & Data Inclusion

HuggingFace Spaces Deployment Fixes

Fixed Docker build error on HuggingFace Spaces (commits 45ae942, bdd0940):

• Removed . package self-installation from requirements.txt that caused "Directory '.' is not installable" error
• Added sys.path manipulation in app.py to make src-layout imports work without formal package installation
• Added [build-system] section to pyproject.toml with hatchling backend
• Updated MANIFEST.in to explicitly include src/chatassistant_retail/

Technical Details: HuggingFace Spaces' auto-generated Dockerfile mounts requirements.txt before copying the repository, preventing standard package installation. The workaround adds the src/ directory to Python's import path at runtime.

Sample Data Files Now Included

Added sample data files to repository (commit 224a842):

• Updated .gitignore to track data/ directory (previously excluded)
• Added products.json (220 KB) - 500+ sample products across 8 categories
• Added sales_history.json (3.6 MB) - 6 months of transaction history
• Added purchase_orders.json (1.3 KB) - Sample purchase orders
• Total size: ~3.7 MB

Rationale: Provides convenient setup for new developers without requiring data generation script execution.

GitHub Actions Workflow Updates

Updated HuggingFace Spaces sync workflow (commits 3e95887, 106d1ac, 7c6b46e):

• Migrated from manual git push to JacobLinCool/huggingface-sync@v1 action
• Added proper checkout step with actions/checkout@v4
• Improved configuration with explicit user/space parameters

UI Module Reorganization

Updated Gradio interface import (commit 6600d9e):

• Changed from direct import to module-based import: gradio_app.create_gradio_interface()
• Improved module organization in chatassistant_retail.ui package

Metrics Dashboard UI Disabled

Temporarily disabled Gradio metrics dashboard UI (commit TBD):

• Commented out metrics dashboard imports in gradio_app.py (lines 15-20)
• Disabled metrics UI components (lines 179-217)
• Removed metrics refresh event handlers (lines 238-242, 258-262)

Backend Status: The observability infrastructure remains fully functional:

• ✅ LangFuse tracing active
• ✅ MetricsCollector class operational
• ✅ @trace decorator working
• ✅ Programmatic metrics access available

Rationale: Streamlined UI to focus on core chat functionality. Metrics remain accessible via LangFuse web dashboard and programmatic API.

Future Plans: Dashboard may be re-enabled in a future release with enhanced features.

0.1.0 (2025-12-05)

• First release on PyPI.