15th Commit Fixed Readme files all the markdown to link between the documentation on GitHub

README.md

@@ -104,7 +104,13 @@ pytest -q
 
 ## Documentation
 
-- [Developer & Build/Test Guide](docs/Developer_Guide_Build_Test.md)
+- [Brief Academic Write Up](docs/Brief_Academic_Write_Up.md)
+- [README](../README.md)
+- [Architecture Overview](docs/architecture.md)  
+- [Design Notes](docs/design.md)  
+- [Implementation Notes](docs/storefront/IMPLEMENTATION.md) 
+- [Dev Doc](docs/DEV_DOC.md)
+- [Developer Guide Build Test](docs/Developer_Guide_Build_Test.md)
 
 ---
 

docs/Brief_Academic_Write_Up.md

@@ -0,0 +1,90 @@
+# Brief Academic Write-Up
+*Agentic-Chat-bot — Design Rationale, Privacy Controls, and Compliance Posture*
+
+## Abstract
+This project implements an **agentic chatbot** with retrieval-augmented generation (RAG), session memory, and provider-agnostic connectors. The system emphasizes **modular architecture**, **resilience via graceful degradation**, and **privacy-by-design**. A key contribution is a **private-data header** mechanism that enforces local-only processing, aggressive redaction, and exclusion from bulk AI inputs, thereby mitigating legal and reputational risks associated with data resale and third-party remarketing (e.g., telemarketers undercutting pricing).
+
+## System Overview
+- **Modularity:** UI (web/Gradio), routing, NLU, memory/RAG, provider adapters, and guardrails are cleanly separated for testability and substitution.
+- **Two Modes:**  
+  - *Anonymous/Local*: offline or local-only inference with strict PII controls.  
+  - *Logged-in/Cloud*: unifies external providers (OpenAI, Azure, HF, etc.) behind a single interface with timeouts and fallbacks.
+- **RAG:** Documents (e.g., storefront policies/FAQs) are chunked and indexed; prompts are grounded to reduce hallucination and maintain domain compliance.
+- **Guardrails & Redaction:** PII/PHI detection and masking precede any external call; logging is minimized and configurable.
+
+## Methods
+1. **Routing & Orchestration:** Requests pass through middleware: authentication, **privacy header detection**, PII/PHI redaction, policy checks, and capability routing (RAG vs. tools vs. LLM).
+2. **Retrieval:** Sparse+dense retrieval with max-passage constraints; citations returned to the UI where applicable.
+3. **Resilience:** Provider failures trigger fallback to local rules or safe canned responses; telemetry excludes sensitive content by default.
+
+## Privacy Header for Customer Data
+We introduce a deployment-standard header:
+```
+X-Private-Customer-Data: strict
+```
+
+**Semantic Policy (enforced in middleware before any provider call):**
+- **Local-Only Processing:** Bypass external providers and long-term storage.
+- **Aggressive Redaction:** Highest PII profile (names, emails, phones, addresses, payment tokens, order details); **no raw payload logging**.
+- **RAG/Analytics Exclusion:** Do **not** index these sessions; **scrub** them from **bulk AI chat input**, training corpora, and aggregate analytics.
+- **Default-Deny Egress:** Block third-party API calls, event streams, or data sharing unless a signed, compliant exception explicitly allows it.
+
+**Business Rationale:**  
+This header materially reduces the risk of allegations of **selling customer data** and helps prevent leakage to data brokers and **telemarketing ecosystems** that could target your customers with **lower online prices**, which erodes trust and revenue.
+
+### Example (FastAPI-style Middleware Sketch)
+```python
+from fastapi import Request, Response
+
+PRIVATE_HEADER = "X-Private-Customer-Data"
+STRICT_VALUE   = "strict"
+
+async def privacy_middleware(request: Request, call_next):
+    private = request.headers.get(PRIVATE_HEADER, "").lower() == STRICT_VALUE
+    request.state.private_mode = private
+
+    if private:
+        request.state.local_only = True
+        request.state.retain_logs = False
+        request.state.rag_exclude = True
+        request.state.redaction_profile = "max"
+
+    response: Response = await call_next(request)
+    return response
+```
+
+## Compliance Considerations (incl. HIPAA/Medical)
+- **HIPAA Readiness (when handling PHI):**
+  - **Minimum Necessary:** Redact and limit exposure to only what is needed for the task.
+  - **No Third-Party Egress Without BAA:** External LLM/provider calls **disabled** unless there is a Business Associate Agreement.
+  - **Logging & Telemetry:** Content logs disabled; operational logs scrubbed; audit logs retained for access and policy decisions.
+  - **Data Lifecycle:** PHI-tagged messages **excluded from RAG indexes** and all analytics/training pipelines; ephemeral session memory with explicit TTLs.
+  - **Encryption & Access:** TLS in transit; encrypted at rest; role-based access; periodic key rotation.
+- **Consumer Data Protection (non-PHI):**
+  - **Do-Not-Sell Policy:** Private header forces a do-not-sell/do-not-share posture for customer data.
+  - **Vendor Risk:** Egress controls prevent uncontracted processors from receiving sensitive customer information.
+  - **Incident Readiness:** Audit trails for provenance; fast revocation paths; breach notification procedures.
+
+> **Note:** This section is a technical summary for engineering rigor and does not constitute legal advice.
+
+## Evaluation & Threat Model (Brief)
+- **Threats:** Data exfiltration (logs, analytics, 3rd-party APIs), prompt injection via retrieved content, ID linkage across sessions, and model inversion via public endpoints.
+- **Mitigations:** Private header hard switch, strict PII redaction, retrieval allow-lists, content-security policies for UI, rate limiting, and anomaly detection on output length/entropy.
+
+## Limitations & Future Work
+- **Granular Policies:** Move from header-only to **policy objects** (per user, per org, per route) managed by an admin console.
+- **Differential Privacy:** Explore noise mechanisms for aggregate analytics that exclude private sessions.
+- **Continuous Redaction Tests:** Unit and fuzz tests for PII/PHI detectors; red-team prompt-injection suites.
+
+## Documentation
+
+- [README](../README.md)
+- [Architecture Overview](architecture.md)  
+- [Design Notes](design.md) 
+- [Developer & Build/Test Guide](Developer_Guide_Build_Test.md) 
+- [Implementation Notes](storefront/IMPLEMENTATION.md) 
+- [Dev Doc](DEV_DOC.md)  
+- [This Document](Brief_Academic_Write_Up.md)
+
+---
+*Prepared for inclusion in the GitHub repository to document academic motivations, privacy mechanisms (private-data header), and compliance posture (including HIPAA considerations) for the Agentic-Chat-bot system.*

