Polish AI agent portfolio documentation

.env.example

@@ -0,0 +1,13 @@
+OPENAI_API_KEY=
+HF_TOKEN=
+MODEL_MODE=OpenAI
+TOP_K=4
+TEMPERATURE=0.2
+
+# Optional runtime configuration
+OPENAI_MODEL=gpt-4o-mini
+OPENAI_STT_MODEL=gpt-4o-mini-transcribe
+OPENAI_TTS_MODEL=gpt-4o-mini-tts
+OPENAI_TTS_VOICE=alloy
+FINETUNED_MODEL_ID=RakeshMadasani/banking-finance-mistral-qlora
+FINETUNED_ENDPOINT_URL=

.gitignore

@@ -1,7 +1,72 @@
+# Python
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
 .venv/
+venv/
+env/
 **/.venv/
-**/__pycache__/
-*.pyc
+**/venv/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+**/.env
+**/.env.*
+!**/.env.example
+.streamlit/secrets.toml
+**/.streamlit/secrets.toml
+
+# Streamlit and local app state
+.streamlit/
+**/.streamlit/
+*.log
+logs/
+
+# Local model artifacts and generated indexes
+models/
+checkpoints/
+outputs/
+wandb/
+runs/
+mlruns/
+*.safetensors
+*.bin
+*.pt
+*.pth
+*.onnx
+*.gguf
+**/faiss_index/
+**/vectorstore/
+**/*.faiss
+**/*.pkl
+
+# Data artifacts that should not be committed accidentally
+*.parquet
+*.arrow
+*.sqlite
+*.db
+*.duckdb
+
+# OS and editor files
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Large local screenshots; curated tracked screenshots can be force-added if needed
 01-rag-system/screenshots/*.png
 01-rag-system/screenshots/*.jpg
 01-rag-system/screenshots/*.jpeg

01-rag-system/README.md

@@ -1,194 +1,97 @@
-# Autonomous Banking & Finance AI Agent
+# AI Agent Runtime
 
-Banking & Finance Copilot is a grounded AI product for USA and India banking, compliance, and financial intelligence. It combines retrieval over curated banking material with multiple model paths, source-backed answer cards, uploads, multilingual support, and evaluation workflows that are committed in the repo alongside the app itself.
+This folder contains the live deployed Banking & Finance AI Agent runtime. It is still named `01-rag-system` for Hugging Face deployment compatibility, but its role in the system is the agent runtime: Streamlit UI, retrieval, model routing, agentic workflows, uploads, voice controls, source cards, and evaluation.
 
-## Live Product
+## Purpose
 
-[banking-finance-rag on Hugging Face](https://huggingface.co/spaces/RakeshMadasani/banking-finance-rag)
+Provide a product-quality AI workflow interface for banking, compliance, and financial knowledge tasks. The runtime prioritizes grounded answers, clear confidence signals, source visibility, multilingual support, and stable user interaction.
 
-## What This Project Is
-
-This is the product layer of the broader portfolio. The goal was not just to make a banking chatbot answer questions. The goal was to make it behave like a product someone could open, test, trust, and discuss seriously:
-
-- grounded answers instead of free-floating generation
-- visible source support
-- multiple model modes with clear routing behavior
-- uploads for real user documents
-- multilingual interaction
-- reproducible evaluation, not just screenshots
-
-## Where The Code Is
-
-The live Hugging Face Space is only the deployment target. The actual product implementation is committed here in this project:
-
-- [`core`](./core)
-  retrieval orchestration, runtime flow, prompts, and shared utilities
-- [`features`](./features)
-  UI rendering, uploads, read-aloud, answer formatting, and user interaction
-- [`models`](./models)
-  OpenAI mode, Fine-Tuned mode, and Auto routing logic
-
-That is important because I wanted the repo to stand on its own as a real product codebase, not just point outward to a demo URL.
-
-## What The User Can Do
-
-- ask banking, AML, KYC, FDIC, Basel III, RBI, and compliance questions
-- switch between `OpenAI`, `Fine-Tuned`, and `Auto` modes
-- upload PDF, DOCX, TXT, and image files
-- inspect retrieved sources under each answer
-- use read-aloud on the final response
-- test multilingual questions
-
-## Why The Product Is Structured This Way
-
-Trust was the main design constraint. For finance and compliance questions, a polished answer alone is not enough. The product needs to show where the answer came from and make its behavior explainable.
-
-That is why the app is built around:
-
-- shared retrieval before generation
-- source cards and chunk previews
-- model-mode transparency
-- latency and confidence visibility
-- evaluation packs committed in the repository
-
-## Model Modes
-
-### OpenAI
-
-This is the strongest general-purpose answer path and the most stable baseline for live testing.
-
-### Fine-Tuned
-
-This uses the banking-domain Mistral adapter. It is valuable when the hosted path is configured and when lower-latency or domain-style responses are desirable.
-
-### Auto
-
-Auto retrieves once, evaluates candidate answer paths, and selects the winner. That makes the routing logic easier to reason about than a hidden black-box switch.
-
-## Product Architecture
+## Architecture
 
 ```mermaid
-flowchart LR
-    A["Built-in banking knowledge + uploaded docs"] --> B["Chunking and preprocessing"]
-    B --> C["Embeddings"]
-    C --> D["FAISS retrieval"]
-    D --> E["Shared grounded context"]
-    E --> F["OpenAI mode"]
-    E --> G["Fine-Tuned mode"]
-    E --> H["Auto routing"]
-    F --> I["Answer card"]
-    G --> I
-    H --> I
-    I --> J["Sources, confidence, latency, read aloud"]
+flowchart TD
+    A["User input"] --> B["Streamlit product runtime"]
+    B --> C["Upload / voice / text handling"]
+    C --> D["Chunking and embeddings"]
+    D --> E["FAISS dense retrieval"]
+    E --> F["Grounded context"]
+    F --> G["OpenAI mode"]
+    F --> H["Fine-Tuned mode"]
+    F --> I["Auto mode"]
+    F --> J["Agentic / Autonomous modes"]
+    G --> K["Answer renderer"]
+    H --> K
+    I --> K
+    J --> K
+    K --> L["Sources, confidence, latency, actions, read aloud"]
 ```
 
-## How It Works
-
-1. The app loads curated banking knowledge files and any uploaded user documents.
-2. Documents are chunked and embedded.
-3. FAISS retrieves the most relevant context for the question.
-4. The selected model mode answers from that shared context.
-5. The UI renders the answer together with:
-   - mode
-   - latency
-   - chunk count
-   - source cards
-   - confidence label
-
-## Product Walkthrough
-
-### A clean first impression for the product
-
-This is the opening experience of the Banking & Finance Copilot: the stable sidebar, the mode selector, the welcome guidance, and multilingual starter questions that make the product feel usable from the first click.
-
-![Banking Copilot home experience](screenshots/banking-copilot-home-experience.png)
-
-### A grounded English answer that feels concise and useful
-
-This example shows the assistant answering a KYC question in English with a direct explanation, short supporting bullets, visible latency, and a retrieved source card underneath the answer.
-
-![English KYC answer walkthrough](screenshots/english-kyc-answer-walkthrough.png)
-
-### The same product experience working in Telugu
+## Key Files
 
-This screenshot matters because it shows the product doing more than translation. The answer stays structured, readable, and grounded while responding to the question naturally in Telugu.
+| File or folder | Role |
+|---|---|
+| `app.py` | Streamlit entry point used by the live Hugging Face Space. |
+| `core/product_runtime.py` | Main product orchestration, mode selection, retrieval calls, session state, and response handling. |
+| `core/agentic_runtime.py` | Agentic/autonomous workflow implementation and tool-style reasoning layer. |
+| `core/retriever.py` | Shared context retrieval over runtime indexes. |
+| `core/vector_store.py` | FAISS vector store construction. |
+| `features/product_ui.py` | Premium UI cards, sidebar, metrics, and answer rendering. |
+| `features/voice_input.py` / `features/voice_output.py` | Speech-to-text and text-to-speech integration paths. |
+| `models/openai_mode.py` | OpenAI answer path. |
+| `models/finetuned_mode.py` | Fine-tuned model endpoint path. |
+| `models/auto_router.py` | Candidate scoring and automatic model selection. |
+| `evaluation/` | Domain and multilingual evaluation packs, runners, summaries, and reports. |
 
-![Telugu KYC answer walkthrough](screenshots/telugu-kyc-answer-walkthrough.png)
+## How To Run
 
-### Multilingual grounding working in Chinese as well
-
-This example shows the same KYC flow in Chinese, which helps demonstrate that the product experience is consistent across languages rather than being strong only in English.
-
-![Chinese KYC answer walkthrough](screenshots/chinese-kyc-answer-walkthrough.png)
-
-## Evaluation
-
-The [`evaluation`](./evaluation) folder includes two larger committed evaluation packs:
-
-- `evaluation_queries.md`
-  120 domain-specific prompts across OpenAI, Fine-Tuned, and Auto
-- `evaluation_multilingual.md`
-  120 multilingual prompts across the same three modes
-
-Supporting scripts:
-
-- `run_eval_sets.py`
-- `summarize_eval_sets.py`
-
-Latest committed result snapshots live in [`evaluation/results`](./evaluation/results).
-Autonomy audit for current release is tracked in [`../AUTONOMY_EVALUATION.md`](../AUTONOMY_EVALUATION.md).
-
-### Latest committed summaries
-
-| Evaluation set | Total prompts | Available evaluated rows | Average latency | Median latency |
-|---|---:|---:|---:|---:|
-| Domain set | 120 | 80 | 2037.0 ms | 2036.0 ms |
-| Multilingual set | 120 | 80 | 2031.8 ms | 2031.5 ms |
-
-### Reading the snapshot correctly
-
-Those numbers are the committed run snapshot, not a made-up "best case" table:
+```bash
+cd 01-rag-system
+pip install -r requirements.txt
+streamlit run app.py
+```
 
-- each pack contains 120 prompts
-- 80 rows were available in the committed export
-- the missing rows reflect backend availability in that local run, not missing evaluation logic
+Required environment:
 
-I prefer that level of honesty because anyone reviewing the repo can inspect the CSVs and JSON summaries directly and see what was measured versus what was unavailable in that environment.
+```env
+OPENAI_API_KEY=
+HF_TOKEN=
+OPENAI_MODEL=gpt-4o-mini
+FINETUNED_MODEL_ID=RakeshMadasani/banking-finance-mistral-qlora
+```
 
-## Run Locally
+## Inputs And Outputs
 
-### Prerequisites
+Inputs:
 
-- Python 3.10+
-- OpenAI API key
+- User questions in English or supported multilingual prompts.
+- PDF, DOCX, TXT, and image-oriented upload workflows.
+- Voice input where browser/runtime support is available.
+- Mode selection across OpenAI, Fine-Tuned, Auto, Agentic Workspace, and Autonomous Max.
 
-### Install
+Outputs:
 
-```bash
-pip install -r requirements.txt
-```
+- Source-grounded answer cards.
+- Confidence label and latency.
+- Retrieved chunk/source metadata.
+- Copy/export actions and read-aloud audio.
+- Agent trace and audit-style context where agentic modes are used.
 
-### Environment
+## Evaluation Notes
 
-```bash
-OPENAI_API_KEY=your_api_key_here
-OPENAI_MODEL=gpt-4o-mini
-OPENAI_STT_MODEL=gpt-4o-mini-transcribe
-OPENAI_TTS_MODEL=gpt-4o-mini-tts
-OPENAI_TTS_VOICE=alloy
-FINETUNED_MODEL_ID=RakeshMadasani/banking-finance-mistral-qlora
-FINETUNED_ENDPOINT_URL=
-HF_TOKEN=your_hugging_face_token
-```
+The runtime includes:
 
-### Start the app
+- 120 domain prompts in `evaluation/evaluation_queries.md`.
+- 120 multilingual prompts in `evaluation/evaluation_multilingual.md`.
+- Runner and summarizer scripts for repeatable evaluation.
+- Committed snapshots under `evaluation/results`.
+- A generated report under `evaluation/reports/latest_portfolio_report.md`.
+- Decision-critical tests under `tests/`.
 
-```bash
-streamlit run app.py
-```
+Latest committed snapshots show about 2.03s average latency for available rows in both domain and multilingual evaluation exports.
 
-## Notes
+## Limitations
 
-- Fine-Tuned mode becomes fully live when a hosted endpoint is configured. The adapter, routing logic, and evaluation path are in the repo today; the hosted endpoint is the last operational piece for a fully public demo of that mode.
-- Voice input and some upload flows are still environment-sensitive because they depend on browser/runtime behavior.
-- The app is built for groundedness and explainability first, not raw throughput.
+- Current retrieval is FAISS dense vector retrieval. BM25 and reciprocal rank fusion are roadmap work unless implemented later.
+- Fine-Tuned mode requires a configured endpoint or compatible local runtime.
+- Streamlit session state is suitable for live demos but not durable production memory by itself.
+- Outputs are educational and must not be treated as legal, investment, financial, or compliance advice.

02-qa-dataset/README.md

@@ -1,69 +1,87 @@
-# Banking & Finance QA Dataset
+# BankingQA Dataset
 
- This project contains the banking and finance instruction dataset used for downstream fine-tuning.
+This folder contains the BankingQA-3K instruction dataset workflow used by the Banking & Finance AI Agent.
+
+## Purpose
+
+Create a reusable domain dataset for banking and financial compliance instruction tuning. The dataset turns curated banking material into structured instruction-response pairs that support the downstream QLoRA adaptation workflow.
 
 ## Dataset
-[banking-finance-qa-dataset](https://huggingface.co/datasets/RakeshMadasani/banking-finance-qa-dataset)
 
-## Screenshot
-Published dataset page with train and validation splits:
+[banking-finance-qa-dataset](https://huggingface.co/datasets/RakeshMadasani/banking-finance-qa-dataset)
 
 ![Dataset on Hugging Face](screenshots/dataset-hf-splits.png)
 
 ## Summary
-- 3,002 instruction-response pairs
-- 2,701 train samples
-- 301 validation samples
-- Alpaca-style format
-- English language
-- Banking and finance domain
+
+| Item | Value |
+|---|---:|
+| Total examples | 3,002 |
+| Train samples | 2,701 |
+| Validation samples | 301 |
+| Format | Alpaca-style instruction data |
+| Language | English |
+| Domain | Banking, finance, AML, KYC, compliance |
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["Curated banking material"] --> B["Question generation"]
+    B --> C["Instruction / input / output schema"]
+    C --> D["Validation and duplicate checks"]
+    D --> E["Train / validation split"]
+    E --> F["Hugging Face Dataset"]
+```
 
 ## Coverage
-- AML / KYC
-- CDD / EDD
-- FDIC
-- Basel III
-- RBI
-- SAR / CTR
-- compliance topics
-- finance fundamentals
-
-## What it demonstrates
-- domain data curation
-- instruction dataset creation
-- validation and split design
-- Hugging Face dataset publishing
-
-## Data Methodology
-
-The dataset was built by turning curated banking and compliance material into instruction-style examples intended for downstream fine-tuning. The focus was not just on volume, but on having a usable spread of topics, clean formatting, and a validation pass before publishing.
-
-In practice, that meant:
-
-- selecting questions that map naturally to banking, compliance, and regulatory supervision
-- structuring examples in Alpaca-style `instruction`, `input`, and `output` fields
-- validating the finished dataset for structural consistency and duplicate issues before upload
-
-## Example Schema
-
-```json
-{
-  "instruction": "What is the FDIC deposit insurance limit in the United States?",
-  "input": "",
-  "output": "The FDIC insures deposits up to $250,000 per depositor, per insured bank, per account ownership category."
-}
+
+- AML, KYC, CDD, and EDD.
+- FDIC deposit insurance.
+- Basel III capital concepts.
+- RBI and India banking compliance topics.
+- SAR, CTR, transaction monitoring, and financial crime concepts.
+- General banking and finance fundamentals.
+
+## Key Files
+
+| File | Role |
+|---|---|
+| `generate_dataset.py` | Builds instruction-response examples from curated material. |
+| `validate_dataset.py` | Checks structure, duplicates, and dataset quality signals. |
+| `upload_to_hf.py` | Publishes dataset artifacts and dataset card to Hugging Face. |
+| `screenshots/` | Published dataset page screenshots for portfolio review. |
+
+## How To Run
+
+```bash
+cd 02-qa-dataset
+python generate_dataset.py
+python validate_dataset.py
+python upload_to_hf.py
 ```
 
-## Code Entry Points
-- `generate_dataset.py` - builds banking instruction-response pairs from curated source material
-- `validate_dataset.py` - runs duplicate and structural checks on the generated dataset
-- `upload_to_hf.py` - publishes the dataset and dataset card to Hugging Face
+Set `HF_TOKEN` before upload if publishing to the Hub.
+
+## Inputs And Outputs
+
+Inputs:
+
+- Curated banking and compliance source material.
+- Topic coverage plan across AML, KYC, FDIC, RBI, Basel III, and banking operations.
+
+Outputs:
+
+- Alpaca-style dataset with `instruction`, `input`, and `output` fields.
+- Train and validation splits.
+- Hugging Face dataset repository.
+
+## Evaluation Notes
 
-## Why it stands out
-This project turns raw banking and compliance material into a reusable ML asset rather than stopping at prompt experimentation. It shows the data layer behind the model and application work in the rest of the portfolio.
+The dataset is validated structurally before publishing. It is designed for fine-tuning and domain adaptation, not as a formal legal or regulatory authority. Downstream quality should be measured through model evaluation and grounded answer testing.
 
 ## Limitations
 
-- instruction-style datasets can still inherit phrasing bias from the source material used to create them
-- U.S. and India banking topics are useful together, but not always perfectly balanced in representation
-- the dataset is a strong domain adaptation asset, but it should not be treated as formal regulatory ground truth
+- The dataset is English-only in its current published form.
+- Coverage is strongest for banking/compliance concepts represented in the curated material.
+- Dataset answers should be treated as training material, not official regulatory advice.

03-qlora-finetuning/README.md

@@ -1,79 +1,83 @@
-# Banking Finance QLoRA Fine-Tuned Model
+# Domain Model Adaptation
 
-This project contains the fine-tuning workflow for adapting a Mistral-based LLM to banking and finance question answering.
+This folder contains the QLoRA fine-tuning workflow used to adapt Mistral-7B-Instruct-v0.3 to banking and financial compliance terminology.
+
+## Purpose
+
+Show the model adaptation layer behind the Banking & Finance AI Agent. The goal is not only to call external APIs, but to demonstrate data preparation, parameter-efficient fine-tuning, adapter publishing, and inference testing.
 
 ## Model
+
 [banking-finance-mistral-qlora](https://huggingface.co/RakeshMadasani/banking-finance-mistral-qlora)
 
-## Published Model Page
 ![Published QLoRA model page](screenshots/model-page-demo.png)
 
-## Recommended Demo Questions
+## Architecture
 
-If you want to capture a stronger inference screenshot for this project, use these questions:
+```mermaid
+flowchart LR
+    A["BankingQA-3K dataset"] --> B["Prompt formatting"]
+    B --> C["Mistral-7B-Instruct-v0.3"]
+    C --> D["4-bit NF4 quantization"]
+    D --> E["LoRA adapter training"]
+    E --> F["Validation / training metrics"]
+    F --> G["Published Hugging Face adapter"]
+```
 
-- `What is the FDIC deposit insurance limit in the United States?`
-- `What are the three stages of money laundering?`
-- `What is the difference between AML and KYC?`
-
-These prompts are short, easy to judge, and representative of the banking/compliance domain adaptation shown by the model.
+## Fine-Tuning Summary
 
-## Base Model
-`mistralai/Mistral-7B-Instruct-v0.3`
+| Item | Value |
+|---|---|
+| Base model | `mistralai/Mistral-7B-Instruct-v0.3` |
+| Method | QLoRA |
+| Quantization | 4-bit NF4 |
+| LoRA rank | 16 |
+| LoRA alpha | 32 |
+| LoRA dropout | 0.05 |
+| Training samples | 2,701 |
+| Validation samples | 301 |
+| Global steps | 676 |
+| Final train loss | 1.13 |
 
-## Fine-Tuning Summary
-- Method: QLoRA
-- Quantization: 4-bit NF4
-- LoRA rank: 16
-- LoRA alpha: 32
-- LoRA dropout: 0.05
-- Training samples: 2,701
-- Validation samples: 301
-- Global steps: 676
-- Final train loss: 1.13
+## Key Files
 
-## Training Environment
+| File | Role |
+|---|---|
+| `Banking_QLoRA_Mistral7B_updated.ipynb` | Main notebook for dataset formatting, QLoRA setup, training, and publishing. |
+| `inference_demo.py` | Lightweight script for loading the adapter and testing domain prompts. |
+| `screenshots/` | Published model page and training-progress screenshots. |
 
-- notebook-based QLoRA workflow
-- designed for practical notebook GPU usage rather than full distributed training
-- built around an adapter approach so a 7B model could be adapted without full fine-tuning
+## How To Run
 
-## Code Entry Points
-- `Banking_QLoRA_Mistral7B_updated.ipynb` - main notebook used for the QLoRA workflow
-- `inference_demo.py` - lightweight inference script for loading the published adapter and testing example prompts
+The notebook is the main training artifact. For local inference, use:
 
-## Why QLoRA
+```bash
+cd 03-qlora-finetuning
+python inference_demo.py
+```
 
-- **4-bit NF4 quantization:** reduces memory usage enough to make 7B-scale fine-tuning practical in notebook GPU environments
-- **LoRA adapters:** updates a small trainable parameter set instead of full-model weights
-- **Cost-efficient experimentation:** a good fit for domain adaptation when full fine-tuning is too heavy
+You need access to the base model, the published adapter, and a compatible local GPU/CPU environment. Full 7B inference can be heavy on consumer machines.
 
-## What it demonstrates
-- parameter-efficient fine-tuning
-- PEFT/LoRA configuration
-- domain adaptation using custom data
-- Hugging Face model publishing
+## Inputs And Outputs
 
-## Output Snapshot
+Inputs:
 
-Example sample outputs from the fine-tuned model included banking-domain answers for prompts such as:
-- FDIC deposit insurance limits
-- the stages of money laundering
-- Basel-related banking questions
+- BankingQA-3K instruction dataset.
+- Mistral-7B-Instruct-v0.3 base model.
+- PEFT/QLoRA configuration.
 
-These examples showed that the adapter was capable of producing domain-specific responses after fine-tuning, even though formal benchmark scoring is still a planned improvement.
+Outputs:
 
-## Before vs After Snapshot
+- Published LoRA adapter.
+- Training metrics.
+- Model card and inference demo path.
 
-| Prompt type | Base model tendency | Fine-tuned model tendency |
-|---|---|---|
-| Banking definitions | usually reasonable but generic | more direct banking-specific phrasing |
-| Compliance language | broad but sometimes high-level | more targeted AML / KYC / SAR / CTR terminology |
-| India-focused regulation | can be vague or mix jurisdictions | better alignment with RBI-oriented wording from the custom dataset |
+## Evaluation Notes
 
-## Why it stands out
-This project shows that the portfolio goes beyond app development and dataset creation into actual model adaptation. Publishing the adapter with a model card, tokenizer files, and LoRA configuration makes the work visible and inspectable as a real model artifact.
+The current folder documents training configuration and final train loss. A stronger future benchmark should compare the base model, adapter model, OpenAI path, and Auto routing on the same held-out banking evaluation pack.
 
-## Limitation to state clearly
+## Limitations
 
-This repository publishes a QLoRA adapter artifact, not a fully hosted standalone inference service by itself. To run it end to end, the adapter still needs to be loaded with the compatible base model in a suitable inference environment.
+- This publishes an adapter artifact, not a fully hosted standalone inference service.
+- Runtime quality depends on loading the compatible base model plus adapter correctly.
+- The model should be evaluated on held-out prompts before making strong accuracy claims.

04-conversational-memory/README.md

@@ -1,139 +1,51 @@
-# Conversational Memory Backend
+# Memory And Orchestration Backend
 
-This project adds a FastAPI-based conversational layer on top of the banking RAG assistant so interactions become session-aware instead of stateless. It introduces session memory, controlled history retention, and summarization for longer conversations while keeping the underlying retrieval-backed banking Q&A workflow reusable. The backend supports both an OpenAI path for quick deployment and a local Hugging Face adapter path for a stronger end-to-end portfolio story.
+This folder contains a FastAPI conversational memory backend for the Banking & Finance AI Agent. It adds session handling, controlled history retention, summarization, and backend comparison around the same banking knowledge workflow.
 
-## What this project does
+## Purpose
 
-- wraps the existing banking RAG logic behind a FastAPI service
-- maintains per-session conversation history for multi-turn follow-up questions
-- truncates and summarizes long sessions to control prompt growth
-- exposes clean API endpoints for chat, session clearing, and health checks
-- supports switchable LLM backends via environment variable
-- supports side-by-side backend comparison on the same retrieved context
-- supports evaluation of memory-on vs memory-off coherence
+Move the system beyond stateless single-turn answers by introducing reusable API endpoints and memory-aware orchestration. This layer is separate from the live Streamlit Space so it can evolve toward production API deployment without destabilizing the public demo.
 
 ## Architecture
 
 ```mermaid
 flowchart LR
-    A["Client / frontend"] --> B["POST /chat"]
-    A --> B2["POST /chat/compare"]
-    B --> C["Session memory store"]
-    B2 --> C
-    C --> D["Truncation or summarization"]
-    D --> E["Retriever + shared banking knowledge base"]
-    E --> F["Shared retrieved context"]
-    F --> G["Single backend path"]
-    F --> H["OpenAI backend"]
-    F --> I["Local HF adapter backend"]
-    G --> J["Single response"]
-    H --> K["OpenAI answer"]
-    I --> L["HF answer"]
-    K --> M["Side-by-side comparison output"]
-    L --> M
-
-    N["DELETE /session/{session_id}"] --> C
-    O["GET /health"] --> B
+    A["Client or frontend"] --> B["POST /chat"]
+    A --> C["POST /chat/compare"]
+    B --> D["Session memory store"]
+    C --> D
+    D --> E["History truncation / summarization"]
+    E --> F["Shared banking retrieval"]
+    F --> G["OpenAI backend"]
+    F --> H["Local HF adapter backend"]
+    G --> I["Response"]
+    H --> J["Comparison response"]
+    K["DELETE /session/{id}"] --> D
+    L["GET /health"] --> B
 ```
 
-## Project Structure
-
-```text
-04-conversational-memory/
-|-- app/
-|   |-- __init__.py
-|   |-- main.py
-|   |-- memory.py
-|   |-- models.py
-|   |-- rag_chain.py
-|   `-- summarizer.py
-|-- evaluation/
-|   |-- coherence_eval.py
-|   `-- questions.csv
-|-- tests/
-|   `-- test_memory.py
-|-- .env.example
-|-- README.md
-`-- requirements.txt
-```
-
-## API Endpoints
-
-### `POST /chat`
-Accepts a user message plus an optional `session_id` and returns:
-
-- `session_id`
-- `response`
-- `turn_count`
-- `sources`
-- `confidence`
-- `history_used`
-- `summary_used`
-
-### `DELETE /session/{session_id}`
-Clears the stored memory for a given session.
-
-### `GET /health`
-Returns a lightweight health status and current session count.
-
-### `POST /chat/compare`
-Runs both backends on the same question and retrieved context, then returns both answers side by side for direct comparison.
+## Key Files
 
-## How to run
+| File | Role |
+|---|---|
+| `app/main.py` | FastAPI application and route definitions. |
+| `app/memory.py` | Session memory store and state handling. |
+| `app/rag_chain.py` | Retrieval and backend generation logic. |
+| `app/summarizer.py` | Conversation summarization support. |
+| `app/models.py` | Request and response models. |
+| `evaluation/coherence_eval.py` | Memory-on versus memory-off coherence evaluation. |
+| `tests/test_memory.py` | Unit tests for memory behavior. |
 
-### Prerequisites
-
-- Python 3.10+
-- banking knowledge files available in `01-rag-system/`
-- one backend configured:
-  - `openai` with `OPENAI_API_KEY`
-  - `local_hf` with model + adapter access and enough local GPU/compute
-
-### Install
+## How To Run
 
 ```bash
+cd 04-conversational-memory
 pip install -r requirements.txt
-```
-
-### Environment
-
-```bash
-LLM_BACKEND=openai
-OPENAI_API_KEY=your_openai_api_key_here
-OPENAI_MODEL=gpt-4o-mini
-LOCAL_HF_MODEL_ID=mistralai/Mistral-7B-Instruct-v0.3
-LOCAL_HF_ADAPTER_ID=RakeshMadasani/banking-finance-mistral-qlora
-LOCAL_HF_DEVICE=auto
-```
-
-### Backend options
-
-#### Option A - OpenAI backend
-
-```bash
-LLM_BACKEND=openai
-OPENAI_API_KEY=your_openai_api_key_here
-OPENAI_MODEL=gpt-4o-mini
-```
-
-#### Option B - Local HF backend
-
-```bash
-LLM_BACKEND=local_hf
-LOCAL_HF_MODEL_ID=mistralai/Mistral-7B-Instruct-v0.3
-LOCAL_HF_ADAPTER_ID=RakeshMadasani/banking-finance-mistral-qlora
-LOCAL_HF_DEVICE=auto
-```
-
-This path is stronger for the portfolio because it links Project 3 directly into Project 4, but it also requires a compatible local environment and enough compute to load the base model plus adapter.
-
-### Run the API
-
-```bash
+copy .env.example .env
 uvicorn app.main:app --reload --port 8000
 ```
 
-### Example request
+Example:
 
 ```bash
 curl -X POST "http://127.0.0.1:8000/chat" ^
@@ -141,88 +53,29 @@ curl -X POST "http://127.0.0.1:8000/chat" ^
   -d "{\"message\":\"What is KYC?\",\"session_id\":\"demo-session\",\"use_memory\":true}"
 ```
 
-### Example comparison request
-
-```bash
-curl -X POST "http://127.0.0.1:8000/chat/compare" ^
-  -H "Content-Type: application/json" ^
-  -d "{\"message\":\"What is the difference between AML and KYC?\",\"session_id\":\"compare-session\",\"use_memory\":true}"
-```
-
-## Evaluation
-
-The `evaluation/coherence_eval.py` script compares memory-off and memory-on responses on multi-turn conversations such as:
-
-- KYC followed by follow-up questions about its components and its relation to AML
-- Basel III followed by capital requirement and Basel II comparison prompts
-- SAR followed by reporting-threshold clarification
-
-Run:
-
-```bash
-python evaluation/coherence_eval.py
-```
-
-This prints:
-
-- average coherence score with memory off
-- average coherence score with memory on
-- relative improvement
-
-Use the resulting percentage as evidence for a claim like `17% improvement` only when your real run produces that number.
-
-## Execution Proof
-
-This project has already been exercised locally at a lightweight level:
-
-- `/health` returned a successful status response
-- `/chat` returned a real answer
-- a follow-up `/chat` call on the same session showed `history_used = true`
-- `/chat/compare` is implemented and reachable, with the local HF runtime path dependent on the local model environment
-
-For the current execution record, see [`evaluation/results.md`](./evaluation/results.md).
-
-## Design Decisions
-
-### Why truncation + summarization instead of only windowing?
-
-- simple windowing drops older context entirely
-- summarization preserves earlier intent and constraints
-- retaining the most recent turns keeps the API responsive for active follow-ups
-- current session store is in-process for demo simplicity; a production upgrade path would be Redis or Postgres
-
-### Why reuse the Project 1 knowledge base?
-
-- keeps the backend directly tied to your deployed banking RAG system
-- strengthens the portfolio story across app layer and backend layer
-- makes evaluation easier because the data and retrieval domain stay consistent
-
-### Why support switchable backends?
-
-- OpenAI is the fastest path to ship and demo the architecture
-- a local HF backend creates a stronger data -> model -> backend portfolio chain
-- the same FastAPI layer can serve both paths without changing the API contract
+## Inputs And Outputs
 
-### Why add `/chat/compare`?
+Inputs:
 
-- it makes backend tradeoffs visible instead of hidden behind a config switch
-- it lets you compare a general-purpose model and a domain-adapted model on the same retrieved evidence
-- it creates a stronger portfolio talking point than a simple backend toggle
+- User message.
+- Optional `session_id`.
+- Optional memory usage flag.
+- Backend configuration via environment variables.
 
-## What this adds to the portfolio
+Outputs:
 
-This project upgrades the overall portfolio from a collection of artifacts into a more production-oriented system story:
+- Session-aware answer.
+- Sources and confidence.
+- Turn count.
+- Flags showing whether history or summary was used.
+- Side-by-side backend comparison through `/chat/compare`.
 
-- Project 1 provides the deployed RAG interface
-- Project 2 provides the banking instruction dataset
-- Project 3 provides the fine-tuned model artifact
-- Project 4 adds the backend memory and orchestration layer for multi-turn interaction
+## Evaluation Notes
 
-## Execution Notes
+The coherence evaluation compares memory-off and memory-on behavior across follow-up conversations. Claims such as percentage improvement should only be made from actual generated evaluation output, not assumed values.
 
-See [`evaluation/results.md`](./evaluation/results.md) for a lightweight execution record covering:
+## Limitations
 
-- successful local `/health` response
-- successful local `/chat` response
-- successful memory follow-up showing `history_used = true`
-- the current state of `/chat/compare` validation
+- The current memory store is lightweight and in-process; production use should move to Redis, Postgres, or another durable store.
+- Local Hugging Face adapter inference depends on a compatible environment and sufficient compute.
+- This backend is a system-design layer and is not the live public Space entry point.

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+Thanks for improving the Banking & Finance AI Agent. This repository is maintained as a serious AI engineering portfolio, so changes should be small, testable, and honest about what the code supports.
+
+## Setup
+
+```bash
+git clone https://github.com/rakeshmadasaniai/banking-genai-portfolio.git
+cd banking-genai-portfolio
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -r 01-rag-system/requirements.txt
+```
+
+Copy the sample environment file and fill local secrets:
+
+```bash
+copy .env.example .env
+```
+
+Never commit real API keys or tokens.
+
+## Branching
+
+- Use short descriptive branches.
+- Prefer `feature/...`, `fix/...`, or `docs/...`.
+- Keep deployment-risky changes separate from documentation-only changes.
+
+## Testing
+
+Run the available unit tests:
+
+```bash
+cd 01-rag-system
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+When changing evaluation logic, also run the relevant scripts under `01-rag-system/evaluation`.
+
+## Pull Request Expectations
+
+Each PR should include:
+
+- What changed.
+- Why it changed.
+- How it was tested.
+- Any limitations or follow-up work.
+
+For AI behavior changes, include at least one before/after example and avoid unsupported accuracy claims.
+
+## Code Style
+
+- Keep Python readable and typed where practical.
+- Prefer small functions over large hidden control flow.
+- Add comments only where the logic is non-obvious.
+- Preserve existing UI design language unless the change is explicitly a redesign.
+
+## Documentation Style
+
+- Use "AI agent", "grounded GenAI system", or "tool-calling AI system" when accurate.
+- Avoid "AGI" or "fully autonomous" unless the implementation and evaluation clearly support that exact claim.
+- Keep metrics tied to committed evaluation files.

EVALUATION.md

@@ -0,0 +1,77 @@
+# Evaluation
+
+This document describes how the Banking & Finance AI Agent is evaluated and what should be improved next.
+
+## Goals
+
+- Measure whether answers are grounded in retrieved banking context.
+- Measure latency for product responsiveness.
+- Compare OpenAI, Fine-Tuned, Auto, and agentic paths where configured.
+- Test multilingual behavior rather than assuming English-only quality.
+- Capture failure modes openly so improvements are traceable.
+
+## Evaluation Assets
+
+| Asset | Location | Purpose |
+|---|---|---|
+| Domain query pack | `01-rag-system/evaluation/evaluation_queries.md` | Banking, AML, KYC, FDIC, RBI, Basel III, payments, and compliance prompts. |
+| Multilingual query pack | `01-rag-system/evaluation/evaluation_multilingual.md` | Multilingual coverage across model modes. |
+| Runner | `01-rag-system/evaluation/run_eval_sets.py` | Executes evaluation packs. |
+| Summarizer | `01-rag-system/evaluation/summarize_eval_sets.py` | Produces CSV/JSON summaries. |
+| Results | `01-rag-system/evaluation/results/` | Committed result snapshots. |
+| Portfolio report | `01-rag-system/evaluation/reports/latest_portfolio_report.md` | Recruiter-friendly summary generated from committed artifacts. |
+| Autonomy audit | `AUTONOMY_EVALUATION.md` | Honest status of the agentic/autonomous runtime. |
+
+## Current Snapshot
+
+| Evaluation set | Total prompts | Available evaluated rows | Average latency | Median latency |
+|---|---:|---:|---:|---:|
+| Domain pack | 120 | 80 | 2037.0 ms | 2036.0 ms |
+| Multilingual pack | 120 | 80 | 2031.8 ms | 2031.5 ms |
+
+The committed export includes unavailable rows where the relevant backend was not active in the local evaluation environment. This is preserved intentionally so the results stay auditable.
+
+## Prompt Categories
+
+- Banking definitions and explainers.
+- AML/KYC/CDD/EDD compliance.
+- FDIC deposit insurance.
+- RBI and India banking compliance.
+- Basel III capital and risk concepts.
+- Payments and transaction-monitoring scenarios.
+- Cross-jurisdiction comparison prompts.
+- Multilingual banking questions.
+- Agentic decision scenarios such as fraud, sanctions, short-horizon investing, and life-event planning.
+
+## Groundedness Scoring
+
+The runtime uses scoring utilities to estimate:
+
+- overlap with retrieved documents,
+- completeness of the answer,
+- latency quality,
+- combined candidate score for routing.
+
+These scores are useful product signals, not formal legal or regulatory validation.
+
+## Latency Measurement
+
+Latency is recorded in milliseconds in model results and evaluation outputs. Current committed snapshot averages are around 2.03 seconds for available rows. Future reports should add p50, p95, p99, and per-mode latency.
+
+## Failure Modes To Track
+
+- Retrieval misses for narrow regulatory facts.
+- Answers that ask for clarification when enough information already exists.
+- Overly generic policy-generation responses.
+- Cross-jurisdiction questions that need explicit table formatting.
+- Voice and upload behavior that depends on browser/runtime permissions.
+- Fine-Tuned mode availability when the hosted endpoint is not configured.
+
+## Future Benchmark Plan
+
+- Add a gold-answer set for 100 high-value banking and compliance questions.
+- Add multilingual human review for at least five languages.
+- Add separate benchmarks for retrieval-only, OpenAI, Fine-Tuned, Auto, and agentic modes.
+- Add document-upload tests for PDF, DOCX, TXT, and image inputs.
+- Add voice input/output smoke tests where runtime support is available.
+- Track before/after scores for BM25/RRF once sparse retrieval is implemented.

README.md

@@ -1,5 +1,5 @@
 ---
-title: Autonomous Banking & Finance AI Agent
+title: Banking & Finance AI Agent
 emoji: 🌎
 colorFrom: blue
 colorTo: indigo
@@ -10,290 +10,185 @@ app_file: 01-rag-system/app.py
 pinned: false
 ---
 
-# Autonomous Banking & Finance AI Agent Portfolio
+# Banking & Finance AI Agent
 
-**Rakesh Madasani**  
-[Live Autonomous Banking & Finance AI Agent](https://huggingface.co/spaces/RakeshMadasani/banking-finance-rag) | [Hugging Face Profile](https://huggingface.co/RakeshMadasani) | [GitHub](https://github.com/rakeshmadasaniai/banking-genai-portfolio) | [LinkedIn](https://www.linkedin.com/in/rakesh-madasani-b217b71b0/)
+![Python](https://img.shields.io/badge/Python-3.10-blue)
+![Hugging Face Spaces](https://img.shields.io/badge/Hugging%20Face-Spaces-yellow)
+![Streamlit](https://img.shields.io/badge/Streamlit-1.56-red)
+![FastAPI](https://img.shields.io/badge/FastAPI-memory%20backend-009688)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Status](https://img.shields.io/badge/Status-Active-brightgreen)
 
-This repository is the full build story behind my Banking & Finance Copilot: a live grounded AI product focused on USA and India banking, compliance, AML, KYC, FDIC, Basel III, and RBI workflows.
+**Production-grade GenAI system for grounded banking, compliance, and financial knowledge workflows.**
 
-I did not want this to be a one-screen chatbot demo. I wanted it to behave like a real product:
+I built this system to answer one question: what does it take to move a GenAI product beyond a chatbot demo and into a reliable, measurable AI system?
 
-- grounded on visible source material
-- measurable with repeatable evaluation packs
-- flexible across OpenAI, Fine-Tuned, and Auto routing
-- multilingual enough for broader banking users
-- strong enough to discuss as an engineering system, not just a UI
+The result is a live Banking & Finance AI Agent with retrieval, model routing, domain adaptation, conversational memory work, evaluation packs, multilingual UX, upload workflows, voice support, and an autonomy audit. It is intentionally positioned as an AI agent and grounded GenAI platform, not AGI and not an overclaimed fully autonomous production system.
 
-## World-Class Execution Plan
+## Live Links
 
-I maintain a concrete week-by-week delivery plan in:
-
-- [`WORLDCLASS_WEEK1_TO_WEEK6.md`](WORLDCLASS_WEEK1_TO_WEEK6.md)
-- [`AUTONOMY_EVALUATION.md`](AUTONOMY_EVALUATION.md)
-
-This is the operating plan used to move the project from strong prototype quality to production-grade architecture, reliability, governance, and distribution.
-
-## Live Product
-
-- **Live app:** [banking-finance-rag](https://huggingface.co/spaces/RakeshMadasani/banking-finance-rag)
-- **Dataset:** [banking-finance-qa-dataset](https://huggingface.co/datasets/RakeshMadasani/banking-finance-qa-dataset)
-- **Fine-tuned model:** [banking-finance-mistral-qlora](https://huggingface.co/RakeshMadasani/banking-finance-mistral-qlora)
-
-## What This Repo Shows
-
-| Layer | What is in the repo | Why it matters |
-|---|---|---|
-| Product | A live Banking & Finance Copilot | Shows a shipped, testable AI product |
-| Retrieval | FAISS + banking knowledge + source cards | Keeps answers grounded and explainable |
-| Data | A domain-specific QA dataset | Shows data ownership, not just prompting |
-| Model | QLoRA fine-tuning workflow | Shows model adaptation beyond API usage |
-| Backend | Conversational memory API | Shows system thinking and architecture depth |
-| Evaluation | 120-query domain set + 120-query multilingual set | Shows repeatable measurement, not anecdotal demos |
-
-## Where The Product Code Lives
-
-If someone lands on this repo from GitHub first, the main product code is not hidden in a separate private service. It lives directly inside [`01-rag-system`](01-rag-system):
-
-- [`01-rag-system/core`](01-rag-system/core)
-  runtime orchestration, retrieval flow, prompts, and shared utilities
-- [`01-rag-system/features`](01-rag-system/features)
-  product UI, uploads, voice output, answer cards, and interaction behavior
-- [`01-rag-system/models`](01-rag-system/models)
-  OpenAI mode, Fine-Tuned mode, and Auto routing logic
-
-That structure matters because I wanted the repo to read like a real product codebase, not a single README pointing to an external demo.
-
-## How The Portfolio Evolves
-
-This repo is one system built in layers.
-
-### 1. Product layer
-
-I started with the user-facing assistant in [`01-rag-system`](01-rag-system). The goal was simple: if someone asks a banking or compliance question, the product should answer clearly and show the evidence behind the answer.
-
-### 2. Data layer
-
-Once the first retrieval system worked, I created a banking QA dataset in [`02-qa-dataset`](02-qa-dataset) so the domain logic would not live only inside prompts and chunk text.
-
-### 3. Model layer
-
-Then I fine-tuned a banking-domain adapter in [`03-qlora-finetuning`](03-qlora-finetuning) to show that I can move from application wiring into actual model adaptation.
-
-### 4. Backend layer
-
-Finally, I added session memory and orchestration work in [`04-conversational-memory`](04-conversational-memory), which made the portfolio feel more like a real product system than a single-page demo.
-
-## Architecture
+| Asset | Link |
+|---|---|
+| Live app | [Hugging Face Space](https://huggingface.co/spaces/RakeshMadasani/banking-finance-rag) |
+| GitHub repository | [banking-genai-portfolio](https://github.com/rakeshmadasaniai/banking-genai-portfolio) |
+| Fine-tuned model | [banking-finance-mistral-qlora](https://huggingface.co/RakeshMadasani/banking-finance-mistral-qlora) |
+| Dataset | [banking-finance-qa-dataset](https://huggingface.co/datasets/RakeshMadasani/banking-finance-qa-dataset) |
 
-### End-to-End System
+## What This System Does
 
-```mermaid
-flowchart LR
-    A["Curated banking knowledge"] --> B["Chunking and preprocessing"]
-    B --> C["Embeddings"]
-    C --> D["FAISS index"]
-    D --> E["Shared grounded context"]
-
-    A --> F["Instruction dataset generation"]
-    F --> G["Banking QA dataset"]
-    G --> H["QLoRA fine-tuning"]
-    H --> I["Published banking adapter"]
-
-    E --> J["OpenAI path"]
-    E --> K["Fine-Tuned path"]
-    E --> L["Auto routing"]
-
-    J --> M["Live Banking & Finance Copilot"]
-    K --> M
-    L --> M
-
-    M --> N["Sources, confidence, latency, uploads, read aloud"]
-    M --> O["Conversational memory backend"]
-```
+- Answers banking, finance, AML, KYC, FDIC, Basel III, RBI, and compliance questions with retrieved context.
+- Supports OpenAI, Fine-Tuned, Auto, Agentic Workspace, and Autonomous Max paths where configured.
+- Renders source-grounded answer cards with latency, confidence, retrieved chunks, source cards, copy/export actions, and read-aloud controls.
+- Accepts text, document uploads, image-supported workflows, multilingual prompts, and voice input/output paths.
+- Includes a published BankingQA-3K dataset and a QLoRA Mistral-7B adapter for domain model adaptation.
+- Ships repeatable evaluation packs, committed result snapshots, and an autonomy evaluation note instead of only screenshots.
 
-### Live Product Runtime
+## Architecture Overview
 
 ```mermaid
 flowchart TD
-    U["Question or uploaded document"] --> R["Shared retrieval"]
-    R --> C["Grounded context"]
-    C --> O["OpenAI mode"]
-    C --> F["Fine-Tuned mode"]
-    C --> A["Auto mode"]
-
-    A --> S["Selection logic"]
-    O --> X["Answer card"]
-    F --> X
-    S --> X
-
-    X --> Y["Latency, confidence, sources, read aloud"]
+    U["User input: text, document, image, or voice"] --> IR["Input router"]
+    IR --> UP["Upload and document parsing"]
+    IR --> VI["Voice input path"]
+    IR --> Q["Normalized user query"]
+
+    UP --> KB["Runtime knowledge context"]
+    Q --> RC["Retrieval coordinator"]
+    KB --> RC
+
+    RC --> FAISS["Implemented: FAISS dense vector search"]
+    RC -. "roadmap" .-> BM25["Planned: BM25 sparse search"]
+    BM25 -. "roadmap" .-> RRF["Planned: reciprocal rank fusion"]
+    FAISS --> GC["Grounded context"]
+    RRF -. "future hybrid context" .-> GC
+
+    GC --> ORCH["LLM orchestration layer"]
+    ORCH --> OAI["OpenAI mode"]
+    ORCH --> FT["Fine-Tuned mode"]
+    ORCH --> AUTO["Auto routing"]
+    ORCH --> AGENT["Agentic / Autonomous modes"]
+
+    OAI --> EVAL["Evaluation + confidence scoring"]
+    FT --> EVAL
+    AUTO --> EVAL
+    AGENT --> EVAL
+
+    EVAL --> RESP["Response with sources, confidence, latency, and actions"]
+    RESP --> MEM["Session memory and audit context"]
+    MEM --> ORCH
 ```
 
-## Main Product: Banking & Finance Copilot
-
-The main product lives in [`01-rag-system`](01-rag-system).
-
-What it does well:
-- grounded banking and compliance Q&A
-- OpenAI, Fine-Tuned, and Auto modes
-- source-backed answers with visible evidence
-- PDF, DOCX, TXT, and image upload support
-- multilingual answer support
-- evaluation workflows committed alongside the app
-
-### Product Walkthrough
-
-#### A clean first impression for the product
-
-This is the opening experience of the Banking & Finance Copilot: stable sidebar, mode selector, welcome guidance, and multilingual starter questions that make the product feel usable immediately.
-
-![Banking Copilot home experience](01-rag-system/screenshots/banking-copilot-home-experience.png)
-
-#### A grounded English answer that feels concise and useful
-
-This example shows the assistant answering a KYC question in English with a direct explanation, compact bullets, visible latency, and retrieved source support.
+## System Design
 
-![English KYC answer walkthrough](01-rag-system/screenshots/english-kyc-answer-walkthrough.png)
+The system is built in four layers:
 
-#### The same product experience working in Telugu
-
-This screenshot shows the answer structure holding up in Telugu, which is important because the product is meant to feel consistent across languages, not just translated.
-
-![Telugu KYC answer walkthrough](01-rag-system/screenshots/telugu-kyc-answer-walkthrough.png)
-
-#### Multilingual grounding working in Chinese as well
-
-This example shows the same KYC workflow in Chinese, which helps demonstrate that multilingual support is part of the product design, not just a side feature.
-
-![Chinese KYC answer walkthrough](01-rag-system/screenshots/chinese-kyc-answer-walkthrough.png)
-
-## Evaluation
-
-The repo includes two larger evaluation packs inside [`01-rag-system/evaluation`](01-rag-system/evaluation):
-
-- `evaluation_queries.md`
-  120 domain-specific banking, AML, KYC, Basel III, FDIC, RBI, CECL, and payments questions
-- `evaluation_multilingual.md`
-  120 multilingual questions grouped across OpenAI, Fine-Tuned, and Auto modes
-
-The folder also includes:
-
-- `run_eval_sets.py` to run both evaluation packs automatically
-- `summarize_eval_sets.py` to summarize any generated CSV
-- committed result snapshots in [`01-rag-system/evaluation/results`](01-rag-system/evaluation/results)
-- raw CSV outputs plus JSON summaries, so the runs are inspectable rather than just summarized in prose
-
-### Latest committed evaluation snapshots
+| Layer | Runtime area | Purpose |
+|---|---|---|
+| AI agent runtime | `01-rag-system` | Live Streamlit product, retrieval, orchestration, source-grounded UI, uploads, voice, and agent paths. |
+| BankingQA dataset | `02-qa-dataset` | 3,002-pair instruction dataset covering banking, compliance, AML, KYC, Basel III, FDIC, RBI, and finance topics. |
+| Domain model adaptation | `03-qlora-finetuning` | QLoRA workflow for adapting Mistral-7B-Instruct-v0.3 to banking and financial compliance terminology. |
+| Memory and orchestration | `04-conversational-memory` | FastAPI memory backend with session handling, history management, summarization, and backend comparison. |
 
-**Domain evaluation pack**
+The current live Space keeps the original folder path `01-rag-system` so existing Hugging Face deployment URLs and `app_file` metadata continue to work. Documentation now positions that folder as the AI agent runtime while preserving compatibility.
 
-| Metric | Result |
-|---|---|
-| Total prompts | 120 |
-| Available evaluated rows | 80 |
-| Average latency | 2037.0 ms |
-| Median latency | 2036.0 ms |
+## Evaluation Metrics
 
-**Multilingual evaluation pack**
+These numbers are from committed project files and should be read as traceable project evidence, not marketing claims.
 
 | Metric | Result |
 |---|---|
-| Total prompts | 120 |
-| Available evaluated rows | 80 |
-| Average latency | 2031.8 ms |
-| Median latency | 2031.5 ms |
-
-### What those numbers mean
-
-The committed snapshot is intentionally honest about the environment it was run in:
+| Evaluation prompts | 240 total prompts across domain and multilingual packs |
+| Latest available evaluated rows | 160 rows across committed domain and multilingual snapshots |
+| Domain pack average latency | 2037.0 ms |
+| Multilingual pack average latency | 2031.8 ms |
+| Dataset size | 3,002 QA pairs |
+| Fine-tuning method | Mistral-7B QLoRA |
+| Final train loss | 1.13 |
+| Current retrieval implementation | FAISS dense vector retrieval |
+| Sparse retrieval / RRF | Roadmap item, not claimed as live implementation |
 
-- the full packs contain 120 prompts each
-- the committed run has 80 available rows because the OpenAI path was not active in that local export
-- the Fine-Tuned and Auto paths still completed and produced auditable CSV/JSON artifacts
+For the current autonomy positioning, see [`AUTONOMY_EVALUATION.md`](AUTONOMY_EVALUATION.md). For the generated portfolio report, see [`01-rag-system/evaluation/reports/latest_portfolio_report.md`](01-rag-system/evaluation/reports/latest_portfolio_report.md).
 
-I prefer showing that reality instead of pretending every backend was active in every run. A reviewer can open the raw result files, see which rows were available, and rerun the exact same packs in a fully configured environment.
+## Key Capabilities
 
-### Portfolio report generator
+### Grounded Banking Answers
 
-To generate a single recruiter-friendly report from committed summary artifacts:
+The runtime retrieves banking material before generation, then presents answers with source cards, confidence labels, latency, and chunk metadata.
 
-- `python 01-rag-system/evaluation/generate_portfolio_report.py`
-- Output: `01-rag-system/evaluation/reports/latest_portfolio_report.md`
+### Model Orchestration
 
-This keeps the published numbers traceable and reproducible.
+OpenAI mode provides a stable general path, Fine-Tuned mode connects the domain adapter path where hosted inference is configured, and Auto mode scores candidate answers based on groundedness, completeness, and latency.
 
-### Regression tests for decision-critical behavior
+### Agentic Runtime Work
 
-I also added deterministic tests for high-risk agent decisions:
+The repo includes agentic/autonomous runtime work with tool-style execution traces and autonomy evaluation. This is presented honestly as a tool-calling AI system and agentic workflow layer, not as AGI.
 
-- `01-rag-system/tests/test_agentic_decision_engine.py`
+### Domain Data and Model Adaptation
 
-Run locally:
+The dataset and QLoRA adapter show the system is not only prompt engineering. It includes a reusable data asset and a domain-adapted model artifact.
 
-- `cd 01-rag-system`
-- `python -m unittest discover -s tests -p "test_*.py"`
+### Memory and API Layer
 
-### Why I kept the raw result files
+The FastAPI memory backend demonstrates session-aware conversation handling, summarization/truncation, health checks, and backend comparison endpoints.
 
-The most valuable part of the evaluation setup is not just the summary table. It is that the repo contains:
+## Demo Workflow
 
-- the question packs
-- the runner scripts
-- the summarizer
-- the committed outputs
+1. Open the [live Space](https://huggingface.co/spaces/RakeshMadasani/banking-finance-rag).
+2. Ask a banking or compliance question such as `What are the main KYC requirements for banks?`.
+3. Switch modes to compare OpenAI, Fine-Tuned, Auto, and agentic paths where configured.
+4. Upload a PDF, DOCX, or TXT document and ask a document-grounded question.
+5. Inspect confidence, source cards, latency, retrieved chunks, and read-aloud output.
+6. Review evaluation artifacts under `01-rag-system/evaluation`.
 
-So if someone asks, "How did you test it?" I can point to the exact prompts, exact outputs, and exact summaries rather than hand-picked screenshots.
+## Repository Structure
 
-Those results matter to me because they make the product discussable in a serious way. If someone asks how I tested it, I can point to committed query packs, reproducible runners, timestamped results, and summaries instead of hand-wavy claims.
-
-## Other Projects In The Portfolio
-
-### [02-qa-dataset](02-qa-dataset)
-
-This is the dataset layer behind the banking system. It contains the curated QA data used to support model adaptation and domain coverage.
-
-![Dataset screenshot](02-qa-dataset/screenshots/dataset-hf-splits.png)
-
-### [03-qlora-finetuning](03-qlora-finetuning)
-
-This is the model adaptation layer. It shows the QLoRA workflow used to adapt a Mistral model for banking-domain answers.
+```text
+banking-genai-portfolio/
+|-- README.md
+|-- ROADMAP.md
+|-- EVALUATION.md
+|-- SYSTEM_DESIGN.md
+|-- CONTRIBUTING.md
+|-- AUTONOMY_EVALUATION.md
+|-- 01-rag-system/                 # AI agent runtime and live Streamlit app
+|-- 02-qa-dataset/                 # BankingQA-3K dataset build/publish workflow
+|-- 03-qlora-finetuning/           # Mistral-7B QLoRA adaptation workflow
+`-- 04-conversational-memory/      # FastAPI memory and orchestration backend
+```
 
-![QLoRA model page screenshot](03-qlora-finetuning/screenshots/model-page-demo.png)
+## Run Locally
 
-### [04-conversational-memory](04-conversational-memory)
+```bash
+git clone https://github.com/rakeshmadasaniai/banking-genai-portfolio.git
+cd banking-genai-portfolio
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -r 01-rag-system/requirements.txt
+copy .env.example .env
+streamlit run 01-rag-system/app.py
+```
 
-This is the backend layer that adds session memory, orchestration, and API structure to the broader assistant system.
+Minimum environment:
 
-## Best Entry Points In Code
+```env
+OPENAI_API_KEY=
+HF_TOKEN=
+MODEL_MODE=OpenAI
+TOP_K=4
+TEMPERATURE=0.2
+```
 
-If someone wants to inspect the implementation rather than just the screenshots, these are the best places to start:
+## Known Limitations
 
-- `01-rag-system/app.py`
-- `01-rag-system/core/product_runtime.py`
-- `01-rag-system/core/retriever.py`
-- `01-rag-system/features/product_ui.py`
-- `01-rag-system/models/auto_router.py`
-- `01-rag-system/models/openai_mode.py`
-- `01-rag-system/models/finetuned_mode.py`
-- `01-rag-system/evaluation/run_eval_sets.py`
-- `01-rag-system/evaluation/summarize_eval_sets.py`
-- `02-qa-dataset/generate_dataset.py`
-- `03-qlora-finetuning/inference_demo.py`
-- `04-conversational-memory/app/main.py`
-- `04-conversational-memory/app/rag_chain.py`
+- The live retrieval path is FAISS dense search; BM25 and reciprocal rank fusion are documented as roadmap work until implemented in code.
+- Fine-Tuned mode depends on an available hosted endpoint or compatible local inference environment.
+- Streamlit session state is not durable across browser restarts; the separate FastAPI memory backend demonstrates the production direction.
+- The system is educational and portfolio-grade; it is not legal, financial, investment, or compliance advice.
 
-## Repo Structure
+## Roadmap
 
-```text
-banking-genai-portfolio/
-|-- README.md
-|-- 01-rag-system/
-|-- 02-qa-dataset/
-|-- 03-qlora-finetuning/
-`-- 04-conversational-memory/
-```
+See [`ROADMAP.md`](ROADMAP.md) for the planned reliability, agentic architecture, governance, and production-hardening phases.
 
-## Closing Note
+## License and Contact
 
-The part I value most in this portfolio is not that it calls an LLM. It is that the repo shows the full path from idea to product: retrieval, data, model work, backend orchestration, evaluation, and a live user-facing deployment that someone can test today.
+This repository is intended as an AI engineering portfolio and educational system. For questions, reach out through [GitHub](https://github.com/rakeshmadasaniai), [Hugging Face](https://huggingface.co/RakeshMadasani), or [LinkedIn](https://www.linkedin.com/in/rakesh-madasani-b217b71b0/).

ROADMAP.md

@@ -0,0 +1,49 @@
+# Roadmap
+
+This roadmap keeps the project moving toward a stronger production-grade Banking & Finance AI Agent without overclaiming what is already implemented.
+
+## Phase 1 - Reliability
+
+- Fill any missing evaluation tables with reproducible result snapshots.
+- Add regression tests for high-risk banking, compliance, investment, and multilingual paths.
+- Improve source-grounding checks and weak-retrieval fallbacks.
+- Track p50, p95, and p99 latency instead of only averages.
+- Add deterministic smoke tests for the Streamlit runtime startup path.
+
+## Phase 2 - Agentic Architecture
+
+- Formalize a Planner -> Executor -> Verifier loop.
+- Standardize tool-use traces across all agentic modes.
+- Add retry policy, max-step budgets, and clear stop conditions.
+- Separate "answer directly" from "act with tools" using an explicit decision layer.
+- Add durable task-state persistence for long-running autonomous workflows.
+
+## Phase 3 - Governance
+
+- Add compliance guardrails for AML, KYC, sanctions, investment-risk, and crisis scenarios.
+- Add structured audit logs for tool calls, verification decisions, and fallback paths.
+- Add escalation policy for unsupported legal, compliance, or investment-advice requests.
+- Add risk scoring for answers that combine regulated finance and user-specific facts.
+- Create reviewer-friendly model cards and dataset cards with limitations clearly stated.
+
+## Phase 4 - Production Hardening
+
+- Add Docker deployment for the Streamlit app and FastAPI memory backend.
+- Add CI/CD for tests, linting, and evaluation smoke checks.
+- Add API documentation for the memory backend.
+- Add monitoring for latency, tool failure rates, retrieval misses, and user-facing errors.
+- Add versioned releases and changelogs.
+
+## Phase 5 - Retrieval Upgrade
+
+- Add BM25 sparse retrieval.
+- Add reciprocal rank fusion between FAISS dense retrieval and BM25 sparse retrieval.
+- Add retrieval ablation tests to quantify dense-only versus hybrid retrieval quality.
+- Add query rewriting for difficult regulatory and multilingual prompts.
+
+## Phase 6 - Portfolio Distribution
+
+- Publish a concise technical write-up explaining the system design and evaluation.
+- Mirror the live Hugging Face Space state into GitHub branches or releases.
+- Add demo clips or GIFs that show source cards, agent trace, uploads, and voice output.
+- Keep README claims tied to committed code, result files, and reproducible scripts.

SYSTEM_DESIGN.md

@@ -0,0 +1,118 @@
+# System Design
+
+## Problem
+
+Banking and finance users need answers that are clear, grounded, and measurable. A normal chatbot can produce fluent text, but regulated domains require source visibility, confidence signals, evaluation, and careful handling of user-specific finance or compliance scenarios.
+
+## Goals
+
+- Provide a live AI workflow interface for banking and compliance questions.
+- Ground answers in curated banking material and uploaded documents.
+- Support multiple model paths and routing decisions.
+- Track latency, confidence, source usage, and evaluation outputs.
+- Demonstrate the full system chain: data, retrieval, fine-tuning, memory, evaluation, and deployment.
+
+## Non-Goals
+
+- Do not claim AGI.
+- Do not claim formal legal, investment, financial, or compliance advice.
+- Do not claim BM25/RRF as implemented until the code path exists.
+- Do not claim fully autonomous production operation without durable planning, monitoring, governance, and external action controls.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A["User input"] --> B["Input router"]
+    B --> C["Text / upload / voice handling"]
+    C --> D["Chunking + embeddings"]
+    D --> E["FAISS dense retrieval"]
+    E --> F["Grounded context"]
+    F --> G["Model orchestration"]
+    G --> H["OpenAI mode"]
+    G --> I["Fine-Tuned mode"]
+    G --> J["Auto mode"]
+    G --> K["Agentic / Autonomous modes"]
+    H --> L["Confidence + source rendering"]
+    I --> L
+    J --> L
+    K --> L
+    L --> M["Response UI"]
+    M --> N["Session memory / audit context"]
+```
+
+## Retrieval Design
+
+Current implementation:
+
+- Documents are chunked and embedded.
+- FAISS provides dense vector search.
+- Retrieved context is passed into answer generation and source cards.
+
+Planned retrieval hardening:
+
+- Add BM25 sparse retrieval for exact regulatory terms.
+- Fuse dense and sparse results with reciprocal rank fusion.
+- Add retrieval evaluation comparing dense-only and hybrid retrieval.
+
+## Model Orchestration
+
+The runtime supports several paths:
+
+- OpenAI mode for stable general-purpose answers.
+- Fine-Tuned mode for the banking-domain adapter path.
+- Auto mode for scoring candidate answers and selecting a winner.
+- Agentic/autonomous modes for tool-style workflows and execution traces where configured.
+
+Candidate scoring uses groundedness, completeness, and latency signals. This makes routing inspectable instead of hidden.
+
+## Memory Design
+
+The live Streamlit runtime uses session state for chat/session continuity during a browser session. The separate FastAPI memory backend demonstrates the production direction:
+
+- session IDs,
+- retained recent turns,
+- summarization/truncation,
+- comparison endpoints,
+- health checks.
+
+Production memory should move to durable storage such as Redis or Postgres.
+
+## Evaluation Design
+
+Evaluation is repository-native:
+
+- domain prompt packs,
+- multilingual prompt packs,
+- runner scripts,
+- summarizer scripts,
+- committed CSV/JSON outputs,
+- generated portfolio report,
+- autonomy audit.
+
+This structure lets reviewers inspect prompts and outputs rather than relying on hand-picked examples.
+
+## Reliability Considerations
+
+- Weak retrieval should be surfaced clearly.
+- Mode failures should degrade gracefully.
+- Fine-Tuned endpoint unavailability should not crash the app.
+- Upload parsing should handle unsupported or malformed files safely.
+- Agentic workflows need max-step limits, retry budgets, and stop conditions.
+- Regulated finance answers should include disclaimers and avoid unsupported personalized advice.
+
+## Tradeoffs
+
+- Streamlit is excellent for fast product iteration, but not a full production backend by itself.
+- FAISS dense retrieval is simple and fast, but sparse retrieval is needed for exact regulatory threshold matching.
+- QLoRA adapters are efficient for domain adaptation, but inference still requires a compatible base model environment.
+- Agentic behavior improves complex workflows, but it adds latency and requires strict controls.
+
+## Future Improvements
+
+- Implement BM25 + reciprocal rank fusion.
+- Add durable memory and audit logs.
+- Add Docker and CI/CD.
+- Add p95/p99 latency monitoring.
+- Add benchmarked document-upload and voice tests.
+- Add governance guardrails for high-risk compliance and investment scenarios.

requirements.txt

@@ -1,12 +1,16 @@
+streamlit==1.56.0
 langchain==0.1.20
 langchain-community==0.0.38
 langchain-openai==0.1.6
-openai==1.30.0
+openai>=1.40.0
+pydantic>=2.0.0
 httpx<0.28
 faiss-cpu
 sentence-transformers==2.7.0
 pypdf==4.2.0
+PyPDF2>=3.0.0
 python-dotenv==1.0.1
 huggingface-hub==0.23.0
 python-docx==1.1.2
 streamlit-mic-recorder==0.0.8
+yfinance