docs/DEV_DOC.md

@@ -96,3 +96,12 @@ Key components include:
 - **NLP (Natural Language Processing):** A field of AI focused on enabling computers to understand human language.
 - **Sentiment Analysis:** An NLP technique that determines the emotional tone behind a text.
 
+## Documentation
+
+- [Brief Academic Write Up](docs/Brief_Academic_Write_Up.md)
+- [README](../README.md)
+- [Architecture Overview](architecture.md)  
+- [Design Notes](design.md)  
+- [Implementation Notes](storefront/IMPLEMENTATION.md) 
+- [Dev Doc](DEV_DOC.md)
+- [Developer Guide Build Test](Developer_Guide_Build_Test.md) 

docs/Developer_Guide_Build_Test.md

@@ -118,4 +118,16 @@ curl -X POST http://127.0.0.1:3978/plain-chat -H "Content-Type: application/json
 
 ---
 
+## Documentation
+
+- [Brief Academic Write Up](docs/Brief_Academic_Write_Up.md)
+- [README](../README.md)
+- [Architecture Overview](architecture.md)  
+- [Design Notes](design.md)  
+- [Implementation Notes](storefront/IMPLEMENTATION.md) 
+- [Dev Doc](DEV_DOC.md) 
+- [This Document](Developer_Guide_Build_Test.md) 
+
+---
+
 _Audience: Contributors & Developers_

docs/architecture.md

@@ -71,3 +71,13 @@ This system follows a **modular chatbot architecture** built around a clear flow
 ## Summary
 
 The architecture ensures a **clean separation between interface, logic, and services**, enabling experimentation with different providers while guaranteeing a safe, privacy-friendly anonymous mode. The flowchart illustrates this layered approach: input → logic → NLU/memory → optional AIaaS → guardrails → output.
+
+## Documentation
+
+- [README](../README.md)
+- [Architecture Overview](architecture.md)  
+- [Design Notes](design.md) 
+- [Developer & Build/Test Guide](Developer_Guide_Build_Test.md) 
+- [Implementation Notes](storefront/IMPLEMENTATION.md) 
+- [Dev Doc](DEV_DOC.md)  
+- [Developer Guide Build Test](Developer_Guide_Build_Test.md) 

docs/design.md

@@ -70,3 +70,13 @@ These notes document the reasoning behind major design choices, focusing on **AP
 ## Summary
 
 The design balances **privacy, modularity, and extensibility**. By cleanly separating anonymous and logged-in paths, the system can run entirely offline while still supporting richer AI features when configured. Security and privacy are first-class concerns, and tradeoffs were made to keep the system lightweight, testable, and compliant with project constraints.
+
+## Documentation
+
+- [README](../README.md)
+- [Architecture Overview](architecture.md)  
+- [Design Notes](design.md) 
+- [Developer & Build/Test Guide](Developer_Guide_Build_Test.md) 
+- [Implementation Notes](storefront/IMPLEMENTATION.md) 
+- [Dev Doc](DEV_DOC.md)  
+- [Developer Guide Build Test](Developer_Guide_Build_Test.md)