Replace main with mobile-friendly ProspectIQ codebase

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.agents
+.venv
+__pycache__
+*.py[cod]
+.env
+.env.*
+*.db
+*.db.bak
+learning_data/uploads
+learning_data/converted
+services/research/pipe_output
+docs/images

.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

.github/workflows/deploy-azure.yml

@@ -0,0 +1,60 @@
+name: Deploy to Azure Container Apps
+
+on:
+  workflow_dispatch:
+
+env:
+  AZURE_RESOURCE_GROUP: ProspectIQ_centralindia
+  AZURE_CONTAINER_APP: prospectiq
+  ACR_LOGIN_SERVER: prospectiqacr57421.azurecr.io
+  IMAGE_NAME: prospectiq
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set image tags
+        id: image
+        shell: bash
+        run: |
+          echo "latest=${ACR_LOGIN_SERVER}/${IMAGE_NAME}:latest" >> "$GITHUB_OUTPUT"
+          echo "sha=${ACR_LOGIN_SERVER}/${IMAGE_NAME}:${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Azure Container Registry
+        uses: azure/docker-login@v2
+        with:
+          login-server: ${{ env.ACR_LOGIN_SERVER }}
+          username: ${{ secrets.ACR_USERNAME }}
+          password: ${{ secrets.ACR_PASSWORD }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ steps.image.outputs.latest }}
+            ${{ steps.image.outputs.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Log in to Azure
+        uses: azure/login@v2
+        with:
+          creds: ${{ secrets.AZURE_CREDENTIALS }}
+
+      - name: Deploy image to Container App
+        uses: azure/cli@v2
+        with:
+          inlineScript: |
+            az containerapp update \
+              --name "${AZURE_CONTAINER_APP}" \
+              --resource-group "${AZURE_RESOURCE_GROUP}" \
+              --image "${{ steps.image.outputs.sha }}"

.gitignore

@@ -0,0 +1,15 @@
+.env
+.env.*
+!.env.production.example
+.venv/
+__pycache__/
+*.py[cod]
+*.db
+*.db.bak
+learning_data/uploads/
+learning_data/converted/
+services/research/pipe_output/
+docs/images/
+.azure-acr-info.txt
+.azure-github-secrets.json
+.CHANGES_FROM_GITHUB_MAIN.txt

ASHWIN.txt

@@ -0,0 +1,666 @@
+Codebase Changes Summary
+========================
+
+This file documents the current uncommitted changes found in the working tree.
+It includes what changed, what the change does, and the main line numbers involved.
+
+Important note:
+- A very large part of this working tree diff is formatting / blank-line / CRLF-LF line-ending churn.
+- Where a file only appears to have formatting or blank-line cleanup, this summary says so.
+- Feature-level notes are based on the whitespace-filtered diff and current line numbers.
+
+Overall diff summary
+--------------------
+- Deleted tracked files: 3
+- Modified tracked files shown by git status: 50
+- Untracked files: ASHWIN.txt and prospectiq_history_corrupt.bak
+- Large frontend files such as static/styles.css, static/js/views/prospecting.js, static/js/app.js, and templates/index.html show very high deletion counts mostly because blank lines were removed.
+
+1. .env.production.example
+--------------------------
+Lines involved: 1-20, entire deleted file
+
+Changes made:
+- Deleted the production environment example file.
+
+What it does:
+- Removes the sample production environment configuration from the tracked codebase.
+
+2. CHANGES_FROM_GITHUB_MAIN.txt
+-------------------------------
+Lines involved: 1-229, entire deleted file
+
+Changes made:
+- Deleted the previous GitHub-main change note.
+
+What it does:
+- Removes an older/manual changelog artifact from the repository.
+
+3. claude_fallback_changelog.txt
+--------------------------------
+Lines involved: 1-84, entire deleted file
+
+Changes made:
+- Deleted the Claude fallback changelog note.
+
+What it does:
+- Removes an older/manual AI fallback changelog artifact from the repository.
+
+4. schema.sql
+-------------
+Lines involved: 11-46
+
+Changes made:
+- Added permissions table at lines 11-15.
+- Added roles table at lines 17-25.
+- Added role_permissions join table at lines 27-34.
+- Added password_hash to users at line 40.
+- Added role_id to users at line 41.
+- Added a users.role_id foreign key to roles at line 46.
+
+What it does:
+- Adds database support for role-based access control.
+- Lets users be connected to tenant-specific roles.
+- Prepares the local SQLite schema for password-backed auth and permission checks.
+
+5. supabase_schema.sql
+----------------------
+Lines involved: 16-43
+
+Changes made:
+- Added permissions table at lines 16-20.
+- Added roles table at lines 22-29.
+- Added role_permissions table at lines 31-35.
+- Added password_hash to users at line 42.
+- Added role_id with a roles foreign key at line 43.
+
+What it does:
+- Mirrors the role/permission changes for Supabase/Postgres deployments.
+- Keeps local and hosted schema definitions aligned.
+
+6. migrate.py
+-------------
+Lines involved: 25-204
+
+Changes made:
+- Includes migration logic for roles table creation at lines 25-49.
+- Includes migration logic for permissions table creation at lines 51-68.
+- Includes migration logic for role_permissions table creation at lines 70-89.
+- Adds password_hash and role_id columns to existing users tables at lines 96-111.
+- Seeds default permissions at lines 115-133.
+- Creates/ensures standard tenant roles at lines 141-148.
+- Grants permissions to Admin, BD Rep, and Viewer roles at lines 149-181.
+- Maps existing users to role IDs and default password hashes at lines 184-204.
+
+What it does:
+- Upgrades existing databases to the new role/permission model without requiring a fresh database.
+- Gives Admin all permissions, BD Rep non-admin operational permissions, and Viewer read permissions.
+
+7. routes/auth.py
+-----------------
+Lines involved: formatting/line-ending change in git diff; current relevant auth code is around 47-584
+
+Changes made:
+- The file is marked modified, but the whitespace-filtered diff does not show clear content changes.
+- Current file contains role seeding, permission lookup, admin dashboard, user management, role creation, and role-permission update logic.
+
+What it does:
+- No definite behavior change is attributable to this working-tree diff after ignoring formatting.
+- The existing auth code supports tenant roles and permissions used by the schema/migration changes.
+
+8. routes/ai.py
+---------------
+Lines involved: 377-394
+
+Changes made:
+- Added agentspace_system_prompt at line 377.
+- The prompt tells Agent Space to:
+  - Be conversational and helpful.
+  - Ask clarifying questions instead of returning blunt errors.
+  - Suggest MCQ-style options for ambiguous requests.
+  - Distinguish internal users/reps/roles from external CRM contacts.
+  - Treat saved CRM/database queries differently from external Regional Prospecting.
+  - Extract decision makers into a contacts array when creating companies.
+- Existing system messages are prefixed with this prompt at line 392.
+- If no system message exists, the prompt is inserted at line 394.
+
+What it does:
+- Makes Agent Space safer and more precise.
+- Reduces cases where "add user" becomes an external contact.
+- Reduces cases where "show companies in CRM" accidentally triggers external prospecting.
+- Helps AI-created companies include leadership contacts automatically.
+
+9. routes/command.py
+--------------------
+Lines involved: 318, 410-427, 458-513, 528-564, 619-650, 710-762, 775-786, 833-841, 917-1218
+
+Changes made:
+- Expanded company-name cleanup at line 318 so descriptive phrases, location words, staff-size words, leadership titles, punctuation, and clauses are removed from the company name.
+- Contact extraction now treats linkedin as a field boundary at line 410.
+- Added LinkedIn parsing into contact_data at lines 425-427.
+- Added unscheduled/unassigned handling for task dates at lines 458-459.
+- Added unscheduled/unassigned handling for task times at lines 492-493.
+- Removed "unscheduled" and "unassigned" from generated task titles at line 513.
+- Expanded list intent keywords at line 528, including typo support for "sow" and "shwo".
+- Added rep/user/role/admin/viewer detection at lines 539-540.
+- Prevented internal rep/user/role prompts from being interpreted as external contacts at lines 541-556.
+- Changed company filtering intent so stage/pipeline requests route to CRM filtering at line 564.
+- Replaced representative parsing with a broader add_rep_match at lines 619-635.
+- Added a friendly clarification response when adding an internal team member without enough information at lines 636-642.
+- Added explicit CRM-database detection at lines 710-714.
+- Added auto-routing to Regional Prospecting only for clear external discovery/prospecting queries at lines 711-712.
+- Added local CRM filtering and top-N reply generation at lines 730-758.
+- Returned filter_companies responses with a generated reply at lines 759-762.
+- Added guardrails to avoid deterministic add_company parsing when a descriptive prompt is too complex at lines 775-776.
+- Improved industry parsing from "doing/do/in ... business" phrasing at line 781.
+- Improved staff-size parsing, including ranges like 50-70 using the midpoint, at lines 784-786.
+- Added LinkedIn as an editable contact field at lines 833-841.
+- Updated the LLM command-routing prompt at lines 937-1004 with:
+  - CRM database vs Regional Prospecting rules.
+  - Clean company-name extraction rules.
+  - Company notes/current_supplier_notes rules.
+  - Contact extraction from executives and decision makers.
+  - LinkedIn support for contacts.
+  - Unscheduled task behavior.
+  - Internal team member vs external CRM contact clarification.
+- Removed an unconditional fallback_tool_route return near lines 1211-1213 so weak fallback routes do not override parsed AI results too early.
+
+What it does:
+- Makes the command bar much better at understanding natural-language CRM requests.
+- Adds support for LinkedIn when adding/editing contacts.
+- Allows tasks to be saved as unscheduled duties instead of forcing them into the calendar.
+- Makes "top 3 companies in database" answer from saved CRM data instead of launching geo search.
+- Makes external discovery queries still route to Regional Prospecting when appropriate.
+- Makes internal user/rep creation safer and less likely to be confused with customer contacts.
+
+10. services/tool_router.py
+---------------------------
+Lines involved: 56-89
+
+Changes made:
+- Added is_explicit_crm detection at lines 56-58.
+- If a query clearly mentions CRM/database/stages/users/contacts/reps, the heuristic router now returns None instead of forcing an external tool route.
+- Expanded CRM company filter language and typo handling at lines 60-63.
+- Narrowed geo prospecting patterns so they require clearer location/discovery wording at lines 70-86.
+- Removed broad trigger text such as "companies in" and "find companies" that could accidentally route CRM queries into geo search.
+
+What it does:
+- Prevents CRM/database commands from being misrouted to Regional Prospecting.
+- Keeps geo routing for true prospect discovery such as nearby/map-search/discover-new requests.
+
+11. routes/companies.py
+-----------------------
+Lines involved: 3, 193-235, 381-428, 437-475, 487-618
+
+Changes made:
+- Imported get_request_tenant_id at line 3.
+- Added extract_contacts_from_descriptive_notes() at lines 193-235.
+- add_company now reads the current tenant ID at line 381.
+- add_company now normalizes notes/current_supplier_notes at lines 389-401.
+- Replaced hard-coded tenant_id 1 with request tenant_id at line 411.
+- Inserts notes_text into current_supplier_notes at line 428.
+- Adds contacts from data.contacts or parsed notes at lines 437-466.
+- Writes notes_text into activities and notes at lines 467-475.
+- add_company_from_extractor now uses request tenant_id at lines 487 and 514.
+- add_company_from_ocr now uses request tenant_id at lines 583 and 618.
+
+What it does:
+- New companies are created under the correct tenant instead of always tenant 1.
+- Descriptive AI company prompts can create company contacts automatically.
+- Leadership and meeting/background notes are preserved in activity/notes history.
+
+12. static/js/components/inline_assistant.js
+--------------------------------------------
+Lines involved: 225-262, 283-401, 410-444, 453-504
+
+Changes made:
+- Company profile actions now use switchWorkspaceAndScrollTo() when available at lines 225-226.
+- Company filtering now scrolls to the company table at lines 250-251.
+- Company filtering replies are more specific and can use the server-provided reply at lines 255-264.
+- Add/edit/delete company and contact flows now route and scroll to the correct table sections at lines 283-401.
+- Task creation now checks whether the date is explicit at line 410.
+- Unscheduled/unassigned tasks now set date/time to null at lines 410-412.
+- Notifications distinguish scheduled tasks from unscheduled task-list items at lines 427-430.
+- Task creation scrolls to calendar-section or tasks-section depending on whether there is a date at lines 434-436.
+- Task replies distinguish scheduled tasks from unassigned duties at lines 441-444.
+- Task edits normalize null/unscheduled date and time values at lines 453-454.
+- Task edit/complete/delete actions scroll to calendar or tasks based on the task's date at lines 463-504.
+
+What it does:
+- Inline AI actions now take the user to the right workspace and section.
+- Unscheduled duties stay in the task list instead of being forced into the calendar.
+- Assistant replies are clearer after filtering, scheduling, and task actions.
+
+13. static/js/app.js
+--------------------
+Lines involved: 618, 1018-1050, 1144-1422, 1488 onward
+
+Changes made:
+- Global command input lookup still uses global-command-bar at line 618, now backed by a textarea in the template.
+- Added switchWorkspaceAndScrollTo() at lines 1018-1050.
+- Command result handling now uses switchWorkspaceAndScrollTo() for company profile, company table, contact table, calendar, and task-list destinations at lines 1144-1422.
+- Command input event handling near line 1488 supports textarea behavior.
+- Large parts of the file also had blank-line cleanup, creating a very large diff that is mostly formatting.
+
+What it does:
+- Command results can move admins from portal mode into workspace mode and scroll directly to the relevant UI area.
+- The global command bar can behave more like a multi-line command textarea.
+
+14. templates/index.html
+------------------------
+Lines involved: 140, 334-352
+
+Changes made:
+- Replaced the global command bar input with a textarea at line 140.
+- Wrapped the password input in an input group at lines 334-338.
+- Added a toggle-password button and Bootstrap eye icon at lines 337-338.
+- Added DOMContentLoaded password visibility toggle script at lines 343-352.
+- The file also has a large amount of blank-line cleanup.
+
+What it does:
+- Users can type longer commands more comfortably.
+- Users can show/hide the login password field.
+
+15. static/js/views/profile.js
+------------------------------
+Lines involved: 29-30, 330, 351, 412, 430, old media tab/pane blocks around previous 448-473 and 1284-1296
+
+Changes made:
+- Removed media from validTabs at line 29.
+- Added id="company-profile-header" to the profile header at line 330.
+- Cleaned Agent Space tab text at lines 351 and 412.
+- Kept the Agent Space pane at line 430.
+- Removed the Media & Videos tab/pane.
+- Removed the old drawVideosTab() placeholder function.
+- Removed old video watched checkbox/localStorage handling.
+
+What it does:
+- Company profiles no longer show the unused Media & Videos area.
+- Other code can scroll directly to the company profile header.
+
+16. static/js/views/mockups.js
+------------------------------
+Lines involved: 20, 24-28, 278-360, 365-581
+
+Changes made:
+- Added isAdmin check based on users:manage permission at line 20.
+- Renamed the page heading to "Settings & Configuration" at line 24.
+- Updated settings description text at lines 24-28.
+- Redesigned command memory loading/display at lines 278-360.
+- Command memory items now include "View Checkpoint" buttons at line 322.
+- Admin console layout/copy changed around lines 365-581.
+
+What it does:
+- Settings now better separates AI memory/checkpoints from admin controls.
+- Admin-only controls are tied to the actual users:manage permission.
+
+17. static/js/views/prospecting.js
+----------------------------------
+Lines involved: 1-75, 81-123 and many later sections; major formatting cleanup throughout
+
+Changes made:
+- Prospecting state contains active OCR, geo, and research job fields at lines 1-18.
+- Added sessionStorage keys for active geo/research jobs at lines 19-20.
+- Restores active geo job state from sessionStorage at lines 23-29.
+- Restores active research job state from sessionStorage at lines 35-42.
+- Added saveGeoJobSession() at lines 44-56.
+- Added saveResearchJobSession() at lines 58-73.
+- Added prospecting status helpers and metadata around lines 81-123.
+- The file shows extremely large deletions because many blank lines were removed.
+
+What it does:
+- Prospecting job state can survive navigation/refresh better.
+- Regional Prospecting and Company Research status can be tracked through shared helper state.
+- Most of the huge diff is formatting cleanup rather than isolated feature changes.
+
+18. static/styles.css
+---------------------
+Lines involved: 352-411, 1955-1984, 2258-3218, 3273, 4818-4842, 5482 onward
+
+Changes made:
+- Updated command input/action styling at lines 352-411.
+- Profile tab styles remain around lines 1955-1984 after Media tab cleanup.
+- Large Prospecting/Geo Finder style section exists at lines 2258-3218.
+- Responsive command-bar styling appears at lines 3273 and 4818-4842.
+- Auth styles appear at line 5482 onward.
+- The file has the largest diff because many blank lines and formatting were removed.
+
+What it does:
+- Supports the command textarea and command action layout.
+- Supports the Prospecting/Geo Finder UI styles.
+- Supports the login/auth UI including the updated password input area.
+
+19. static/js/views/companies.js
+--------------------------------
+Lines involved: line 1
+
+Changes made:
+- One-line content/formatting change at the start of the file.
+
+What it does:
+- No clear feature-level behavior change is visible from the whitespace-filtered diff.
+
+20. static/js/views/contacts.js
+-------------------------------
+Lines involved: line 1
+
+Changes made:
+- One-line content/formatting change at the start of the file.
+
+What it does:
+- No clear feature-level behavior change is visible from the whitespace-filtered diff.
+
+21. static/js/views/home.js
+---------------------------
+Lines involved: lines 1-4
+
+Changes made:
+- Small content/formatting change near the start of the file.
+
+What it does:
+- No clear feature-level behavior change is visible from the whitespace-filtered diff.
+
+22. requirements.txt
+--------------------
+Lines involved: around line 143
+
+Changes made:
+- Removed an extra blank line around the anthropic dependency.
+
+What it does:
+- No dependency was clearly added or removed in this working-tree diff.
+- This appears to be formatting cleanup only.
+
+23. db.py
+---------
+Lines involved: around 288, 572-657
+
+Changes made:
+- Removed blank lines around get_db_connection(), dict_from_row(), Redis cache helpers, and cache_get/cache_set.
+
+What it does:
+- Formatting cleanup only.
+- No clear behavior change is visible from the whitespace-filtered diff.
+
+24. routes/learning.py
+----------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear behavior change.
+
+25. routes/stt.py
+-----------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed one blank/formatting line.
+
+What it does:
+- No clear behavior change.
+
+26. routes/system.py
+--------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank/formatting lines only.
+
+What it does:
+- No clear behavior change.
+
+27. services/ai_service.py
+--------------------------
+Lines involved: formatting/blank-line cleanup throughout
+
+Changes made:
+- Removed blank lines around many helper functions and job-management functions.
+
+What it does:
+- Formatting cleanup only in this working-tree diff.
+- No clear service behavior change is visible after ignoring whitespace.
+
+28. services/export_service.py
+------------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear export behavior change.
+
+29. services/geo_search.py
+--------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear geo-search behavior change in this working-tree diff.
+
+30. services/ocr.py
+-------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear OCR behavior change.
+
+31. services/rag_service.py
+---------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear RAG behavior change.
+
+32. services/research/analyzer.py
+---------------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear research analyzer behavior change.
+
+33. services/research/browser.py
+--------------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear browser/research behavior change.
+
+34. services/research/pipeline.py
+---------------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear pipeline behavior change.
+
+35. services/research/query_generator.py
+----------------------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear query-generation behavior change.
+
+36. services/research/questionlist.md
+-------------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear documentation/content behavior change.
+
+37. static/js/components/contact_drawer.js
+------------------------------------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed one blank/formatting line.
+
+What it does:
+- No clear behavior change.
+
+38. static/js/components/activity_logger.js
+-------------------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+39. static/js/components/agent_drawer.js
+----------------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+40. static/js/components/buttons.js
+-----------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+41. static/js/components/columns.js
+-----------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+42. static/js/components/notifications.js
+-----------------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+43. static/js/components/tasks.js
+---------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+44. static/js/router.js
+-----------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+45. static/js/utils.js
+----------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+46. static/js/views/admin_portal.js
+-----------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear behavior change.
+
+47. static/js/views/learning.js
+-------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear Learning-page behavior change in this working-tree diff.
+
+48. learning_data/collections_meta.json
+---------------------------------------
+Lines involved: formatting/line-ending change
+
+Changes made:
+- File is marked modified, but no clear content change was visible after whitespace filtering.
+
+What it does:
+- No clear data/content change.
+
+49. tasks.py
+------------
+Lines involved: formatting/blank-line cleanup
+
+Changes made:
+- Removed blank lines only in the whitespace-filtered diff.
+
+What it does:
+- No clear task behavior change.
+
+50. ASHWIN.txt
+--------------
+Lines involved: entire file
+
+Changes made:
+- Added/rewrote this codebase change summary document.
+- Expanded it to match the attached example style: numbered file sections, line ranges, changes made, and what each change does.
+
+What it does:
+- Documents the current working tree changes for easier review.
+
+51. prospectiq_history_corrupt.bak
+----------------------------------
+Lines involved: untracked file
+
+Changes made:
+- An untracked backup file exists in the repository root.
+
+What it does:
+- Likely preserves a corrupted or old ProspectIQ history artifact.
+- It is not currently part of the tracked codebase unless intentionally added.

CONFLICT_ANALYSIS_REPORT.txt

@@ -0,0 +1,331 @@
+Codebase Change Conflict Analysis
+==================================
+
+Source documents compared:
+- ASHWIN.txt (Ashwin's uncommitted working-tree change summary)
+- JAI.txt (Jai's uncommitted working-tree change summary)
+
+Purpose:
+This report identifies overlaps, contradictions, and merge risks between the
+two change summaries, which describe changes made to the same codebase by
+two different people.
+
+==================================================================
+SECTION 1: CRITICAL CONFLICT - CONTRADICTORY REPORTS ON SAME FILES
+==================================================================
+
+The following files are described very differently by each report. In every
+case, JAI's summary describes real functional/feature changes with specific
+line numbers, while ASHWIN's summary describes the SAME file as pure
+whitespace/blank-line/line-ending cleanup with "no clear behavior change."
+
+Since both documents claim to summarize the current working tree, this
+contradiction means one of two things:
+  (a) Ashwin's working tree does not currently contain Jai's changes
+      (different branch, different machine, or changes not yet pulled), or
+  (b) Ashwin's diffing method (whitespace-filtered diff) failed to detect
+      real content changes in these files.
+
+Either way, if Ashwin's version of these files is merged/pushed as the
+source of truth, Jai's work in each of these files is at risk of being
+silently lost or overwritten.
+
+--------------------------------------------------------------
+1.1 services/ai_service.py
+--------------------------------------------------------------
+JAI reports (lines 771-780):
+  - Replaced the generic geo pipeline log message with friendly stage
+    labels: Input parsed, Fetching maps, Fetching internet, Verifying,
+    Verifying URLs, Ranking.
+
+ASHWIN reports (same file):
+  - "Formatting/blank-line cleanup throughout... no clear service
+    behavior change is visible after ignoring whitespace."
+
+Risk: HIGH - functional UX change vs. "nothing changed."
+
+--------------------------------------------------------------
+1.2 services/export_service.py
+--------------------------------------------------------------
+JAI reports (lines 211-238, 244, 247-248, 253-267, 334, 691-710):
+  - Added standardize_na() and get_geo_contact() helper functions.
+  - Website export normalizes invalid/missing values to "N/A."
+  - Phone/Email export columns use cleaned contact extraction, including
+    splitting emails mistakenly placed in phone fields.
+  - Removed Match Score, Operating Hours, Operational Status, Legitimacy
+    Label, and All Available Details columns from geo export.
+  - Added logic to prevent dropped/mapped fields from duplicating as
+    extra columns.
+  - Added Unicode replacement/cleanup before profile PDF generation to
+    avoid black square glyphs.
+
+ASHWIN reports (same file):
+  - "Formatting/blank-line cleanup only... no clear export behavior
+    change."
+
+Risk: HIGH - multiple new functions and export-format changes vs.
+"nothing changed."
+
+--------------------------------------------------------------
+1.3 services/geo_search.py
+--------------------------------------------------------------
+JAI reports (lines 42-43, 68-69, 87, 119-130, 285-286, 473-474, 624-647):
+  - Prompt instructions now separately request Phone number and Email
+    address.
+  - Removed operating hours/operational status from requested output.
+  - Loosened filtering so companies aren't dropped just because HQ is
+    outside the searched city.
+  - Removed Match score from ranking output; added Full address, Phone
+    number, Email, Services/products to required output fields.
+  - Added stricter N/A rules for missing website/phone/email.
+  - Switched some Claude calls from Sonnet to claude-haiku-4-5.
+  - Increased max_tokens to 4096 in several places.
+  - Added continuation/retry handling when judge output is truncated by
+    max_tokens, plus a fallback message for empty judge output.
+
+ASHWIN reports (same file):
+  - "Formatting/blank-line cleanup only... no clear geo-search behavior
+    change in this working-tree diff."
+
+Risk: VERY HIGH - this is the single largest functional change in
+either report (model swap, prompt rewrite, retry logic), and Ashwin's
+version shows none of it.
+
+--------------------------------------------------------------
+1.4 services/ocr.py
+--------------------------------------------------------------
+JAI reports (lines 146-147):
+  - Changed OCR model from claude-3-5-sonnet-20241022 to
+    claude-haiku-4-5.
+  - Increased max_tokens from 1024 to 4096.
+
+ASHWIN reports (same file):
+  - "Formatting/blank-line cleanup only... no clear OCR behavior
+    change."
+
+Risk: HIGH - a model swap is a meaningful behavioral/cost change that
+Ashwin's report does not reflect at all.
+
+--------------------------------------------------------------
+1.5 static/js/views/learning.js
+--------------------------------------------------------------
+JAI reports (lines 14-15, 103-105, 110-153, 268-354, 390-408, 421-436,
+440-456, 487-505, 683-730, 755-760):
+  - Added background task polling (processingTaskIds, pollingTimer,
+    checkTaskStatus, startPollingTasks).
+  - Added custom Bootstrap confirm/error modals replacing native
+    browser confirm() dialogs for collection/document/chat deletion.
+  - Documents with 0 pages/chunks now show "Processing..." with a
+    spinner instead of stale counts.
+  - Upload flow now tracks background task IDs for documents and URL
+    uploads.
+
+ASHWIN reports (same file):
+  - "Formatting/line-ending change... no clear Learning-page behavior
+    change in this working-tree diff."
+
+Risk: HIGH - an entire polling/notification subsystem is missing from
+Ashwin's version of this file.
+
+==================================================================
+SECTION 2: DEPENDENCY FILE CONFLICT
+==================================================================
+
+--------------------------------------------------------------
+2.1 requirements.txt
+--------------------------------------------------------------
+JAI reports (lines 142-147):
+  - Added six new dependencies: unstructured[xlsx], pandas, networkx,
+    supabase, ddgs, langchain-excel-loader.
+
+ASHWIN reports (same file, ~line 143):
+  - "Removed an extra blank line around the anthropic dependency...
+    no dependency was clearly added or removed. Formatting cleanup
+    only."
+
+Risk: HIGH - same contradiction pattern as Section 1, but flagged
+separately because a missed dependency file means the app may fail to
+import modules (pandas, networkx, supabase, etc.) that Jai's code in
+other files (geo_search.py, export_service.py, learning.js backend
+support) likely now depends on. This compounds the Section 1 risk:
+losing requirements.txt changes could break the very features that
+would otherwise be preserved.
+
+==================================================================
+SECTION 3: OVERLAPPING FILES - LINE-LEVEL MERGE COLLISION RISK
+==================================================================
+
+These files are edited by both people in ways that are not directly
+contradictory in content, but occupy overlapping or adjacent line
+ranges, creating a high risk of literal merge conflicts or line-number
+drift.
+
+--------------------------------------------------------------
+3.1 routes/command.py
+--------------------------------------------------------------
+JAI reports (line 1019):
+  - Increased max_tokens from 1000 to 4096.
+
+ASHWIN reports (lines 318, 410-427, 458-513, 528-564, 619-650,
+710-762, 775-786, 833-841, 917-1218):
+  - Large rewrite: company-name cleanup, LinkedIn contact parsing,
+    unscheduled task handling, CRM vs. Regional Prospecting routing
+    logic, LLM command-routing prompt rewrite (937-1004), fallback
+    route removal (~1211-1213).
+
+Risk: HIGH - Jai's single-line change at 1019 falls squarely inside
+Ashwin's heavily rewritten block (917-1218). This is very likely to
+produce a direct line-level merge conflict, and even if resolved
+automatically, the exact line 1019 target needs to be re-verified
+against Ashwin's rewritten version of the file.
+
+--------------------------------------------------------------
+3.2 routes/ai.py
+--------------------------------------------------------------
+JAI reports (lines 254, 264, 288, 292, 508):
+  - Added pdf_display_name logic for company research PDF export
+    filenames.
+  - Increased agentspace chat max_tokens from 1500 to 4096 (line 508).
+
+ASHWIN reports (lines 377-394):
+  - Added agentspace_system_prompt with conversational/clarifying
+    behavior instructions, inserted before/into existing system
+    messages.
+
+Risk: MEDIUM - the two changes are logically independent (filename
+generation vs. system prompt), but Ashwin's insertion at lines 377-394
+(roughly 17+ lines) occurs before Jai's line 508 change, meaning Jai's
+"line 508" max_tokens edit will shift to a different line number once
+both changes are combined. Not a content conflict, but requires
+re-locating the edit after merge rather than assuming line 508 is
+still correct.
+
+--------------------------------------------------------------
+3.3 static/js/views/prospecting.js
+--------------------------------------------------------------
+JAI reports (lines 317-328, 1345-1402, 3763-3766, ~3839, 4143-4153,
+4227, 4269, 4489-4543, 4682, 4887, 5082-5086, 5206-5278, 5302-5304,
+5372-5389, ~5492, 5677-5685, ~6142-6170, ~6894):
+  - Added prospectNormalizeUrl().
+  - Removed Hours/Status/Match Score/Fit Rating fields from geo result
+    cards and copied details.
+  - Replaced raw log text area with structured step-by-step progress
+    UI (updateGeoProgress with icons).
+  - Added job-status-aware rendering (applyGeoJobToUi, 
+    renderGeoResultsTable now takes jobStatus).
+  - Added running-job warning before allowing CRM add.
+  - Website/phone/email display cleanup and normalization.
+  - Removed "Complete live details" research log panel.
+
+ASHWIN reports (lines 1-75, 81-123, plus broad formatting cleanup
+across the file):
+  - Added prospecting job-state fields (active OCR/geo/research jobs).
+  - Added sessionStorage keys and restore logic for active geo/research
+    jobs across navigation/refresh.
+  - Added saveGeoJobSession() and saveResearchJobSession().
+  - Notes that most of the file's large diff is blank-line/formatting
+    cleanup rather than isolated features.
+
+Risk: MEDIUM-HIGH - both make substantial, non-trivial changes to the
+same very large file, in different functional areas (Jai: UI display/
+cleanup of geo results and progress; Ashwin: job-state persistence via
+sessionStorage). These could plausibly coexist, but given the size and
+density of both diffs (and Ashwin's own note that formatting churn
+makes the diff hard to read), this file needs a careful manual/guided
+merge rather than a blind combination of both diffs.
+
+==================================================================
+SECTION 4: NO CONFLICT - SAFE, INDEPENDENT ADDITIONS
+==================================================================
+
+4.1 Debug/scratch files
+  - Jai added: scratch_check.py, scratch_check_app.py (untracked
+    developer debug helpers for inspecting geo interactions).
+  - Ashwin added: prospectiq_history_corrupt.bak (untracked backup
+    file).
+  - These are different untracked files; no collision.
+
+4.2 Ashwin-only work (not touched by Jai's report at all)
+  - schema.sql / supabase_schema.sql: new permissions, roles, and
+    role_permissions tables; password_hash and role_id on users.
+  - migrate.py: migration logic for the above RBAC model.
+  - routes/auth.py: role seeding, permission lookups, admin dashboard
+    (flagged by Ashwin as formatting-only after filtering, but
+    functionally supports the schema/migration work).
+  - routes/companies.py: tenant-ID correctness fixes, automatic
+    contact extraction from descriptive notes, notes/activity history
+    preservation.
+  - services/tool_router.py: CRM-vs-Regional-Prospecting routing
+    heuristics.
+  - static/js/components/inline_assistant.js, static/js/app.js,
+    templates/index.html, static/js/views/profile.js,
+    static/js/views/mockups.js, static/styles.css: workspace
+    navigation/scrolling, command textarea, password visibility
+    toggle, removal of unused Media & Videos tab, Settings/Admin page
+    redesign.
+
+4.3 Jai-only work (not touched by Ashwin's report at all)
+  - The specific stage-label wording, N/A normalization logic, and
+    haiku model swaps described in Section 1 are functionally unique
+    to Jai's report; Ashwin's report contains no equivalent feature
+    work for these areas.
+
+4.4 Self-referential documentation files
+  - JAI.txt (Jai's own summary) and ASHWIN.txt (Ashwin's own summary)
+    are each just the authoring document itself; not a code conflict.
+
+==================================================================
+SECTION 5: SUMMARY TABLE
+==================================================================
+
+File                                  | Conflict Level | Type
+---------------------------------------------------------------
+services/ai_service.py                | CRITICAL        | Contradictory
+services/export_service.py            | CRITICAL        | Contradictory
+services/geo_search.py                | CRITICAL        | Contradictory
+services/ocr.py                       | CRITICAL        | Contradictory
+static/js/views/learning.js           | CRITICAL        | Contradictory
+requirements.txt                      | HIGH            | Contradictory
+routes/command.py                     | HIGH            | Line collision
+routes/ai.py                          | MEDIUM          | Line drift
+static/js/views/prospecting.js        | MEDIUM-HIGH     | Overlapping features
+Debug/scratch files                   | NONE            | Independent
+Ashwin-only files (auth/RBAC, UI nav) | NONE            | Independent
+Jai-only feature wording              | NONE            | Independent
+
+==================================================================
+SECTION 6: RECOMMENDATIONS
+==================================================================
+
+1. Before merging, confirm which of the two working trees is actually
+   up to date. The contradictory reports in Section 1 strongly suggest
+   Ashwin's tree does not include Jai's changes to ai_service.py,
+   export_service.py, geo_search.py, ocr.py, and learning.js (and the
+   requirements.txt dependencies those changes rely on).
+
+2. Do NOT merge/overwrite using Ashwin's version of the five Section 1
+   files and requirements.txt without first checking for Jai's changes
+   - doing so would silently delete real feature work (geo search
+   prompt/model changes, export cleanup, OCR model upgrade, learning
+   page polling/modals).
+
+3. For routes/command.py, apply Ashwin's larger rewrite first, then
+   manually re-locate and re-apply Jai's max_tokens change (originally
+   at line 1019) inside the updated file, since the surrounding code
+   will have shifted.
+
+4. For routes/ai.py, apply both changes, but re-verify the exact line
+   for the max_tokens increase after Ashwin's system-prompt insertion
+   shifts the file.
+
+5. For static/js/views/prospecting.js, perform a manual side-by-side
+   merge rather than a blind diff-apply, since both contributors made
+   large, non-overlapping-in-purpose but overlapping-in-location
+   changes to the same file.
+
+6. Once merged, re-run the whitespace-filtered diff process Ashwin used
+   against the final combined tree to confirm all of Jai's functional
+   changes are still present and were not filtered out as "formatting
+   only."
+
+End of report.

DEPLOYMENT_AZURE.md

@@ -0,0 +1,274 @@
+# Deploy ProspectIQ on Azure
+
+ProspectIQ should be deployed as a Docker container on Azure because the app needs Flask, Celery, Redis, Chromium, and ChromeDriver in the runtime.
+
+Recommended Azure service: **Azure Container Apps**.
+
+This repo's `Dockerfile` already installs Chromium/ChromeDriver and starts:
+
+- Redis, when `REDIS_URL` points to local Redis
+- Celery worker
+- Gunicorn on port `7860`
+
+## Important Production Notes
+
+- Keep replicas at `1` for this current Docker setup. Redis runs inside the container, so multiple replicas would not share queued job state.
+- Use Supabase/Postgres for persistent database state. Do not rely on local SQLite on Azure.
+- Do not commit `.env` files or API keys. Add secrets in Azure.
+- Use at least `2 CPU / 4 GiB` memory because Chromium and Gemini jobs can be heavy.
+
+## Required Environment Variables
+
+Add these in Azure as secrets or environment variables:
+
+```text
+SUPABASE_DB_HOST
+SUPABASE_DB_NAME
+SUPABASE_DB_USER
+SUPABASE_DB_PASSWORD
+SUPABASE_DB_PORT
+GEMINI_API_KEY_prime_1
+GEMINI_API_KEY_prime_2
+GEMINI_API_KEY_prime_3
+OPENROUTER_API_KEY
+PORT=7860
+WEBSITES_PORT=7860
+REDIS_URL=redis://127.0.0.1:6379/0
+CELERY_BROKER_URL=redis://127.0.0.1:6379/0
+CELERY_RESULT_BACKEND=redis://127.0.0.1:6379/0
+WEB_CONCURRENCY=1
+WEB_TIMEOUT=300
+CELERY_WORKER_POOL=solo
+CELERY_WORKER_CONCURRENCY=1
+COMPANY_EXTRACTOR_MAX_PARALLEL_SEARCHES=2
+```
+
+## Option A: Azure Container Apps
+
+Install prerequisites:
+
+- Docker Desktop
+- Azure CLI
+
+Login:
+
+```powershell
+az login
+az extension add --name containerapp --upgrade
+```
+
+Set names. Azure Container Registry names must be globally unique and use only letters/numbers.
+
+```powershell
+$RG="prospectiq-rg"
+$LOC="eastus"
+$APP="prospectiq"
+$ENV="prospectiq-env"
+$ACR="prospectiqacr$((Get-Random -Minimum 10000 -Maximum 99999))"
+```
+
+Create Azure resources:
+
+```powershell
+az group create --name $RG --location $LOC
+az acr create --resource-group $RG --name $ACR --sku Basic --admin-enabled true
+az containerapp env create --name $ENV --resource-group $RG --location $LOC
+```
+
+Build and push the image:
+
+```powershell
+$IMAGE="$ACR.azurecr.io/prospectiq:latest"
+az acr login --name $ACR
+docker build -t $IMAGE .
+docker push $IMAGE
+```
+
+Get registry credentials:
+
+```powershell
+$ACR_USER=$(az acr credential show --name $ACR --query username -o tsv)
+$ACR_PASS=$(az acr credential show --name $ACR --query "passwords[0].value" -o tsv)
+```
+
+Create the Container App. Replace the placeholder values before running:
+
+```powershell
+az containerapp create `
+  --name $APP `
+  --resource-group $RG `
+  --environment $ENV `
+  --image $IMAGE `
+  --target-port 7860 `
+  --ingress external `
+  --cpu 2 `
+  --memory 4Gi `
+  --min-replicas 1 `
+  --max-replicas 1 `
+  --registry-server "$ACR.azurecr.io" `
+  --registry-username $ACR_USER `
+  --registry-password $ACR_PASS `
+  --secrets `
+    supabase-db-password="YOUR_SUPABASE_PASSWORD" `
+    gemini-api-key-prime-1="YOUR_GEMINI_API_KEY_prime_1" `
+    gemini-api-key-prime-2="YOUR_GEMINI_API_KEY_prime_2" `
+    gemini-api-key-prime-3="YOUR_GEMINI_API_KEY_prime_3" `
+    openrouter-api-key="YOUR_OPENROUTER_API_KEY" `
+  --env-vars `
+    SUPABASE_DB_HOST="YOUR_SUPABASE_HOST" `
+    SUPABASE_DB_NAME="postgres" `
+    SUPABASE_DB_USER="postgres" `
+    SUPABASE_DB_PASSWORD=secretref:supabase-db-password `
+    SUPABASE_DB_PORT="6543" `
+    GEMINI_API_KEY_prime_1=secretref:gemini-api-key-prime-1 `
+    GEMINI_API_KEY_prime_2=secretref:gemini-api-key-prime-2 `
+    GEMINI_API_KEY_prime_3=secretref:gemini-api-key-prime-3 `
+    OPENROUTER_API_KEY=secretref:openrouter-api-key `
+    PORT="7860" `
+    WEBSITES_PORT="7860" `
+    REDIS_URL="redis://127.0.0.1:6379/0" `
+    CELERY_BROKER_URL="redis://127.0.0.1:6379/0" `
+    CELERY_RESULT_BACKEND="redis://127.0.0.1:6379/0" `
+    WEB_CONCURRENCY="1" `
+    WEB_TIMEOUT="300" `
+    CELERY_WORKER_POOL="solo" `
+    CELERY_WORKER_CONCURRENCY="1" `
+    COMPANY_EXTRACTOR_MAX_PARALLEL_SEARCHES="2"
+```
+
+Get the public URL:
+
+```powershell
+az containerapp show --name $APP --resource-group $RG --query properties.configuration.ingress.fqdn -o tsv
+```
+
+View logs:
+
+```powershell
+az containerapp logs show --name $APP --resource-group $RG --follow
+```
+
+Update after future code changes:
+
+```powershell
+docker build -t $IMAGE .
+docker push $IMAGE
+az containerapp update --name $APP --resource-group $RG --image $IMAGE
+```
+
+## Option B: Azure App Service for Containers
+
+Use this only if you specifically want App Service. Container Apps is usually better for this app.
+
+Create an App Service plan and Web App:
+
+```powershell
+$RG="prospectiq-rg"
+$LOC="eastus"
+$PLAN="prospectiq-plan"
+$WEBAPP="prospectiq-$((Get-Random -Minimum 10000 -Maximum 99999))"
+$ACR="YOUR_ACR_NAME"
+$IMAGE="$ACR.azurecr.io/prospectiq:latest"
+
+az appservice plan create --name $PLAN --resource-group $RG --location $LOC --is-linux --sku B2
+az webapp create --resource-group $RG --plan $PLAN --name $WEBAPP --deployment-container-image-name $IMAGE
+az webapp config appsettings set --resource-group $RG --name $WEBAPP --settings WEBSITES_PORT=7860 PORT=7860 WEB_CONCURRENCY=1 WEB_TIMEOUT=300
+```
+
+Then add the same Supabase/API key settings in:
+
+Azure Portal -> App Service -> Settings -> Environment variables.
+
+## Health Check
+
+After deployment, test:
+
+- Open the Azure URL.
+- Run OCR with a small image.
+- Run Geo Finder with a simple query.
+- Run Company Extractor with a known company.
+- Check logs if any job remains queued.
+
+## Scaling Later
+
+For heavier production usage, split the app into separate services:
+
+- Web container: Flask/Gunicorn
+- Worker container: Celery
+- Azure Cache for Redis: shared broker/result backend
+- Supabase/Postgres: database
+
+Then you can safely increase replicas.
+
+## GitHub Actions CI/CD
+
+This repository includes `.github/workflows/deploy-azure.yml`.
+
+When run manually, the workflow:
+
+1. Builds the Docker image from `Dockerfile`.
+2. Pushes the image to Azure Container Registry.
+3. Updates the Azure Container App to a new revision.
+
+Current Azure resources used by the workflow:
+
+```text
+Resource group: ProspectIQ_centralindia
+Container app: prospectiq
+Container registry: prospectiqacr57421.azurecr.io
+Image: prospectiq
+```
+
+Add these GitHub repository secrets:
+
+```text
+ACR_USERNAME
+ACR_PASSWORD
+AZURE_CREDENTIALS
+```
+
+Get ACR credentials from Azure CLI:
+
+```powershell
+az acr credential show --name prospectiqacr57421 --query username -o tsv
+az acr credential show --name prospectiqacr57421 --query "passwords[0].value" -o tsv
+```
+
+`AZURE_CREDENTIALS` must be the JSON output from a service principal with Contributor access to the resource group:
+
+```powershell
+$scope = az group show --name ProspectIQ_centralindia --query id -o tsv
+az ad sp create-for-rbac `
+  --name prospectiq-github-actions `
+  --role Contributor `
+  --scopes $scope `
+  --json-auth
+```
+
+If Azure returns `Insufficient privileges to complete the operation`, your tenant does not allow your account to create service principals. Ask an Azure/Entra admin to either:
+
+- create the service principal and give you the JSON for `AZURE_CREDENTIALS`, or
+- temporarily grant your user permission to register applications.
+
+After secrets are set, run the workflow manually from:
+
+```text
+GitHub -> Actions -> Deploy to Azure Container Apps -> Run workflow
+```
+
+### No-Admin Deployment Path
+
+If your Azure tenant blocks service-principal creation, you cannot fully automate Azure updates from GitHub Actions because GitHub has no Azure identity. Use the local deployment script instead:
+
+```powershell
+git pull origin main
+.\scripts\deploy-azure.ps1
+```
+
+This uses your local `az login` session and Docker Desktop to:
+
+1. Build the image.
+2. Push it to `prospectiqacr57421.azurecr.io`.
+3. Update the Azure Container App.
+
+This is not fully automatic, but it works without admin help.

DEPLOYMENT_HUGGINGFACE.md

@@ -0,0 +1,82 @@
+# Hugging Face Spaces Docker Deployment
+
+This app is configured for a Hugging Face Docker Space.
+
+Hugging Face Docker Spaces expose port `7860` by default. The Space metadata is in `README.md`.
+
+## Important Limitations
+
+- Spaces run a single Docker container, so Redis, Celery, and Flask run as processes inside one container.
+- Free Spaces storage is not a production database. Use Supabase/Postgres for real data.
+- Headless Chromium is installed in the Docker image for Company Extractor.
+- Long-running browser/search jobs can still hit platform resource limits on free hardware.
+
+## Create The Space
+
+1. Go to Hugging Face.
+2. Create a new Space.
+3. Choose SDK: `Docker`.
+4. Choose visibility.
+5. Clone the Space repository locally.
+
+## Push This Project To The Space
+
+From this project folder:
+
+```bash
+git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+git push hf main
+```
+
+If the remote already exists:
+
+```bash
+git remote set-url hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+git push hf main
+```
+
+## Add Secrets
+
+In the Space, go to Settings -> Variables and secrets -> New secret.
+
+Add the secrets you need:
+
+```text
+SUPABASE_DB_HOST
+SUPABASE_DB_NAME
+SUPABASE_DB_USER
+SUPABASE_DB_PASSWORD
+SUPABASE_DB_PORT
+GEMINI_API_KEY_prime_1
+GEMINI_API_KEY_prime_2
+GEMINI_API_KEY_prime_3
+OPENROUTER_API_KEY
+GROQ_API_KEY
+PINECONE_API_KEY
+SUPABASE_URL
+SUPABASE_KEY
+```
+
+Minimum for Company Extractor:
+
+```text
+SUPABASE_DB_HOST
+SUPABASE_DB_PASSWORD
+GEMINI_API_KEY_prime_1
+GEMINI_API_KEY_prime_2
+GEMINI_API_KEY_prime_3
+```
+
+Minimum for OpenRouter-backed features:
+
+```text
+OPENROUTER_API_KEY
+```
+
+## Database
+
+Use Supabase/Postgres. Run `supabase_schema.sql` in the Supabase SQL editor before first use.
+
+## Logs
+
+After pushing, open the Space build/runtime logs. A healthy start should show Gunicorn binding to port `7860` and Celery starting.

Dockerfile

@@ -0,0 +1,37 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONPATH=/app
+ENV CHROME_BIN=/usr/bin/chromium
+ENV CHROMEDRIVER_PATH=/usr/bin/chromedriver
+ENV PORT=7860
+ENV WEBSITES_PORT=7860
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    chromium \
+    chromium-driver \
+    fonts-liberation \
+    libasound2 \
+    libatk-bridge2.0-0 \
+    libgbm1 \
+    libgtk-3-0 \
+    libnss3 \
+    libxss1 \
+    redis-server \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN chmod +x /app/start-hf-space.sh
+
+EXPOSE 7860
+
+CMD ["/app/start-hf-space.sh"]

JAI.txt

@@ -0,0 +1,207 @@
+Codebase Changes Summary
+========================
+
+This file documents the current uncommitted changes found in the working tree.
+It includes what changed, what the change does, and the main line numbers involved.
+
+1. requirements.txt
+-------------------
+Lines involved: 142-147
+
+Changes made:
+- Added these dependencies:
+  - unstructured[xlsx]
+  - pandas
+  - networkx
+  - supabase
+  - ddgs
+  - langchain-excel-loader
+
+What it does:
+- Adds package support for spreadsheet/document ingestion, data processing, graph logic,
+  Supabase integration, DuckDuckGo search, and Excel loading through LangChain.
+
+2. routes/ai.py
+---------------
+Lines involved: 254, 264, 288, 292, 508
+
+Changes made:
+- Added pdf_display_name initialization at line 254.
+- Reads the job title into pdf_display_name at line 264.
+- Builds the exported PDF filename from the searched company/job title, folder name, or file stem at line 288.
+- Uses that generated filename in send_file at line 292.
+- Increased agentspace chat max_tokens from 1500 to 4096 at line 508.
+
+What it does:
+- Company research PDFs now download with a clearer name like "<Company> Company Research".
+- Agentspace chat responses can be longer before being cut off.
+
+3. routes/command.py
+--------------------
+Lines involved: 1019
+
+Changes made:
+- Increased max_tokens from 1000 to 4096.
+
+What it does:
+- Command-generated AI responses can return longer outputs.
+
+4. services/ai_service.py
+-------------------------
+Lines involved: 771-780
+
+Changes made:
+- Replaced the generic geo pipeline log message with friendly stage labels:
+  - Input parsed
+  - Fetching maps
+  - Fetching internet
+  - Verifying
+  - Verifying URLs
+  - Ranking
+
+What it does:
+- The geo search progress UI receives cleaner, user-readable status messages instead of raw internal step names.
+
+5. services/export_service.py
+-----------------------------
+Lines involved: 211-238, 244, 247-248, 253-267, 334, 691-710
+
+Changes made:
+- Added standardize_na() at lines 211-222.
+- Added get_geo_contact() at lines 224-238.
+- Website export now normalizes invalid or missing values to "N/A" at line 244.
+- Phone and Email export columns now use cleaned contact extraction at lines 247-248.
+- Removed Match Score, Operating Hours, Operational Status, Legitimacy Label, and All Available Details from the preferred geo export table.
+- Added mapped_or_dropped_keys at lines 253-260 to prevent dropped/mapped fields from being duplicated as extra columns.
+- Removed the Operating Hours Excel column width entry at old line 301.
+- Added Unicode replacement/cleanup before profile PDF generation at lines 691-710.
+
+What it does:
+- Geo exports are cleaner and now separate phone and email correctly, including cases where an email was mixed into the phone field.
+- Placeholder text like "not found", "dead link", "removed", or "not directly listed" is converted to "N/A".
+- Exported spreadsheets avoid duplicate or unwanted fields.
+- Profile PDFs avoid black square glyphs by replacing unsupported Unicode characters before rendering.
+
+6. services/geo_search.py
+-------------------------
+Lines involved: 42-43, 68-69, 87, 119-130, 285-286, 473-474, 624-647
+
+Changes made:
+- Prompt instructions now ask separately for Phone number and Email address at lines 42-43 and 68-69.
+- Removed operating hours and operational status from requested geo output.
+- Updated filtering guidance at line 87 so companies are not removed too aggressively just because headquarters may be outside the searched city.
+- Removed Match score from the final ranking format.
+- Added Full address, Phone number, Email, and Services/products fields to the required final output at lines 118-123.
+- Added stricter rules at lines 129-130 for location mismatches and for using "N/A" when website, phone, or email are unavailable.
+- Switched some Claude calls from sonnet to claude-haiku-4-5 at lines 285 and 473.
+- Increased related max_tokens values to 4096 at lines 286, 474, and 629.
+- Added continuation handling for judge output at lines 624-647, retrying when the model stops because of max_tokens.
+- Added fallback text "[Judge AI returned no output]" when judge output is empty.
+
+What it does:
+- Geo search should return more complete contact details, cleaner missing values, and fewer wrongly discarded businesses.
+- Ranking output is less likely to be truncated.
+- AI calls are adjusted to use haiku with larger response limits.
+
+7. services/ocr.py
+------------------
+Lines involved: 146-147
+
+Changes made:
+- Changed the OCR model from claude-3-5-sonnet-20241022 to claude-haiku-4-5.
+- Increased max_tokens from 1024 to 4096.
+
+What it does:
+- Business card extraction now uses the newer haiku model and allows longer OCR extraction output.
+
+8. static/js/views/learning.js
+------------------------------
+Lines involved: 14-15, 103-105, 110-153, 268-354, 390-408, 421-436, 440-456, 487-505, 683-730, 755-760
+
+Changes made:
+- Added processingTaskIds and pollingTimer state at lines 14-15.
+- Added api.checkTaskStatus() at lines 103-105.
+- Added startPollingTasks() at lines 110-153.
+- Added custom Bootstrap confirm modal at lines 268-309.
+- Added custom Bootstrap error modal at lines 312-354.
+- Replaced browser confirm() deletion prompts with custom modals for:
+  - Collection deletion at lines 390-408.
+  - Document deletion at lines 440-456.
+  - Chat session deletion at lines 487-505.
+- Added loading spinners and disabled states while delete actions are running.
+- Documents with 0 pages and 0 chunks now display as "Processing..." with a spinner at lines 421-436.
+- Upload progress text changed from "Indexing documents..." to "Uploading documents..." at line 687.
+- Upload flows now collect returned background task IDs at lines 683-730.
+- URL upload task IDs are also tracked at lines 755-760.
+
+What it does:
+- The Learning page now handles background document/video/URL indexing more gracefully.
+- Users see processing status instead of stale document counts.
+- Delete actions feel safer and clearer because they use styled modals and loading states.
+- The page automatically refreshes documents and collections when background processing finishes.
+
+9. static/js/views/prospecting.js
+---------------------------------
+Lines involved: 317-328, 1345-1402, 3763-3766, 3839 old line, 4143-4153, 4227, 4269, 4489-4543, 4682, 4887, 5082-5086, 5206-5278, 5302-5304, 5372-5389, 5492 old block, 5677-5685, 6142-6170 old lines, 6894 old block
+
+Changes made:
+- Added prospectNormalizeUrl() at lines 317-328.
+- Removed Hours and Status detail rows from geo result cards around old lines 1345-1358.
+- Removed Match score pill display around old line 1395.
+- Replaced raw geo runner log text area with a structured step container at lines 3763-3766.
+- Removed Fit Rating column around old line 3839.
+- Geo search startup now renders structured progress steps at lines 4143-4153.
+- Error, interruption, and stop messages now append as HTML alert rows instead of plain text at lines 4227, 4269, 4887, and 5082-5086.
+- updateGeoProgress() now renders step-by-step status with icons for Input parsed, Fetching maps, Fetching internet, Verifying, and Ranking at lines 4489-4543.
+- applyGeoJobToUi() now passes job.status into renderGeoResultsTable() at line 4682.
+- renderGeoResultsTable() now accepts jobStatus at line 5206.
+- Running or queued geo jobs now show a warning not to add companies to CRM until the pipeline finishes at lines 5262-5278.
+- Website values are normalized and invalid website text is converted to "N/A" at lines 5302-5304.
+- Phone/email cleanup now extracts emails mistakenly placed in the phone field and normalizes invalid placeholders at lines 5372-5389.
+- Removed rating table cell block around old line 5492.
+- Website display now hides the protocol in link text while keeping the full href at line 5677.
+- Added Email detail display with mailto link at lines 5683-5685.
+- Removed Operating Hours and Operational Status detail blocks around old lines 5672-5703.
+- Removed Match Score and Operating Hours from copied company details around old lines 6142-6170.
+- Removed the "Complete live details" research log panel around old line 6894.
+
+What it does:
+- The Prospecting geo UI is simplified and focused on useful CRM fields.
+- Progress is shown as readable pipeline steps instead of noisy raw logs.
+- Users are warned while results are still running so incomplete companies are not added too early.
+- Website, phone, and email fields are cleaner and safer to display/export.
+- Removed fields that were either noisy, duplicated, or no longer part of the geo output format.
+
+10. scratch_check.py
+--------------------
+Lines involved: 1-24
+
+Changes made:
+- Added an untracked scratch script that opens interactions.db directly with sqlite3.
+- It prints recent geo logs, output_json result preview, and stage previews.
+
+What it does:
+- Helps manually inspect the latest geo interaction stored in the local SQLite database.
+- This appears to be a developer/debug helper and is not integrated into the app.
+
+11. scratch_check_app.py
+------------------------
+Lines involved: 1-26
+
+Changes made:
+- Added an untracked scratch script that imports db_list_interactions from services.ai_service.
+- It prints the latest geo interaction title, status, result, and stage previews.
+
+What it does:
+- Helps inspect the latest geo interaction through the app service layer instead of raw sqlite3.
+- This also appears to be a developer/debug helper and is not integrated into the app.
+
+12. JAI.txt
+-----------
+Lines involved: entire file
+
+Changes made:
+- Added this change summary document.
+
+What it does:
+- Documents the current working tree changes, their purpose, and the relevant file line numbers.

README.md

@@ -0,0 +1,26 @@
+---
+title: ProspectIQ
+emoji: 📇
+colorFrom: blue
+colorTo: gray
+sdk: docker
+app_port: 7860
+---
+
+# ProspectIQ
+
+Flask CRM and prospecting workspace packaged as a Hugging Face Docker Space.
+
+The Docker container starts:
+
+- Flask via Gunicorn
+- Celery worker
+- Redis for local queueing
+- Chromium/ChromeDriver for Company Extractor headless browser search
+
+Configure API keys and database credentials in the Space settings as Secrets.
+
+## Deployment
+
+- Hugging Face Spaces: see `DEPLOYMENT_HUGGINGFACE.md`
+- Azure: see `DEPLOYMENT_AZURE.md`

app.py

@@ -0,0 +1,54 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from flask import Flask, render_template
+from pathlib import Path
+from db import init_db
+
+from routes.companies import companies_bp
+from routes.contacts import contacts_bp
+from routes.command import command_bp
+from routes.system import stages_bp, activities_bp, stats_bp, columns_bp, settings_bp, bootstrap_bp
+from routes.ai import ai_bp
+from routes.learning import learning_bp
+from routes.stt import stt_bp
+from routes.auth import auth_bp
+
+app = Flask(__name__)
+app.secret_key = os.environ.get("SECRET_KEY", "prospectiq_secure_dev_session_key_98765")
+
+from db import init_db, is_supabase_active, sync_postgres_sequences
+# Ensure database is initialized
+if not is_supabase_active():
+    db_file = Path(__file__).resolve().parent / "prospectiq.db"
+    if not db_file.exists() or db_file.stat().st_size == 0:
+        init_db()
+else:
+    sync_postgres_sequences()
+
+@app.route("/")
+def index():
+    return render_template("index.html")
+
+# Register Blueprints
+app.register_blueprint(auth_bp, url_prefix='/api/auth')
+app.register_blueprint(companies_bp, url_prefix='/api/companies')
+app.register_blueprint(contacts_bp, url_prefix='/api/contacts')
+app.register_blueprint(stages_bp, url_prefix='/api/stages')
+app.register_blueprint(activities_bp, url_prefix='/api/notes')
+app.register_blueprint(stats_bp, url_prefix='/api/stats')
+app.register_blueprint(columns_bp, url_prefix='/api')
+app.register_blueprint(settings_bp, url_prefix='/api/settings')
+app.register_blueprint(command_bp, url_prefix='/api/command')
+
+# Register AI Blueprint
+app.register_blueprint(ai_bp)
+app.register_blueprint(learning_bp, url_prefix='/api/learning')
+app.register_blueprint(bootstrap_bp, url_prefix='/api/bootstrap')
+app.register_blueprint(stt_bp)
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 5000))
+    app.run(host="0.0.0.0", port=port, debug=True)

celery_app.py

@@ -0,0 +1,21 @@
+import os
+import sys
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Add the project root to the Python path so Celery can find the 'services' module
+sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))
+
+from celery import Celery
+
+redis_url = os.environ.get("REDIS_URL", "redis://127.0.0.1:6379/0")
+broker_url = os.environ.get("CELERY_BROKER_URL", redis_url)
+backend_url = os.environ.get("CELERY_RESULT_BACKEND", redis_url)
+
+celery_app = Celery(
+    "prospectiq_tasks",
+    broker=broker_url,
+    backend=backend_url,
+    include=["tasks"]
+)

db.py

@@ -0,0 +1,689 @@
+import sqlite3
+import os
+from pathlib import Path
+import psycopg2
+from psycopg2 import pool
+
+DB_PATH = Path(__file__).resolve().parent / "prospectiq.db"
+SCHEMA_PATH = Path(__file__).resolve().parent / "schema.sql"
+
+# Global PG Connection Pool
+pg_pool = None
+
+def init_pg_pool():
+    global pg_pool
+    if pg_pool is not None:
+        return
+
+    host = os.environ.get("SUPABASE_DB_HOST") or ""
+    db = os.environ.get("SUPABASE_DB_NAME", "postgres")
+    user = os.environ.get("SUPABASE_DB_USER", "postgres")
+    password = os.environ.get("SUPABASE_DB_PASSWORD") or ""
+    port = os.environ.get("SUPABASE_DB_PORT", "6543")
+
+    if host.strip() and password.strip():
+        try:
+            pg_pool = psycopg2.pool.ThreadedConnectionPool(
+                minconn=2,
+                maxconn=20,
+                host=host,
+                database=db,
+                user=user,
+                password=password,
+                port=port
+            )
+            print("Successfully initialized PostgreSQL connection pool.")
+        except Exception as e:
+            print(f"Error initializing PostgreSQL connection pool: {e}")
+            pg_pool = None
+
+class PostgresRow:
+    def __init__(self, data, description):
+        self._data = data
+        self._keys = [desc[0] for desc in description]
+        self._key_map = {name: i for i, name in enumerate(self._keys)}
+
+    def __getitem__(self, key):
+        if isinstance(key, int):
+            return self._data[key]
+        elif isinstance(key, str):
+            idx = self._key_map.get(key)
+            if idx is None:
+                raise KeyError(key)
+            return self._data[idx]
+        else:
+            raise TypeError("Index must be int or str")
+
+    def keys(self):
+        return self._keys
+
+    def __len__(self):
+        return len(self._data)
+
+    def __iter__(self):
+        return iter(self._keys)
+
+    def get(self, key, default=None):
+        if key in self._key_map:
+            return self[key]
+        return default
+
+class PostgresCursorWrapper:
+    def __init__(self, pg_cursor, connection):
+        self.cursor = pg_cursor
+        self.connection = connection
+        self._lastrowid = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def execute(self, sql, params=None):
+        sql = sql.replace('?', '%s')
+        sql_upper = sql.upper().strip()
+
+        if "INSERT OR REPLACE INTO INTERACTIONS" in sql_upper:
+            sql = """
+                INSERT INTO interactions (
+                    id, kind, title, status, input_json, output_json, result_text, logs_json,
+                    error, run_dir, profile_path, command_json, returncode, pid,
+                    created_at, started_at, finished_at, updated_at
+                ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON CONFLICT (id) DO UPDATE SET
+                    kind = EXCLUDED.kind,
+                    title = EXCLUDED.title,
+                    status = EXCLUDED.status,
+                    input_json = EXCLUDED.input_json,
+                    output_json = EXCLUDED.output_json,
+                    result_text = EXCLUDED.result_text,
+                    logs_json = EXCLUDED.logs_json,
+                    error = EXCLUDED.error,
+                    run_dir = EXCLUDED.run_dir,
+                    profile_path = EXCLUDED.profile_path,
+                    command_json = EXCLUDED.command_json,
+                    returncode = EXCLUDED.returncode,
+                    pid = EXCLUDED.pid,
+                    created_at = EXCLUDED.created_at,
+                    started_at = EXCLUDED.started_at,
+                    finished_at = EXCLUDED.finished_at,
+                    updated_at = EXCLUDED.updated_at
+            """
+        elif "INSERT OR IGNORE INTO" in sql_upper:
+            sql = sql.replace("INSERT OR IGNORE INTO", "INSERT INTO") + " ON CONFLICT DO NOTHING"
+
+        is_insert = sql_upper.startswith("INSERT")
+        if is_insert and "RETURNING" not in sql_upper and "ROLE_PERMISSIONS" not in sql_upper:
+            sql = sql.rstrip().rstrip(';') + " RETURNING id"
+
+        # Invalidate stage or user caches automatically on database writes
+        is_write = sql_upper.startswith("INSERT") or sql_upper.startswith("UPDATE") or sql_upper.startswith("DELETE")
+        if is_write:
+            try:
+                if "STAGES" in sql_upper:
+                    cache_delete("prospectiq:stages")
+                if "USERS" in sql_upper:
+                    cache_delete("prospectiq:users")
+            except Exception:
+                pass
+
+        if params is not None:
+            self.cursor.execute(sql, params)
+        else:
+            self.cursor.execute(sql)
+
+        self._lastrowid = None
+        if is_insert and "RETURNING" in sql.upper():
+            try:
+                row = self.cursor.fetchone()
+                if row:
+                    self._lastrowid = row[0]
+            except Exception:
+                pass
+
+        return self
+
+    def executemany(self, sql, seq_of_params):
+        sql = sql.replace('?', '%s')
+        self.cursor.executemany(sql, seq_of_params)
+        return self
+
+    def fetchone(self):
+        row = self.cursor.fetchone()
+        if row is None:
+            return None
+        return PostgresRow(row, self.cursor.description)
+
+    def fetchall(self):
+        rows = self.cursor.fetchall()
+        if not rows:
+            return []
+        desc = self.cursor.description
+        return [PostgresRow(r, desc) for r in rows]
+
+    @property
+    def rowcount(self):
+        return self.cursor.rowcount
+
+    @property
+    def lastrowid(self):
+        return self._lastrowid
+
+    def close(self):
+        self.cursor.close()
+
+class PostgresConnectionWrapper:
+    def __init__(self, pg_conn):
+        self.conn = pg_conn
+
+    def cursor(self):
+        return PostgresCursorWrapper(self.conn.cursor(), self)
+
+    def execute(self, sql, params=None):
+        cur = self.cursor()
+        cur.execute(sql, params)
+        return cur
+
+    def executemany(self, sql, seq_of_params):
+        cur = self.cursor()
+        cur.executemany(sql, seq_of_params)
+        return cur
+
+    def commit(self):
+        self.conn.commit()
+
+    def rollback(self):
+        self.conn.rollback()
+
+    def close(self):
+        global pg_pool
+        if pg_pool is not None:
+            try:
+                pg_pool.putconn(self.conn)
+            except Exception as e:
+                print(f"Error returning connection to pool: {e}")
+                try:
+                    self.conn.close()
+                except Exception:
+                    pass
+        else:
+            self.conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            if exc_type is not None:
+                self.rollback()
+            else:
+                self.commit()
+        finally:
+            self.close()
+
+def is_supabase_active() -> bool:
+    global pg_pool
+    if pg_pool is None:
+        init_pg_pool()
+    return pg_pool is not None
+
+def sync_postgres_sequence(table_name: str, column_name: str = "id"):
+    if not is_supabase_active():
+        return
+    safe_table = "".join(ch for ch in str(table_name) if ch.isalnum() or ch == "_")
+    safe_column = "".join(ch for ch in str(column_name) if ch.isalnum() or ch == "_")
+    if not safe_table or not safe_column:
+        return
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        cursor.execute(f"""
+            SELECT setval(
+                pg_get_serial_sequence('{safe_table}', '{safe_column}'),
+                COALESCE((SELECT MAX({safe_column}) FROM {safe_table}), 0) + 1,
+                false
+            )
+        """)
+        conn.commit()
+    except Exception as e:
+        conn.rollback()
+        print(f"Warning: could not sync PostgreSQL sequence for {safe_table}.{safe_column}: {e}")
+    finally:
+        conn.close()
+
+def sync_postgres_sequences():
+    if not is_supabase_active():
+        return
+    for table_name in (
+        "tenants",
+        "users",
+        "stages",
+        "companies",
+        "contacts",
+        "activities",
+        "notes",
+        "stage_changes",
+        "ai_field_values",
+    ):
+        sync_postgres_sequence(table_name)
+
+def get_db_connection():
+    global pg_pool
+    if pg_pool is None:
+        init_pg_pool()
+
+    if pg_pool is not None:
+        try:
+            conn = pg_pool.getconn()
+            conn.autocommit = False
+            return PostgresConnectionWrapper(conn)
+        except Exception as e:
+            print(f"PostgreSQL connection failed, falling back to SQLite: {e}")
+
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+def dict_from_row(row):
+    return dict(row) if row is not None else None
+
+def init_db():
+    # Execute schema
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    with open(SCHEMA_PATH, 'r') as f:
+        schema_sql = f.read()
+    cursor.executescript(schema_sql)
+    conn.commit()
+
+    # Seed stages if empty
+    cursor.execute("SELECT COUNT(*) FROM stages")
+    if cursor.fetchone()[0] == 0:
+        default_stages = [
+            ("New", 1, "#f1f5f9", "#475569"),
+            ("Shortlisted", 2, "#eff6ff", "#1d4ed8"),
+            ("Research Done", 3, "#f5f3ff", "#6d28d9"),
+            ("Contacted", 4, "#ecfdf5", "#047857"),
+            ("Engaged", 5, "#f0fdf4", "#15803d"),
+            ("Meeting Scheduled", 6, "#fffbeb", "#b45309"),
+            ("Meeting Done", 7, "#fef3c7", "#b45309"),
+            ("Proposal Sent", 8, "#faf5ff", "#7e22ce"),
+            ("Won", 9, "#d1fae5", "#065f46"),
+            ("Paused / Not a Fit", 10, "#fee2e2", "#991b1b")
+        ]
+        cursor.executemany(
+            "INSERT INTO stages (name, order_index, color_bg, color_text) VALUES (?, ?, ?, ?)",
+            default_stages
+        )
+        conn.commit()
+
+    # Seed tenant if empty
+    cursor.execute("SELECT COUNT(*) FROM tenants")
+    if cursor.fetchone()[0] == 0:
+        cursor.execute(
+            "INSERT INTO tenants (id, name, brand_color) VALUES (1, 'MapleMPSS', '#3b82f6')"
+        )
+        conn.commit()
+
+    # Seed users if empty
+    cursor.execute("SELECT COUNT(*) FROM users")
+    if cursor.fetchone()[0] == 0:
+        default_users = [
+            (1, 1, "admin1@maplempss.com", "admin1", "Admin"),
+            (2, 1, "bdrep1@maplempss.com", "bd rep1", "BD Rep"),
+            (3, 1, "viewer1@maplempss.com", "viewer1", "Viewer"),
+            (4, 1, "bdrep2@maplempss.com", "bd rep2", "BD Rep"),
+            (5, 1, "bdrep3@maplempss.com", "bd rep3", "BD Rep")
+        ]
+        cursor.executemany(
+            "INSERT INTO users (id, tenant_id, email, name, role) VALUES (?, ?, ?, ?, ?)",
+            default_users
+        )
+        conn.commit()
+
+    # Seed 10 dummy companies if empty
+    cursor.execute("SELECT COUNT(*) FROM companies")
+    if cursor.fetchone()[0] == 0:
+        # Columns:
+        # id, tenant_id, name, legal_name, website, phone, nic_code, industry,
+        # street, city, province, postal_code, country, size_staff, revenue_band, business_type,
+        # products_made, parts_sourced, current_supplier_notes, maplempss_fit_score, stage_id, assigned_rep_id,
+        # created_by, updated_by
+        dummy_companies = [
+            # 1. Tesla Inc. - Large OEM (California), Contacted stage, has 2 contacts, active call history, upcoming follow-up.
+            (1, 1, "Tesla Inc.", "Tesla Inc.", "https://www.tesla.com", "1-800-TESLA", "3711", "Automotive OEM",
+             "3500 Deer Creek Road", "Palo Alto", "California", "94304", "USA", 100000, "1B+", "OEM",
+             "Electric Vehicles, Energy Storage Systems", "Stamping parts, cast aluminum knuckles, fasteners", "Currently sources cast parts globally, looking for localized North American CNC shops.", 4.5, 4, 2, 1, 1),
+
+            # 2. Northstar Sourcing - Mid distributor (Ontario), Engaged stage, has overdue follow-up.
+            (2, 1, "Northstar Sourcing", "Northstar Sourcing Ltd.", "https://www.northstarsourcing.ca", "416-555-0199", "3327", "Aerospace Parts",
+             "100 Airport Road", "Toronto", "Ontario", "M5V 2N8", "Canada", 120, "10M-50M", "distributor",
+             "Landing gear brackets, actuator assemblies", "Bushings, sleeves, pivot pins", "Supplier in Mexico failing quality checks. Seeking backup CNC capacity in Ontario.", 4.0, 5, 2, 1, 1),
+
+            # 3. Ontario Automotive OEM - Large OEM (Ontario), New stage, single contact, no activities but has notes.
+            (3, 1, "Ontario Automotive OEM", "Ontario Automotive OEM Corp.", "https://www.ontarioautooem.ca", "519-555-0123", "3714", "Auto Parts Mfg",
+             "500 Tecumseh Rd E", "Windsor", "Ontario", "N8X 2S2", "Canada", 450, "100M-500M", "OEM",
+             "Suspension arms, links, engine mounts", "Steel forgings, CNC machined journals", "Currently single sourced. High risk due to logistics bottlenecks.", 3.5, 1, 2, 1, 1),
+
+            # 4. Apex Machining Ltd. - Small machine shop (BC), Research Done stage, 0 contacts (edge case: no contacts logged).
+            (4, 1, "Apex Machining Ltd.", None, "https://www.apexmachining.ca", None, "3327", "CNC Shop",
+             "12330 Vulcan Way", "Richmond", "British Columbia", "V6V 1J8", "Canada", 45, "1M-10M", "other",
+             "Custom hydraulic fittings, prototype valves", "Aluminum bars, brass castings", "High precision shop. Might be a sub-contracting partner, not a direct client.", 4.2, 3, 2, 1, 1),
+
+            # 5. Calgary Metal Press - Small shop, Paused/Not a Fit stage, low fit score.
+            (5, 1, "Calgary Metal Press", "Calgary Metal Pressing Co.", None, "403-555-0450", "3321", "Metal Stamping",
+             "7800 51 St SE", "Calgary", "Alberta", "T2C 4E3", "Canada", 15, "<1M", "OEM",
+             "Stamped brackets, flat washers", "Sheet metal coils", "Too small for our outsourcing program. Margins do not justify logistics. Paused.", 1.8, 10, 2, 1, 1),
+
+            # 6. Quebec Aerospace Group - Large Aerospace OEM, Won stage, multiple contacts and activities.
+            (6, 1, "Quebec Aerospace Group", "Quebec Aerospace Group Inc.", "https://www.quebecaerospace.com", "514-555-0900", "3364", "Aerospace OEM",
+             "450 Boulevard Saint-Martin O", "Laval", "Quebec", "H7M 3Y6", "Canada", 850, "500M-1B", "OEM",
+             "Turbine blades, housing rings, landing gears", "Inconel castings, titanium shafts", "Closed deal on turbine flange prototypes. Moving to production batches.", 4.8, 9, 2, 1, 1),
+
+            # 7. Precision Components India - Large global supplier, Shortlisted stage (Edge case: foreign country, fit assessment).
+            (7, 1, "Precision Components India", "Precision Components India Pvt. Ltd.", "https://www.precisioncompindia.com", "+91-120-555-0100", "3714", "Auto Parts Mfg",
+             "Sector 63, Block C", "Noida", "Uttar Pradesh", "201301", "India", 2100, "100M-500M", "OEM / distributor",
+             "Steering gears, universal joints, steering columns", "Steel bars, pinion blanks", "High volume Indian manufacturer. Assessing if logistics cost overrides sourcing discount.", 3.9, 2, 2, 1, 1),
+
+            # 8. Hamilton Gearworks - Mid OEM, Meeting Scheduled stage, upcoming meeting follow-up.
+            (8, 1, "Hamilton Gearworks", "Hamilton Industrial Gearworks Ltd.", "https://www.hamiltongear.ca", "905-555-0111", "3327", "Industrial Gears OEM",
+             "250 Gage Ave N", "Hamilton", "Ontario", "L8L 7B1", "Canada", 85, "10M-50M", "OEM",
+             "Heavy industrial gearboxes, custom splines", "Cast iron gear cases, forging blanks", "Scheduled discovery call with VP Operations to discuss gearbox housing outsourcing.", 4.1, 6, 2, 1, 1),
+
+            # 9. WestCoast Castings - Small Foundry, Meeting Done stage, pending next steps.
+            (9, 1, "WestCoast Castings", "WestCoast Foundries Ltd.", "https://www.westcoastcastings.com", "604-555-0188", "3315", "Foundry",
+             "1550 Kingsway Ave", "Port Coquitlam", "British Columbia", "V3C 6N6", "Canada", 30, "1M-10M", "OEM",
+             "Sand cast aluminum & bronze housings", "Ingots, sand molds", "Meeting completed last week. Waiting for their capacity sheet regarding 10-ton casting capacity.", 3.0, 7, 2, 1, 1),
+
+            # 10. Montreal Custom Fasteners - Micro distributor, Proposal Sent stage, follow-up due today.
+            (10, 1, "Montreal Custom Fasteners", None, None, "514-555-0133", "3327", "Fastener Distributor",
+             "890 Rue Saint-Jacques", "Montreal", "Quebec", "H3C 1H8", "Canada", 8, "<1M", "distributor",
+             "Custom sockets, micro fasteners", "Wire coils", "Proposal for standard fasteners supply sent. Decision-maker review today.", 3.6, 8, 2, 1, 1)
+        ]
+
+        cursor.executemany(
+            """INSERT INTO companies (
+                id, tenant_id, name, legal_name, website, phone, nic_code, industry,
+                street, city, province, postal_code, country, size_staff, revenue_band, business_type,
+                products_made, parts_sourced, current_supplier_notes, maplempss_fit_score, stage_id, assigned_rep_id,
+                created_by, updated_by
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            dummy_companies
+        )
+        conn.commit()
+
+        # Seed contacts
+        # Columns: company_id, first_name, last_name, title, email, phone, linkedin, is_primary
+        dummy_contacts = [
+            (1, "Elon", "Musk", "CEO", "elon@tesla.com", "1-800-TESLA", "https://linkedin.com/in/elonmusk", 0),
+            (1, "Priya", "Sharma", "VP Procurement", "priya.sharma@tesla.com", "650-555-0102", "https://linkedin.com/in/priyasharmaprocurement", 1),
+            (2, "David", "Miller", "Sourcing Manager", "david@northstarsourcing.ca", "416-555-0144", "https://linkedin.com/in/davidmillersourcing", 1),
+            (3, "Robert", "Chen", "Director of Supply Chain", "r.chen@ontarioautooem.ca", "519-555-0199", "https://linkedin.com/in/robertchensupply", 1),
+            # Company 4 has 0 contacts
+            (5, "Frank", "Glover", "Operations Manager", "frank@calgarymetalpress.com", "403-555-0451", None, 1),
+            (6, "Jean", "Dupont", "VP Procurement", "j.dupont@quebecaerospace.com", "514-555-0901", "https://linkedin.com/in/jeandupont", 1),
+            (6, "Marc", "Leclerc", "Buyer", "m.leclerc@quebecaerospace.com", "514-555-0902", None, 0),
+            (7, "Rajesh", "Kumar", "Director Sourcing", "r.kumar@precisioncompindia.com", None, None, 1),
+            (8, "Sarah", "Connor", "VP Operations", "sarah.connor@hamiltongear.ca", "905-555-0112", "https://linkedin.com/in/sarahconnor", 1),
+            (9, "Kevin", "Bacon", "Plant Manager", "kevin@westcoastcastings.com", "604-555-0189", None, 1),
+            (10, "Pierre", "Trudeau", "Owner", "pierre@montrealfasteners.com", "514-555-0134", None, 1)
+        ]
+        cursor.executemany(
+            """INSERT INTO contacts (
+                company_id, first_name, last_name, title, email, phone, linkedin, is_primary
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            dummy_contacts
+        )
+        conn.commit()
+
+        # Seed activities and notes
+        # Columns: company_id, contact_id, user_id, type, outcome, notes, next_action, next_action_date
+        dummy_activities = [
+            # Tesla - upcoming follow-up
+            (1, 2, 2, "Cold Call", "Answered", "Had a brief conversation with Priya. She requested our machinery inventory list and casting capacity details.", "Send CNC capacity list and certifications", "2026-06-25"),
+            (1, 2, 2, "Email", "Sent", "Follow-up email containing CNC capacity sheet and ISO registration certificate pdf.", None, None),
+
+            # Northstar - overdue follow-up (next action date: 2026-06-15)
+            (2, 3, 2, "Meeting", "Answered", "Discovery call completed. Discussed landing gear bushing volumes. They source 50,000 units annually. Mexico vendor experiencing major delays.", "Prepare landing gear bushing price quote", "2026-06-15"),
+
+            # Quebec Aerospace - Won
+            (6, 6, 2, "Meeting", "discovery", "Discovery call completed. Inconel flange specifications discussed.", "Prepare proposal", "2026-05-10"),
+            (6, 6, 2, "Email", "Sent", "Sent formal proposal quote for 100 prototype flanges.", None, None),
+            (6, 6, 2, "Meeting", "negotiation", "Flange proposal accepted. First prototype PO issued.", "Deliver flanges by end of July", "2026-07-31"),
+
+            # Hamilton Gearworks - upcoming follow-up (next action date: 2026-06-22)
+            (8, 9, 2, "LinkedIn Message", "Accepted", "Sarah accepted connection request. Offered to show gearbox housing capabilities.", "Scheduled discovery call on Teams for June 22nd", "2026-06-22"),
+
+            # Montreal Fasteners - due today (next action date: 2026-06-20)
+            (10, 11, 2, "Email", "Sent", "Sent quotation for custom brass socket order. Pricing valid for 30 days.", "Follow up on proposal decision", "2026-06-20")
+        ]
+        cursor.executemany(
+            """INSERT INTO activities (
+                company_id, contact_id, user_id, type, outcome, notes, next_action, next_action_date
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            dummy_activities
+        )
+        conn.commit()
+
+        # Seed notes
+        # Columns: company_id, contact_id, user_id, body, is_pinned
+        dummy_notes = [
+            (1, 2, 2, "Priya mentioned that delivery delays with current CNC supplier in Mexico are holding up their lines. Extremely high urgency.", 1),
+            (2, 3, 2, "Northstar Sourcing prefers DDP shipping terms to their warehouse in Toronto. Must build freight pricing into quote.", 0),
+            (3, 4, 2, "Windsor plant operates on a 3-shift rotation. Will require a supplier with strong backup capacity planning.", 0),
+            (4, None, 2, "Assessed website products: Apex manufactures high-end hydraulic parts. Might be better suited as a strategic partner than a direct buyer.", 0)
+        ]
+        cursor.executemany(
+            """INSERT INTO notes (
+                company_id, contact_id, user_id, body, is_pinned
+            ) VALUES (?, ?, ?, ?, ?)""",
+            dummy_notes
+        )
+        conn.commit()
+
+        # Seed initial stage_changes
+        dummy_stage_changes = [
+            (1, None, 4, 2, "manual"),
+            (2, None, 5, 2, "manual"),
+            (3, None, 1, 2, "manual"),
+            (4, None, 3, 2, "manual"),
+            (5, None, 10, 2, "manual"),
+            (6, None, 9, 2, "manual"),
+            (7, None, 2, 2, "manual"),
+            (8, None, 6, 2, "manual"),
+            (9, None, 7, 2, "manual"),
+            (10, None, 8, 2, "manual")
+        ]
+        cursor.executemany(
+            """INSERT INTO stage_changes (
+                company_id, from_stage_id, to_stage_id, changed_by_user_id, source
+            ) VALUES (?, ?, ?, ?, ?)""",
+            dummy_stage_changes
+        )
+        conn.commit()
+
+    conn.close()
+
+from flask import request
+
+def get_request_user():
+    from flask import session
+    try:
+        if 'user_id' in session:
+            return session['user_id'], session['user_role'], session['user_name']
+    except Exception:
+        pass
+
+    try:
+        user_id = request.headers.get("X-User-Id")
+        role = request.headers.get("X-User-Role")
+        name = request.headers.get("X-User-Name")
+        try:
+            user_id = int(user_id) if user_id else 2
+        except (ValueError, TypeError):
+            user_id = 2
+        role = role if role else "BD Rep"
+        name = name if name else "bd rep1"
+        return user_id, role, name
+    except Exception:
+        return 2, "BD Rep", "bd rep1"
+
+def get_request_tenant_id():
+    from flask import session
+    try:
+        if 'tenant_id' in session:
+            return session['tenant_id']
+    except Exception:
+        pass
+
+    try:
+        user_id, _, _ = get_request_user()
+        conn = get_db_connection()
+        cursor = conn.cursor()
+        cursor.execute("SELECT tenant_id FROM users WHERE id = ?", (user_id,))
+        row = cursor.fetchone()
+        conn.close()
+        if row:
+            return row[0]
+    except Exception:
+        pass
+    return 1
+
+def get_user_access_level(db_conn, user_id, user_role, company_id):
+    if user_role in ('Super Admin', 'Admin'):
+        return 'full'
+    cursor = db_conn.cursor()
+    cursor.execute("SELECT assigned_rep_id FROM companies WHERE id = ?", (company_id,))
+    row = cursor.fetchone()
+    if not row:
+        return 'none'
+    assigned_rep = row[0]
+    if user_role == 'BD Rep':
+        if assigned_rep == user_id:
+            return 'full'
+        else:
+            return 'basic'
+    if user_role == 'Viewer':
+        return 'viewer'
+    return 'basic'
+
+if __name__ == "__main__":
+    init_db()
+    print("Database initialized and 10 dummy records seeded successfully.")
+
+# =====================================================================
+# Redis Caching Utility Functions (Stage 4)
+# — With in-memory fallback when Redis is unavailable
+# =====================================================================
+import redis
+import json
+import time
+import threading
+from collections import OrderedDict
+
+redis_client = None
+_redis_last_attempt = 0
+_REDIS_RETRY_INTERVAL = 60  # seconds between Redis reconnection attempts
+_redis_fallback_warned = False
+
+# In-memory fallback cache (thread-safe, TTL-aware, LRU-eviction)
+_mem_cache = OrderedDict()  # key -> (value, expiry_timestamp)
+_mem_cache_lock = threading.Lock()
+_MEM_CACHE_MAX_SIZE = 1000
+
+def get_redis_client():
+    """Try to return a working Redis client, or None if unavailable."""
+    global redis_client, _redis_last_attempt, _redis_fallback_warned
+    if redis_client is not None:
+        return redis_client
+    now = time.time()
+    if now - _redis_last_attempt < _REDIS_RETRY_INTERVAL:
+        return None
+    _redis_last_attempt = now
+    try:
+        redis_url = (
+            os.environ.get("REDIS_URL")
+            or os.environ.get("CELERY_BROKER_URL")
+            or os.environ.get("CELERY_RESULT_BACKEND")
+            or "redis://127.0.0.1:6379/0"
+        )
+        client = redis.Redis.from_url(redis_url, decode_responses=True, socket_connect_timeout=2)
+        client.ping()
+        redis_client = client
+        if _redis_fallback_warned:
+            print("Redis cache connection restored — switching from in-memory fallback to Redis.")
+            _redis_fallback_warned = False
+        return redis_client
+    except Exception as e:
+        if not _redis_fallback_warned:
+            print(f"Warning: Redis cache unavailable ({e}). Using in-memory fallback cache.")
+            _redis_fallback_warned = True
+        redis_client = None
+    return None
+
+# --- In-memory cache helpers ---
+
+def _mem_get(key):
+    with _mem_cache_lock:
+        entry = _mem_cache.get(key)
+        if entry is None:
+            return None
+        value, expiry = entry
+        if time.time() > expiry:
+            del _mem_cache[key]
+            return None
+        # Move to end for LRU freshness
+        _mem_cache.move_to_end(key)
+        return value
+
+def _mem_set(key, value, timeout):
+    with _mem_cache_lock:
+        expiry = time.time() + timeout
+        if key in _mem_cache:
+            _mem_cache.move_to_end(key)
+        _mem_cache[key] = (value, expiry)
+        # Evict oldest entries if over capacity
+        while len(_mem_cache) > _MEM_CACHE_MAX_SIZE:
+            _mem_cache.popitem(last=False)
+
+def _mem_delete(key):
+    with _mem_cache_lock:
+        _mem_cache.pop(key, None)
+
+# --- Public cache API (same signatures as before) ---
+
+def cache_get(key):
+    client = get_redis_client()
+    if client:
+        try:
+            val = client.get(key)
+            if val:
+                return json.loads(val)
+        except Exception as e:
+            print(f"Redis cache_get error: {e}")
+    # Fallback to in-memory
+    return _mem_get(key)
+
+def cache_set(key, value, timeout=3600):
+    client = get_redis_client()
+    if client:
+        try:
+            client.setex(key, timeout, json.dumps(value))
+            return True
+        except Exception as e:
+            print(f"Redis cache_set error: {e}")
+    # Always store in memory as well (acts as fallback + L1 cache)
+    _mem_set(key, value, timeout)
+    return True
+
+def cache_delete(key):
+    client = get_redis_client()
+    if client:
+        try:
+            client.delete(key)
+        except Exception as e:
+            print(f"Redis cache_delete error: {e}")
+    _mem_delete(key)
+    return True

docker-compose.yml

@@ -0,0 +1,50 @@
+services:
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    command: redis-server --appendonly yes
+    volumes:
+      - redis_data:/data
+
+  web:
+    build: .
+    restart: unless-stopped
+    command: gunicorn app:app --bind 0.0.0.0:10000 --workers 2 --timeout 180
+    env_file:
+      - .env.production
+    environment:
+      PORT: 10000
+      REDIS_URL: redis://redis:6379/0
+      CELERY_BROKER_URL: redis://redis:6379/0
+      CELERY_RESULT_BACKEND: redis://redis:6379/0
+    ports:
+      - "80:10000"
+    depends_on:
+      - redis
+    volumes:
+      - prospectiq_settings:/app/settings
+      - prospectiq_learning_data:/app/learning_data
+      - prospectiq_research_output:/app/services/research/pipe_output
+
+  worker:
+    build: .
+    restart: unless-stopped
+    command: celery -A celery_app.celery_app worker --loglevel=info
+    env_file:
+      - .env.production
+    environment:
+      REDIS_URL: redis://redis:6379/0
+      CELERY_BROKER_URL: redis://redis:6379/0
+      CELERY_RESULT_BACKEND: redis://redis:6379/0
+    depends_on:
+      - redis
+    volumes:
+      - prospectiq_settings:/app/settings
+      - prospectiq_learning_data:/app/learning_data
+      - prospectiq_research_output:/app/services/research/pipe_output
+
+volumes:
+  redis_data:
+  prospectiq_settings:
+  prospectiq_learning_data:
+  prospectiq_research_output:

documentation.md

@@ -0,0 +1,666 @@
+# ProspectIQ Product Guide & Investor Proposal
+
+## Executive Summary
+
+ProspectIQ is an AI-assisted prospecting and sales workspace that helps a business development team find companies, capture leads, manage contacts, track follow-ups, and move opportunities through a pipeline.
+
+It is built for the daily reality of sales work: leads come from many places, notes get scattered, follow-ups are missed, and research takes too long. ProspectIQ brings that work into one clear system. A user can scan a business card, discover companies by location, research a target account, add contacts, track the pipeline, generate outreach support, and keep all activity connected to the right company.
+
+For investors, ProspectIQ is positioned as a practical AI business tool, not a generic chatbot. It gives teams a working operating system for prospecting: capture the lead, understand the lead, prioritize the lead, act on the lead, and preserve the learning for future sales decisions.
+
+---
+
+## Product Snapshot
+
+![ProspectIQ Dashboard](docs/images/dashboard.png)
+
+ProspectIQ gives users one workspace for:
+
+- Managing companies and contacts.
+- Tracking sales stages visually.
+- Capturing business cards and documents.
+- Finding nearby or category-specific prospects.
+- Researching companies.
+- Chatting with an AI assistant that can use company context.
+- Scheduling tasks and follow-ups.
+- Reviewing activity history.
+- Preparing better outreach.
+
+The product is designed to be easy to understand for everyday users while still deep enough for serious sales operations.
+
+---
+
+## The Problem ProspectIQ Solves
+
+Sales and business development teams often work across too many disconnected tools:
+
+- A spreadsheet for leads.
+- A phone gallery full of business cards.
+- A notes app for meeting comments.
+- Google Maps for local discovery.
+- Email drafts in inboxes.
+- A CRM that is often incomplete.
+- A separate AI chatbot that does not know the customer data.
+
+This causes three expensive problems.
+
+### 1. Lead Data Gets Lost
+
+A promising contact from a trade show, meeting, supplier visit, or directory search may never become a proper record. Even when it does, details are often missing.
+
+### 2. Follow-Ups Become Inconsistent
+
+Without a shared view of tasks, activities, and next steps, opportunities can sit untouched. Sales momentum fades because the system does not clearly show what should happen next.
+
+### 3. Research Takes Too Much Time
+
+Before contacting a company, reps need to understand what the company does, who to speak to, why it is a good fit, and what message to send. Doing that manually for every prospect is slow.
+
+ProspectIQ solves these problems by turning scattered prospecting work into a structured, repeatable workflow.
+
+---
+
+## Who ProspectIQ Is For
+
+ProspectIQ is useful for any team that needs to build and manage a targeted B2B prospect list.
+
+Ideal users include:
+
+- Business development representatives.
+- Sales teams.
+- Founders doing outbound sales.
+- Local service businesses selling to offices or commercial sites.
+- Manufacturing, sourcing, and distribution teams.
+- Field sales teams.
+- Agencies building prospect lists for clients.
+- Managers who need visibility into pipeline activity.
+
+The strongest early market is small and mid-sized B2B teams that need more structure than a spreadsheet but want something easier and more prospecting-focused than a heavy CRM.
+
+---
+
+## How to Use ProspectIQ
+
+### Step 1: Start on the Home Dashboard
+
+The Home dashboard is the daily command center. It shows the current workspace status, active tasks, recent activity, quick actions, and a calendar view.
+
+Use it to:
+
+- Check total companies and contacts.
+- See active, won, and lost deals.
+- Review today’s tasks.
+- Add quick follow-ups.
+- Open recent company activity.
+- Jump into adding a company, importing contacts, reviewing the pipeline, or opening the learning playbook.
+
+This screen helps a user answer: “What should I pay attention to today?”
+
+![Home Dashboard](docs/images/dashboard.png)
+
+### Step 2: Search or Give a Command
+
+At the top of the app is the global command bar. It acts like one search box for the whole workspace.
+
+Users can type normal business requests such as:
+
+- “Show aerospace companies in Ontario.”
+- “Find companies in the Contacted stage.”
+- “Add a task to follow up with Northstar tomorrow.”
+- “Show companies on the board view.”
+- “Add a new company called Hamilton Gearworks.”
+
+The command bar reduces clicking and helps users move faster. Instead of remembering exactly where a feature lives, the user can say what they want to do.
+
+### Step 3: Manage Companies
+
+The Companies screen is where the main prospect list lives.
+
+Use it to:
+
+- Browse all company records.
+- Search by name, location, industry, or representative.
+- Filter companies by province, city, industry, stage, size, last touched date, or assigned rep.
+- Sort companies by name, fit score, or last activity.
+- Add a new company manually.
+- Select and delete records in bulk.
+- Add custom columns for extra information.
+- Hide or show columns depending on the current workflow.
+- Open a company profile for deeper details.
+
+![Companies Table](docs/images/companies-table.png)
+
+This view is best when the user needs a spreadsheet-like overview of the prospect list.
+
+### Step 4: Use the Pipeline Board
+
+The same company records can also be viewed as a pipeline board.
+
+Use it to:
+
+- See where every opportunity sits.
+- Review companies by stage.
+- Compare how many prospects are in each stage.
+- Identify stalled stages.
+- Focus on active opportunities.
+
+![Companies Board](docs/images/companies-board.png)
+
+The board is best when a manager or sales rep wants to understand sales movement visually.
+
+### Step 5: Open a Company Profile
+
+Clicking a company opens its profile. This is the account’s home base.
+
+Use a company profile to:
+
+- Review company details.
+- See website, phone, location, industry, staff size, and business type.
+- Check the company’s current stage.
+- View linked contacts.
+- Read notes.
+- Review outreach activity.
+- Add new notes.
+- Log calls, emails, meetings, and follow-ups.
+- Store important context about fit, sourcing signals, or customer needs.
+
+The company profile prevents account knowledge from being scattered across messages, documents, and personal memory.
+
+### Step 6: Manage Contacts
+
+The Contacts area stores the people connected to each company.
+
+Use it to:
+
+- Add new contacts.
+- Edit contact details.
+- Track title, email, phone, and LinkedIn.
+- Link each contact to a company.
+- Mark one person as the primary contact.
+- Keep decision-maker information organized.
+
+This is especially important for outreach because the quality of a sales process often depends on knowing the right person to contact.
+
+### Step 7: Track Activities and Follow-Ups
+
+ProspectIQ lets users log the work that happens around each account.
+
+Users can track:
+
+- Cold calls.
+- Emails.
+- Meetings.
+- LinkedIn messages.
+- Notes.
+- Next actions.
+- Follow-up dates.
+
+This creates a timeline of what has happened with each company. It also helps the Home dashboard surface current and upcoming actions.
+
+For a sales team, this is one of the most important habits ProspectIQ supports: every conversation should create a next step.
+
+### Step 8: Use Tasks for Daily Execution
+
+The task section helps users keep small actions visible.
+
+Use it to:
+
+- Quickly add a task.
+- Mark tasks complete.
+- Edit or delete tasks.
+- Schedule follow-ups.
+- Keep personal daily work close to the sales workspace.
+
+Tasks are useful for lightweight execution: call this person, review this account, send the proposal, update a profile, or check a meeting outcome.
+
+### Step 9: Capture Business Cards with OCR
+
+The OCR tool turns a business card or image document into usable sales data.
+
+Use it when:
+
+- A rep receives a business card at a meeting.
+- A user has an image with contact details.
+- A company and contact need to be added quickly.
+
+How it works from the user’s perspective:
+
+1. Open Prospecting Tools.
+2. Select OCR.
+3. Drag and drop a business card image or upload one.
+4. Review the extracted company and contact information.
+5. Edit any fields that need correction.
+6. Confirm and add the record to the CRM.
+
+![Business Card OCR](docs/images/ocr.png)
+
+This feature converts offline conversations into structured pipeline data.
+
+### Step 10: Find Companies with Geo Finder
+
+Geo Finder helps users discover companies based on location, category, industry, or search intent.
+
+Use it to:
+
+- Search for companies in a city or region.
+- Find businesses near a specific area.
+- Identify local prospects by category.
+- Build a ranked list of companies.
+- Export discovery results for further review.
+
+![Geo Finder](docs/images/geo-finder.png)
+
+Example uses:
+
+- “Manufacturing companies near Toronto.”
+- “Corporate offices in downtown San Francisco.”
+- “Industrial suppliers around Hamilton.”
+- “Hospitals within this region.”
+
+Geo Finder is valuable because it helps users create new prospect lists instead of only managing existing leads.
+
+### Step 11: Research Companies with Company Extractor
+
+Company Extractor helps turn company research into a structured profile.
+
+Use it when:
+
+- A user has a company name but needs more context.
+- A rep wants to understand what a target company does.
+- A manager wants a cleaner profile before outreach.
+- A user wants to create a CRM-ready record from research.
+
+The user can run a company extraction, review the generated profile, export it, and add useful information into the prospect list.
+
+![Company Extractor](docs/images/company-extractor.png)
+
+This feature reduces the time spent manually reading, copying, and organizing company research.
+
+### Step 12: Use Agent Space as the AI Workbench
+
+Agent Space is the AI assistant area inside ProspectIQ.
+
+Use it to:
+
+- Ask questions about a company.
+- Load company context into the conversation.
+- Upload or use extracted card data as context.
+- Prepare sales notes.
+- Draft outreach ideas.
+- Summarize account information.
+- Think through next steps before contacting a prospect.
+
+![Agent Space](docs/images/agent-space.png)
+
+Agent Space is different from a generic chatbot because it can work with the user’s prospecting context. The goal is not just to answer general questions, but to help the user act on real account information.
+
+### Step 13: Review History
+
+ProspectIQ keeps a history of important prospecting runs.
+
+Use history to:
+
+- Reopen previous OCR captures.
+- Review earlier Geo Finder searches.
+- Open past company research runs.
+- Revisit previous AI conversations.
+- Avoid repeating work.
+
+History matters because prospecting is cumulative. The team should be able to learn from previous searches and research instead of starting from zero each time.
+
+### Step 14: Export Useful Outputs
+
+ProspectIQ supports export workflows for sharing and review.
+
+Use exports to:
+
+- Download discovered company lists.
+- Save researched company profiles.
+- Share findings with team members.
+- Prepare account summaries for managers or investors.
+
+Exports make the product useful outside the app when users need a portable report, list, or profile.
+
+### Step 15: Use Learning, Reports, and Settings
+
+ProspectIQ also includes supporting areas for team development and oversight.
+
+Learning:
+
+- Used for onboarding material.
+- Helps new users understand sourcing guidelines, internal playbooks, and domain knowledge.
+
+Reports:
+
+- Used for reviewing performance and pipeline health.
+- Helps managers understand activity, conversion, and account progress.
+
+Settings:
+
+- Used for workspace-level preferences and configuration.
+- Helps the team keep the system organized.
+
+These sections support the broader business operation around the core sales workflow.
+
+---
+
+## Full Feature List
+
+### Sales Workspace
+
+- Home dashboard.
+- Global command bar.
+- Sidebar navigation.
+- Quick actions.
+- Notifications.
+- Daily tasks.
+- Calendar view.
+- Recent activity feed.
+
+### Company Management
+
+- Company list.
+- Company table view.
+- Pipeline board view.
+- Company profiles.
+- Search and filters.
+- Sorting.
+- Stage tracking.
+- Fit score display.
+- Bulk selection.
+- Bulk delete.
+- Custom columns.
+- Inline custom-field editing.
+
+### Contact Management
+
+- Contact directory.
+- Company-linked contacts.
+- Primary contact selection.
+- Contact editing.
+- Email, phone, title, and LinkedIn tracking.
+
+### Outreach Tracking
+
+- Activity logging.
+- Notes.
+- Pinned notes.
+- Next actions.
+- Follow-up dates.
+- Recent activity timeline.
+- Immediate action tracking.
+
+### AI and Prospecting Tools
+
+- Business card OCR.
+- Editable extraction review.
+- OCR-to-CRM save flow.
+- Geo Finder.
+- Ranked company discovery.
+- Company Extractor.
+- Company profile generation.
+- AI restructuring of research.
+- AI fit analysis.
+- AI briefing and outreach support.
+- Agent Space assistant.
+- Company context loading.
+- Chat history.
+
+### Sharing and Review
+
+- Geo result export.
+- Company profile export.
+- History for previous runs.
+- Reopen past prospecting work.
+
+---
+
+## The User Journey
+
+ProspectIQ is easiest to understand as a complete sales journey.
+
+### 1. Discover
+
+The user finds potential companies through Geo Finder, manual entry, OCR, or Company Extractor.
+
+### 2. Capture
+
+The company and contact details are saved into the workspace. Business cards and research outputs become structured records.
+
+### 3. Qualify
+
+The user reviews industry, location, staff size, fit score, notes, and AI-generated context to decide whether the company is worth pursuing.
+
+### 4. Organize
+
+The company is placed into a pipeline stage. Contacts, notes, and activities are kept together.
+
+### 5. Act
+
+The user logs calls, sends emails, schedules meetings, adds tasks, and creates follow-ups.
+
+### 6. Learn
+
+The workspace keeps history. Over time, the team can see what types of companies, locations, and outreach actions produce results.
+
+---
+
+## Business Value
+
+ProspectIQ creates value in five practical ways.
+
+### 1. Faster Lead Entry
+
+Business cards, company research, and geo searches can become CRM-ready records faster than manual typing.
+
+### 2. Better Follow-Up Discipline
+
+Tasks, activities, next actions, and stages make it harder for good leads to be forgotten.
+
+### 3. Cleaner Sales Data
+
+Companies, contacts, notes, and activity history are organized around each account.
+
+### 4. Smarter Outreach
+
+AI assistance helps users understand the company and prepare more relevant communication.
+
+### 5. Stronger Management Visibility
+
+The pipeline, dashboard, reports, and history make it easier to understand what is happening across the prospecting operation.
+
+---
+
+## Investor Perspective
+
+ProspectIQ is attractive because it targets a painful and common business workflow: turning messy prospect information into revenue activity.
+
+The product does not depend on users changing their entire sales process overnight. It improves the work they already do:
+
+- Finding prospects.
+- Saving contacts.
+- Tracking companies.
+- Preparing outreach.
+- Following up.
+- Reviewing progress.
+
+This gives ProspectIQ a practical adoption path. A team can start with one workflow, such as business card capture or company discovery, then expand into pipeline management and AI-assisted sales execution.
+
+---
+
+## Market Opportunity
+
+ProspectIQ sits between CRM, lead generation, sales intelligence, and AI productivity.
+
+Potential customer segments include:
+
+- Small and mid-sized B2B sales teams.
+- Local service businesses selling to commercial customers.
+- Industrial and manufacturing sales teams.
+- Procurement and sourcing teams.
+- Agencies doing lead research.
+- Field sales organizations.
+- Founder-led companies building their first outbound process.
+
+These teams often need more than a spreadsheet but less complexity than a large enterprise CRM. ProspectIQ can serve that middle ground with a more focused prospecting experience.
+
+---
+
+## Competitive Advantage
+
+### Lead Capture and CRM in One Place
+
+Many tools help store leads. Others help generate or research leads. ProspectIQ connects both sides.
+
+### Practical AI Inside the Workflow
+
+The AI features are tied to everyday sales actions: scan, research, summarize, qualify, brief, and draft.
+
+### Context-Aware Assistance
+
+Agent Space can use company and contact context, which makes the assistant more useful than a blank chat window.
+
+### Flexible Data Tracking
+
+Custom columns let teams track the information that matters to their market without waiting for product changes.
+
+### Repeatable Sales Memory
+
+History, notes, activities, and profiles give the team a memory that compounds over time.
+
+---
+
+## Revenue Model
+
+ProspectIQ can support several revenue streams:
+
+- Monthly subscription per user.
+- Team plans for shared workspaces.
+- Usage credits for AI-heavy workflows.
+- Premium exports and reporting.
+- Vertical templates for specific industries.
+- Setup and onboarding services.
+- Custom workflow configuration for larger teams.
+
+The most natural starting model is a per-seat subscription with usage limits for advanced AI prospecting features.
+
+---
+
+## Why Now
+
+Sales teams are ready for AI tools, but many AI tools still feel disconnected from real work. ProspectIQ is timely because it applies AI directly to prospecting workflows.
+
+The market is ready because:
+
+- Teams want faster research.
+- Businesses need cleaner lead data.
+- Reps are expected to do more with fewer tools.
+- AI is becoming normal in daily work.
+- Small and mid-sized teams need simple, useful sales systems.
+- Existing CRMs are often too broad and too manual for early prospecting.
+
+ProspectIQ can become the place where prospecting actually happens, not just where final records are stored.
+
+---
+
+## Success Metrics
+
+The product should be measured by outcomes that matter to sales teams.
+
+Important metrics include:
+
+- Number of leads captured per week.
+- Time saved on manual data entry.
+- Number of business cards converted into records.
+- Number of companies discovered through Geo Finder.
+- Percentage of companies with primary contacts.
+- Number of follow-ups scheduled.
+- Follow-up completion rate.
+- Number of qualified companies moved forward in the pipeline.
+- Meetings booked from ProspectIQ-managed leads.
+- Proposals sent.
+- Won opportunities.
+- User retention and weekly active usage.
+
+---
+
+## Investment Use of Funds
+
+Investment would help turn ProspectIQ from a functional product into a polished commercial platform.
+
+Funding can be used for:
+
+- Product design polish.
+- Customer onboarding experience.
+- Sales and marketing materials.
+- More investor-ready demos.
+- More reliable AI workflows.
+- Stronger reporting dashboards.
+- Customer pilots.
+- Product packaging and pricing.
+- User testing with real sales teams.
+
+The focus should be market validation, user experience, and proving that ProspectIQ saves time while improving lead quality.
+
+---
+
+## Risks and Mitigations
+
+### Risk: Users Already Have a CRM
+
+Mitigation:
+
+Position ProspectIQ as a prospecting workspace that can either replace lightweight CRMs or feed better data into existing sales processes.
+
+### Risk: AI Output May Need Review
+
+Mitigation:
+
+Keep the user in control. ProspectIQ already uses review and confirmation flows for important captured information.
+
+### Risk: Users May Not Change Habits Quickly
+
+Mitigation:
+
+Start with high-value workflows that are immediately useful, such as OCR capture, Geo Finder, and company research.
+
+### Risk: The Market Has Many Sales Tools
+
+Mitigation:
+
+Focus on the early prospecting workflow, where many teams still rely on manual research and spreadsheets.
+
+---
+
+## Strategic Narrative
+
+ProspectIQ is building a focused operating system for B2B prospecting.
+
+The product starts where many sales opportunities begin: a business card, a map search, a company name, a rough note, or a research task. It turns that raw signal into a company record, a contact, a profile, a next action, and eventually a pipeline opportunity.
+
+That flow is valuable because prospecting is still one of the messiest parts of sales. Teams do not simply need another place to store data. They need a better way to create, qualify, organize, and act on that data.
+
+ProspectIQ can win by owning this workflow:
+
+- Discover the company.
+- Capture the details.
+- Understand the fit.
+- Prepare outreach.
+- Track the follow-up.
+- Move the opportunity forward.
+
+Over time, every company record, note, activity, and outcome makes the workspace smarter and more valuable.
+
+---
+
+## Conclusion
+
+ProspectIQ is a practical AI-assisted sales workspace for teams that need better prospecting. It brings together company management, contact tracking, pipeline visibility, business card capture, geographic discovery, company research, AI assistance, tasks, notes, and history.
+
+The product is easy to explain: it helps teams find better prospects and follow up better.
+
+For users, ProspectIQ saves time and brings order to daily sales work. For investors, it represents a focused opportunity in a large market where AI can create immediate operational value.
+
+---
+
+*ProspectIQ by MapleMPSS. Confidential product guide and investor proposal.*

learning_data/collections_meta.json

@@ -0,0 +1 @@
+[]

migrate.py

@@ -0,0 +1,214 @@
+import os
+import sys
+import bcrypt
+from dotenv import load_dotenv
+
+# Load env before importing db
+load_dotenv()
+
+# Add project root to sys.path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from db import get_db_connection, is_supabase_active
+
+def hash_password(password: str) -> str:
+    salt = bcrypt.gensalt()
+    return bcrypt.hashpw(password.encode('utf-8'), salt).decode('utf-8')
+
+def run_migrations():
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    is_pg = is_supabase_active()
+    print(f"Running migrations on {'PostgreSQL (Supabase)' if is_pg else 'SQLite'}...")
+
+    try:
+        # 1. Create Roles table
+        if is_pg:
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS roles (
+                    id SERIAL PRIMARY KEY,
+                    tenant_id INTEGER NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
+                    name VARCHAR(255) NOT NULL,
+                    description TEXT,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    UNIQUE(tenant_id, name)
+                )
+            """)
+        else:
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS roles (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    tenant_id INTEGER NOT NULL,
+                    name TEXT NOT NULL,
+                    description TEXT,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY(tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
+                    UNIQUE(tenant_id, name)
+                )
+            """)
+        print("Roles table verified/created.")
+
+        # 2. Create Permissions table
+        if is_pg:
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS permissions (
+                    id SERIAL PRIMARY KEY,
+                    code VARCHAR(255) UNIQUE NOT NULL,
+                    description TEXT
+                )
+            """)
+        else:
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS permissions (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    code TEXT UNIQUE NOT NULL,
+                    description TEXT
+                )
+            """)
+        print("Permissions table verified/created.")
+
+        # 3. Create Role Permissions join table
+        if is_pg:
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS role_permissions (
+                    role_id INTEGER NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
+                    permission_id INTEGER NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
+                    PRIMARY KEY(role_id, permission_id)
+                )
+            """)
+        else:
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS role_permissions (
+                    role_id INTEGER NOT NULL,
+                    permission_id INTEGER NOT NULL,
+                    PRIMARY KEY(role_id, permission_id),
+                    FOREIGN KEY(role_id) REFERENCES roles(id) ON DELETE CASCADE,
+                    FOREIGN KEY(permission_id) REFERENCES permissions(id) ON DELETE CASCADE
+                )
+            """)
+        print("Role permissions mapping table verified/created.")
+
+        # 4. Add columns to users table
+        if is_pg:
+            # Check if columns exist first
+            cursor.execute("SELECT column_name FROM information_schema.columns WHERE table_name = 'users' AND table_schema = 'public'")
+            columns = [r[0] for r in cursor.fetchall()]
+            if 'password_hash' not in columns:
+                cursor.execute("ALTER TABLE users ADD COLUMN password_hash TEXT")
+                print("Added password_hash column to public.users (Postgres)")
+            if 'role_id' not in columns:
+                cursor.execute("ALTER TABLE users ADD COLUMN role_id INTEGER REFERENCES roles(id)")
+                print("Added role_id column to public.users (Postgres)")
+        else:
+            # SQLite: Check table info
+            cursor.execute("PRAGMA table_info(users)")
+            columns = [r[1] for r in cursor.fetchall()]
+            if 'password_hash' not in columns:
+                cursor.execute("ALTER TABLE users ADD COLUMN password_hash TEXT")
+                print("Added password_hash column to users (SQLite)")
+            if 'role_id' not in columns:
+                cursor.execute("ALTER TABLE users ADD COLUMN role_id INTEGER REFERENCES roles(id)")
+                print("Added role_id column to users (SQLite)")
+
+        conn.commit()
+
+        # 5. Seed permissions
+        default_permissions = [
+            ("companies:read", "Read access to company listings and profiles"),
+            ("companies:write", "Create, update, or edit company data"),
+            ("companies:delete", "Delete company records"),
+            ("contacts:read", "View contacts"),
+            ("contacts:write", "Create, update, or delete contacts"),
+            ("prospecting:use", "Execute OCR, Geo Finder, or AI Company Extractor runs"),
+            ("settings:manage", "Edit tenant settings, stages, and metadata"),
+            ("users:manage", "Provision users, create roles, and alter role permissions")
+        ]
+
+        for code, desc in default_permissions:
+            if is_pg:
+                cursor.execute("INSERT INTO permissions (code, description) VALUES (%s, %s) ON CONFLICT (code) DO NOTHING", (code, desc))
+            else:
+                cursor.execute("INSERT OR IGNORE INTO permissions (code, description) VALUES (?, ?)", (code, desc))
+        conn.commit()
+        print("Standard permissions seeded successfully.")
+
+        # 6. Migrate existing users and tenants
+        # Fetch all unique tenants in users
+        cursor.execute("SELECT DISTINCT tenant_id FROM users")
+        tenant_ids = [r[0] for r in cursor.fetchall()]
+
+        for tenant_id in tenant_ids:
+            # Check/create standard roles for each tenant
+            for role_name in ["Admin", "BD Rep", "Viewer"]:
+                if is_pg:
+                    cursor.execute("INSERT INTO roles (tenant_id, name, description) VALUES (%s, %s, %s) ON CONFLICT (tenant_id, name) DO NOTHING", (tenant_id, role_name, f"Default {role_name} role"))
+                else:
+                    cursor.execute("INSERT OR IGNORE INTO roles (tenant_id, name, description) VALUES (?, ?, ?)", (tenant_id, role_name, f"Default {role_name} role"))
+            conn.commit()
+
+            # Grant permissions to roles for this tenant
+            # Admin gets all permissions
+            cursor.execute("SELECT id FROM roles WHERE tenant_id = ? AND name = ?", (tenant_id, "Admin"))
+            admin_role_id = cursor.fetchone()[0]
+            cursor.execute("SELECT id FROM permissions")
+            all_perm_ids = [r[0] for r in cursor.fetchall()]
+            for pid in all_perm_ids:
+                if is_pg:
+                    cursor.execute("INSERT INTO role_permissions (role_id, permission_id) VALUES (%s, %s) ON CONFLICT DO NOTHING", (admin_role_id, pid))
+                else:
+                    cursor.execute("INSERT OR IGNORE INTO role_permissions (role_id, permission_id) VALUES (?, ?)", (admin_role_id, pid))
+
+            # BD Rep gets non-admin permissions
+            cursor.execute("SELECT id FROM roles WHERE tenant_id = ? AND name = ?", (tenant_id, "BD Rep"))
+            bd_role_id = cursor.fetchone()[0]
+            cursor.execute("SELECT id FROM permissions WHERE code NOT IN ('users:manage', 'settings:manage')")
+            bd_perm_ids = [r[0] for r in cursor.fetchall()]
+            for pid in bd_perm_ids:
+                if is_pg:
+                    cursor.execute("INSERT INTO role_permissions (role_id, permission_id) VALUES (%s, %s) ON CONFLICT DO NOTHING", (bd_role_id, pid))
+                else:
+                    cursor.execute("INSERT OR IGNORE INTO role_permissions (role_id, permission_id) VALUES (?, ?)", (bd_role_id, pid))
+
+            # Viewer gets read permissions
+            cursor.execute("SELECT id FROM roles WHERE tenant_id = ? AND name = ?", (tenant_id, "Viewer"))
+            viewer_role_id = cursor.fetchone()[0]
+            cursor.execute("SELECT id FROM permissions WHERE code IN ('companies:read', 'contacts:read')")
+            viewer_perm_ids = [r[0] for r in cursor.fetchall()]
+            for pid in viewer_perm_ids:
+                if is_pg:
+                    cursor.execute("INSERT INTO role_permissions (role_id, permission_id) VALUES (%s, %s) ON CONFLICT DO NOTHING", (viewer_role_id, pid))
+                else:
+                    cursor.execute("INSERT OR IGNORE INTO role_permissions (role_id, permission_id) VALUES (?, ?)", (viewer_role_id, pid))
+            conn.commit()
+
+        # 7. Update users with correct role_id and default password_hash
+        cursor.execute("SELECT id, tenant_id, role, password_hash FROM users")
+        users_rows = cursor.fetchall()
+
+        default_hash = hash_password("password123")
+        for u in users_rows:
+            uid, tenant_id, role_str, pwd_hash = u[0], u[1], u[2], u[3]
+
+            # Map role_str to role_id
+            cursor.execute("SELECT id FROM roles WHERE tenant_id = ? AND name = ?", (tenant_id, role_str))
+            role_row = cursor.fetchone()
+            if role_row:
+                target_role_id = role_row[0]
+                cursor.execute("UPDATE users SET role_id = ? WHERE id = ?", (target_role_id, uid))
+
+            # Update password if not set
+            if not pwd_hash:
+                cursor.execute("UPDATE users SET password_hash = ? WHERE id = ?", (default_hash, uid))
+
+        conn.commit()
+        print("Users successfully mapped to dynamic roles and default passwords seeded (password123).")
+        print("Migration complete!")
+    except Exception as e:
+        conn.rollback()
+        print("Migration failed:", e)
+        raise e
+    finally:
+        conn.close()
+
+if __name__ == "__main__":
+    run_migrations()

render.yaml

@@ -0,0 +1,90 @@
+services:
+  - type: keyvalue
+    name: prospectiq-redis
+    plan: starter
+    ipAllowList: []
+
+  - type: web
+    name: prospectiq-web
+    runtime: docker
+    plan: starter
+    dockerfilePath: ./Dockerfile
+    dockerCommand: gunicorn app:app --bind 0.0.0.0:${PORT} --workers ${WEB_CONCURRENCY} --timeout ${WEB_TIMEOUT}
+    healthCheckPath: /
+    envVars:
+      - key: REDIS_URL
+        fromService:
+          type: keyvalue
+          name: prospectiq-redis
+          property: connectionString
+      - key: CELERY_BROKER_URL
+        fromService:
+          type: keyvalue
+          name: prospectiq-redis
+          property: connectionString
+      - key: CELERY_RESULT_BACKEND
+        fromService:
+          type: keyvalue
+          name: prospectiq-redis
+          property: connectionString
+      - key: PORT
+        value: 10000
+      - key: WEB_CONCURRENCY
+        value: 2
+      - key: WEB_TIMEOUT
+        value: 180
+      - key: GEMINI_API_KEY_prime_1
+        sync: false
+      - key: GEMINI_API_KEY_prime_2
+        sync: false
+      - key: GEMINI_API_KEY_prime_3
+        sync: false
+      - key: SUPABASE_DB_HOST
+        sync: false
+      - key: SUPABASE_DB_NAME
+        value: postgres
+      - key: SUPABASE_DB_USER
+        value: postgres
+      - key: SUPABASE_DB_PASSWORD
+        sync: false
+      - key: SUPABASE_DB_PORT
+        value: 6543
+
+  - type: worker
+    name: prospectiq-worker
+    runtime: docker
+    plan: starter
+    dockerfilePath: ./Dockerfile
+    dockerCommand: celery -A celery_app.celery_app worker --loglevel=info
+    envVars:
+      - key: REDIS_URL
+        fromService:
+          type: keyvalue
+          name: prospectiq-redis
+          property: connectionString
+      - key: CELERY_BROKER_URL
+        fromService:
+          type: keyvalue
+          name: prospectiq-redis
+          property: connectionString
+      - key: CELERY_RESULT_BACKEND
+        fromService:
+          type: keyvalue
+          name: prospectiq-redis
+          property: connectionString
+      - key: GEMINI_API_KEY_prime_1
+        sync: false
+      - key: GEMINI_API_KEY_prime_2
+        sync: false
+      - key: GEMINI_API_KEY_prime_3
+        sync: false
+      - key: SUPABASE_DB_HOST
+        sync: false
+      - key: SUPABASE_DB_NAME
+        value: postgres
+      - key: SUPABASE_DB_USER
+        value: postgres
+      - key: SUPABASE_DB_PASSWORD
+        sync: false
+      - key: SUPABASE_DB_PORT
+        value: 6543

requirements.txt

@@ -0,0 +1,147 @@
+aiohappyeyeballs==2.6.2
+aiohttp==3.14.1
+aiosignal==1.4.0
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.14.1
+attrs==26.1.0
+bcrypt==5.0.0
+blinker==1.9.0
+build==1.5.0
+certifi==2026.6.17
+cffi==2.0.0
+charset-normalizer==3.4.7
+click==8.4.2
+colorama==0.4.6
+cryptography==49.0.0
+decorator==5.3.1
+distro==1.9.0
+durationpy==0.10
+et_xmlfile==2.0.0
+filelock==3.29.4
+filetype==1.2.0
+Flask==3.1.3
+flatbuffers==25.12.19
+frozenlist==1.8.0
+fsspec==2026.6.0
+google-auth==2.55.1
+google-genai==2.10.0
+googleapis-common-protos==1.75.0
+greenlet==3.5.3
+gunicorn==23.0.0
+grpcio==1.81.1
+h11==0.16.0
+hf-xet==1.5.1
+httpcore==1.0.9
+httptools==0.8.0
+httpx==0.28.1
+httpx-sse==0.4.3
+huggingface_hub==1.21.0
+idna==3.18
+ImageIO==2.37.3
+imageio-ffmpeg==0.6.0
+importlib_resources==7.1.0
+itsdangerous==2.2.0
+Jinja2==3.1.6
+jsonpatch==1.33
+jsonpointer==3.1.1
+jsonschema==4.26.0
+jsonschema-specifications==2025.9.1
+kubernetes==36.0.2
+langchain==1.3.11
+langchain-classic==1.0.8
+langchain-community==0.4.2
+langchain-core==1.4.8
+langchain-google-genai==4.2.6
+langchain-protocol==0.0.18
+langchain-text-splitters==1.1.2
+langgraph==1.2.6
+langgraph-checkpoint==4.1.1
+langgraph-prebuilt==1.1.0
+langgraph-sdk==0.4.2
+langsmith==0.9.3
+markdown-it-py==4.2.0
+MarkupSafe==3.0.3
+mdurl==0.1.2
+mmh3==5.2.1
+moviepy==2.2.1
+multidict==6.7.1
+numpy==2.4.6
+oauthlib==3.3.1
+onnxruntime==1.27.0
+openpyxl==3.1.5
+opentelemetry-api==1.43.0
+opentelemetry-exporter-otlp-proto-common==1.43.0
+opentelemetry-exporter-otlp-proto-grpc==1.43.0
+opentelemetry-proto==1.43.0
+opentelemetry-sdk==1.43.0
+opentelemetry-semantic-conventions==0.64b0
+orjson==3.11.9
+ormsgpack==1.12.2
+overrides==7.7.0
+packaging==26.2
+pillow==11.3.0
+proglog==0.1.12
+propcache==0.5.2
+protobuf==7.35.1
+pyasn1==0.6.3
+pyasn1_modules==0.4.2
+pybase64==1.4.3
+pycparser==3.0
+psycopg2-binary==2.9.12
+pydantic==2.13.4
+pydantic-settings==2.14.2
+pydantic_core==2.46.4
+Pygments==2.20.0
+pypdf==6.14.2
+PyPika==0.51.1
+pyproject_hooks==1.2.0
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.2
+PyYAML==6.0.3
+referencing==0.37.0
+requests==2.34.2
+requests-oauthlib==2.0.0
+requests-toolbelt==1.0.0
+rich==15.0.0
+rpds-py==2026.5.1
+serpapi==1.0.2
+shellingham==1.5.4
+six==1.17.0
+sniffio==1.3.1
+SpeechRecognition==3.17.0
+SQLAlchemy==2.0.51
+tenacity==9.1.4
+tokenizers==0.23.1
+tqdm==4.68.3
+typer==0.25.1
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+urllib3==2.7.0
+uuid_utils==0.16.2
+uvicorn==0.49.0
+watchfiles==1.2.0
+websocket-client==1.9.0
+websockets==15.0.1
+Werkzeug==3.1.8
+xxhash==3.8.0
+yarl==1.24.2
+zstandard==0.25.0
+langchain-pinecone
+pinecone-client
+pinecone
+pyreadline3; platform_system == "Windows"
+celery
+redis
+selenium
+webdriver-manager
+reportlab
+markdown
+beautifulsoup4
+anthropic
+unstructured[xlsx]
+pandas
+networkx
+supabase
+ddgs
+langchain-excel-loader

routes/__init__.py

@@ -0,0 +1 @@
+"""Routes package for ProspectIQ."""

routes/ai.py

@@ -0,0 +1,912 @@
+from __future__ import annotations
+
+import os
+import re
+import threading
+import base64
+from pathlib import Path
+from typing import Any
+from flask import Blueprint, jsonify, request, send_file
+
+from services.export_service import build_profile_pdf, build_geo_excel, parse_geo_companies, parse_geo_companies_from_stages
+from services.ai_service import (
+    JOBS,
+    JOBS_LOCK,
+    PIPELINE_SCRIPT,
+    append_log,
+    clean_int,
+    current_job_status,
+    db_get_interaction,
+    db_list_interactions,
+    db_prune_geo_history,
+    db_update_interaction,
+    fallback_profile_path,
+    find_final_profile,
+    gemini_keys,
+    get_base_company_context,
+    get_job_state,
+    list_profiles,
+    new_job,
+    now,
+    resolve_project_file,
+    run_company_research_job,
+    run_geo_job,
+    safe_read_profile,
+    safe_read_text,
+    stop_process_tree,
+    update_job,
+)
+
+ai_bp = Blueprint("ai", __name__)
+
+ALLOWED_IMAGE_MIME_TYPES = {
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/gif",
+    "image/bmp",
+    "image/tiff",
+}
+
+def get_openrouter_key_response():
+    key = os.environ.get("OPENROUTER_API_KEY", "").strip()
+    if not key:
+        return None, (jsonify({"error": "OPENROUTER_API_KEY is not configured."}), 503)
+    return key, None
+
+def get_gemini_key() -> str:
+    keys = gemini_keys()
+    return keys[0] if keys else ""
+
+def create_completed_interaction(
+    kind: str,
+    title: str,
+    input_payload: dict[str, Any],
+    result: dict[str, Any] | None = None,
+    error: str = "",
+) -> str:
+    job_id = new_job(kind, title, input_payload)
+    update_job(
+        job_id,
+        status="failed" if error else "completed",
+        started_at=now(),
+        finished_at=now(),
+        result=result or {},
+        error=error,
+    )
+    return job_id
+
+def enqueue_celery_task(task_func, fallback_func, *args):
+    try:
+        task_func.delay(*args)
+        return True
+    except Exception as exc:
+        print(f"Warning: Celery enqueue failed for {getattr(task_func, 'name', task_func)}: {exc}")
+        thread = threading.Thread(target=fallback_func, args=args, daemon=True)
+        thread.start()
+        return False
+
+def geo_result_payload(job_id: str) -> dict[str, Any] | None:
+    payload = get_job_state(job_id)
+    with JOBS_LOCK:
+        job = JOBS.get(job_id)
+        if not payload and job:
+            payload = dict(job)
+    if not payload or payload.get("kind") != "geo":
+        return None
+
+    result = payload.get("result")
+    if not isinstance(result, dict):
+        return payload
+    if result.get("result") and not result.get("companies"):
+        result["companies"] = parse_geo_companies(str(result.get("result") or ""))
+    if not result.get("companies") and result.get("stages"):
+        fallback_companies = parse_geo_companies_from_stages(result.get("stages") or [])
+        if fallback_companies:
+            result["companies"] = fallback_companies
+            result["ranking_unavailable"] = True
+            result["notice"] = "Ranking was not available, so these discovered companies are shown unranked."
+    payload["result"] = result
+    return payload
+
+def safe_download_name(value: str, fallback: str = "geo-results") -> str:
+    name = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip()).strip("-._")
+    return (name[:90] or fallback) + ".xlsx"
+
+def safe_pdf_name(value: str, fallback: str = "company-profile") -> str:
+    name = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip()).strip("-._")
+    return (name[:90] or fallback) + ".pdf"
+
+# =====================================================================
+# Business Card OCR Route
+# =====================================================================
+
+@ai_bp.post("/api/ocr")
+def api_ocr():
+    uploaded_file = request.files.get("card")
+    if not uploaded_file or not uploaded_file.filename:
+        return jsonify({"error": "Upload a business card or document image."}), 400
+
+    mime_type = uploaded_file.mimetype or "application/octet-stream"
+    input_payload = {"filename": uploaded_file.filename, "mime_type": mime_type}
+    if mime_type not in ALLOWED_IMAGE_MIME_TYPES:
+        create_completed_interaction("ocr", uploaded_file.filename, input_payload, error="Unsupported image type.")
+        return jsonify({"error": "Upload a JPG, PNG, WebP, GIF, BMP, or TIFF image."}), 400
+
+    file_content_b64 = base64.b64encode(uploaded_file.read()).decode("ascii")
+    job_id = new_job("ocr", uploaded_file.filename, input_payload)
+
+    from tasks import ocr_task
+
+    def fallback_ocr(job_id_arg: str, filename_arg: str, mime_type_arg: str, file_content_arg: str):
+        ocr_task.run(job_id_arg, filename_arg, mime_type_arg, file_content_arg)
+
+    used_celery = enqueue_celery_task(
+        ocr_task,
+        fallback_ocr,
+        job_id,
+        uploaded_file.filename,
+        mime_type,
+        file_content_b64,
+    )
+    return jsonify({"job_id": job_id, "status": "queued", "queued": used_celery}), 202
+
+# =====================================================================
+# Geo Finder Routes
+# =====================================================================
+
+@ai_bp.post("/api/geo-search")
+def api_geo_search():
+    payload = request.get_json(force=True, silent=True) or {}
+    query = str(payload.get("query") or "").strip()
+    if not query:
+        return jsonify({"error": "Enter a company type, industry, location, or coordinates."}), 400
+
+    job_id = new_job("geo", query, {"query": query})
+    from tasks import geo_search_task
+    used_celery = enqueue_celery_task(geo_search_task, run_geo_job, job_id, query)
+    return jsonify({"job_id": job_id, "queued": used_celery})
+
+@ai_bp.get("/api/geo-export/<job_id>")
+def api_geo_export(job_id: str):
+    job = geo_result_payload(job_id)
+    if not job:
+        return jsonify({"error": "Geo run not found."}), 404
+    if job.get("status") != "completed":
+        return jsonify({"error": "Geo export is available after the run completes."}), 400
+
+    try:
+        output = build_geo_excel(job)
+    except (RuntimeError, ValueError) as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    filename = safe_download_name(str(job.get("title") or "geo-results"))
+    return send_file(
+        output,
+        as_attachment=True,
+        download_name=filename,
+        mimetype="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    )
+
+# =====================================================================
+# Company Research & Extractor Routes
+# =====================================================================
+
+@ai_bp.post("/api/company-research")
+def api_company_research():
+    payload = request.get_json(force=True, silent=True) or {}
+    company = str(payload.get("company") or "").strip()
+    if not company:
+        return jsonify({"error": "Enter a company name."}), 400
+    if not get_base_company_context():
+        return jsonify({
+            "error": "Base company context is required before running Company Research.",
+            "redirect": "#/settings",
+        }), 409
+    if not PIPELINE_SCRIPT.exists():
+        return jsonify({"error": f"Missing pipeline script: {PIPELINE_SCRIPT}"}), 500
+
+    job_id = new_job("research", company, payload)
+    from tasks import company_research_task
+    used_celery = enqueue_celery_task(company_research_task, run_company_research_job, job_id, payload)
+    return jsonify({"job_id": job_id, "queued": used_celery})
+
+@ai_bp.get("/api/profiles")
+def api_profiles():
+    return jsonify(list_profiles())
+
+@ai_bp.get("/api/profile")
+def api_profile():
+    raw_path = request.args.get("path", "")
+    try:
+        resolved = resolve_project_file(raw_path)
+        text = safe_read_profile(resolved)
+        if not text and resolved.name == "final_integrated_company_profile_gemini_enriched.txt":
+            fallback = resolved.with_name("final_integrated_company_profile.txt")
+            if fallback.exists():
+                fallback_text = safe_read_profile(fallback)
+                if fallback_text:
+                    return jsonify({"path": str(fallback), "text": fallback_text})
+        return jsonify({"path": str(resolved), "text": text or safe_read_text(resolved)})
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@ai_bp.get("/api/profile-pdf")
+def api_profile_pdf():
+    raw_path = request.args.get("path", "")
+    job_id = str(request.args.get("job_id") or "").strip()
+    stored_text = ""
+    stored_source = ""
+    pdf_display_name = ""
+    if job_id:
+        job = get_job_state(job_id)
+        if not job:
+            return jsonify({"error": "Job not found."}), 404
+        result = job.get("result") if isinstance(job.get("result"), dict) else {}
+        stored_text = str(result.get("text") or job.get("result_text") or "").strip()
+        stored_source = str(result.get("path") or job.get("profile_path") or "").strip()
+        raw_path = raw_path or stored_source
+        # Use the searched company name for the downloaded PDF when available.
+        pdf_display_name = str(job.get("title") or "").strip()
+
+    try:
+        resolved = None
+        text = ""
+        if raw_path:
+            try:
+                resolved = resolve_project_file(raw_path)
+                text = safe_read_profile(resolved)
+                if not text:
+                    resolved = fallback_profile_path(resolved)
+                    text = safe_read_profile(resolved)
+            except (ValueError, FileNotFoundError):
+                if not stored_text:
+                    raise
+
+        if not text and stored_text:
+            text = stored_text
+            resolved = Path(stored_source or raw_path or f"{job_id}-company-profile.md")
+        if not text:
+            return jsonify({"error": "Profile has no usable text to export."}), 400
+
+        output = build_profile_pdf(text, resolved)
+        filename_base = (pdf_display_name or resolved.parent.name or resolved.stem) + " Company Research"
+        return send_file(
+            output,
+            as_attachment=True,
+            download_name=safe_pdf_name(filename_base),
+            mimetype="application/pdf",
+        )
+    except (ValueError, FileNotFoundError) as exc:
+        return jsonify({"error": str(exc)}), 400
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# =====================================================================
+# Jobs & Audit History Management Routes
+# =====================================================================
+
+@ai_bp.get("/api/jobs")
+def api_jobs():
+    return jsonify(db_list_interactions())
+
+@ai_bp.get("/api/jobs/<job_id>")
+def api_job(job_id: str):
+    payload = get_job_state(job_id)
+    with JOBS_LOCK:
+        job = JOBS.get(job_id)
+        if not payload and job:
+            payload = dict(job)
+    if not payload:
+        return jsonify({"error": "Job not found."}), 404
+    if (
+        payload.get("kind") == "research"
+        and payload.get("status") not in {"queued", "running"}
+        and payload.get("run_dir")
+        and not payload.get("result")
+    ):
+        payload["result"] = find_final_profile(payload.get("run_dir"))
+    if payload.get("kind") == "geo" and isinstance(payload.get("result"), dict):
+        result = payload["result"]
+        if result.get("result") and not result.get("companies"):
+            result["companies"] = parse_geo_companies(str(result.get("result") or ""))
+        if not result.get("companies") and result.get("stages"):
+            fallback_companies = parse_geo_companies_from_stages(result.get("stages") or [])
+            if fallback_companies:
+                result["companies"] = fallback_companies
+                result["ranking_unavailable"] = True
+                result["notice"] = "Ranking was not available, so these discovered companies are shown unranked."
+    return jsonify(payload)
+
+@ai_bp.post("/api/jobs/<job_id>/stop")
+def api_stop_job(job_id: str):
+    payload = get_job_state(job_id)
+    with JOBS_LOCK:
+        job = JOBS.get(job_id)
+        if not payload and job:
+            payload = dict(job)
+    if not payload:
+        return jsonify({"error": "Job not found."}), 404
+    if payload.get("kind") not in {"research", "geo"}:
+        return jsonify({"error": "Only Regional Prospecting and Company Research jobs can be stopped."}), 400
+    if payload.get("status") not in {"queued", "running"}:
+        return jsonify({"error": "This job is not running."}), 400
+
+    pid = payload.get("pid")
+    if job:
+        update_job(job_id, status="canceled", finished_at=now(), error="Stopped by user.")
+        append_log(job_id, "Stop requested by user.")
+    else:
+        db_update_interaction(job_id, status="canceled", finished_at=now(), error="Stopped by user.")
+
+    if payload.get("kind") == "geo":
+        return jsonify({"success": True, "status": "canceled"})
+
+    if pid:
+        try:
+            stop_process_tree(int(pid))
+        except Exception as exc:
+            append_log(job_id, f"Stop command failed: {type(exc).__name__}: {exc}")
+            return jsonify({"error": f"Could not stop process: {exc}"}), 500
+
+    return jsonify({"success": True, "status": "canceled"})
+
+@ai_bp.get("/api/history")
+def api_history():
+    limit = clean_int(request.args.get("limit"), 80, 1, 250)
+    kind = str(request.args.get("kind") or "").strip()
+    if kind == "geo":
+        db_prune_geo_history(20)
+    return jsonify(db_list_interactions(limit, kind))
+
+@ai_bp.get("/api/geo-history")
+def api_geo_history():
+    limit = clean_int(request.args.get("limit"), 20, 1, 100)
+    db_prune_geo_history(20)
+    return jsonify(db_list_interactions(limit, "geo"))
+
+@ai_bp.get("/api/ocr-history")
+def api_ocr_history():
+    limit = clean_int(request.args.get("limit"), 20, 1, 100)
+    return jsonify(db_list_interactions(limit, "ocr"))
+
+@ai_bp.post("/api/agentspace/chat")
+def api_agentspace_chat():
+    import os
+    import requests
+
+    payload = request.get_json(force=True, silent=True) or {}
+    messages = payload.get("messages", [])
+
+    agentspace_system_prompt = """You are ProspectIQ's intelligent AI Assistant (Agent Space).
+Your goal is to help users interact with their CRM data, analyze business cards, run company research, and manage sales workflows.
+
+CRITICAL BEHAVIOR & CONVERSATIONAL RULES:
+1. Be Conversational and Helpful: If the user gives a clear prompt, fulfill it directly. If their request is ambiguous, unclear, or missing key details, do NOT give a blunt error or make assumptions. Instead, ask friendly clarifying follow-up questions to help them clarify their intent.
+2. Suggest MCQ Options for Ambiguity: When a question or command is ambiguous or could mean multiple things, present a clear Multiple-Choice Question (MCQ) numbered list (e.g., 1) Option A\n2) Option B) so the user can easily select the right path.
+3. Distinguish Between Contacts vs. Users/Roles:
+   - External CRM Contacts: People working at client/prospect companies (buyers, decision-makers, managers). Added to CRM under a specific Company.
+   - Internal Users/Representatives: Team members (BD Reps, Admins, Viewers) who log into ProspectIQ to manage pipelines.
+   If the user says "add user", "add role", "add rep", or mentions login roles/permissions, this is an INTERNAL representative, NOT a CRM contact. If ambiguous, ask an MCQ clarifying whether they mean an Internal Team Member or an External CRM Contact.
+4. CRM Database Queries vs. External Prospecting:
+   - If the user asks for something like "list top 3 companies from database", "show all companies currently in new stage", "show/sow companies in CRM", or questions about existing saved records or pipeline stages, answer using the loaded CRM context or direct them to CRM (`filter_companies`). NEVER suggest or trigger external Regional Prospecting (`geo`) or Company Research when they explicitly ask about pipeline stages ("new stage", "shortlisted", etc.) or existing records already in the CRM/database.
+5. Clean Company & Attribute Extraction: When adding or editing companies with descriptive prompts, ALWAYS isolate the clean short company name (e.g. "Abel music house") without trailing clauses. Put leadership (CEO, VP) or extra context into notes, geographic location into province/city, business type into industry, and average staff into size_staff. If decision makers or executives are mentioned (e.g. "CEO is Sarah Connor, VP is Kyle Reese"), include them in a "contacts" array inside "company_data" (e.g. [{"first_name": "Sarah", "last_name": "Connor", "title": "CEO", "is_primary": true}, {"first_name": "Kyle", "last_name": "Reese", "title": "VP", "is_primary": false}]) so they are automatically added to the Contacts CRM table alongside the company!"""
+
+    if messages and messages[0].get("role") == "system":
+        messages[0]["content"] = agentspace_system_prompt + "\n\n--- Current Loaded Context & Instructions ---\n" + str(messages[0].get("content", ""))
+    else:
+        messages.insert(0, {"role": "system", "content": agentspace_system_prompt})
+
+    # Extract user query
+    user_query = ""
+    for msg in reversed(messages):
+        if msg.get("role") == "user":
+            user_query = msg.get("content")
+            break
+
+    # Log chat job in database
+    job_id = new_job("chat", user_query or "Chat Session", {"messages": messages})
+    update_job(job_id, status="running", started_at=now())
+
+    gemini_key = get_gemini_key()
+    gemini_error = ""
+
+    try:
+        if gemini_key:
+            res = requests.post(
+                "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {gemini_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": "gemini-2.5-flash-lite",
+                    "service_tier": "priority",
+                    "messages": messages,
+                    "temperature": 0.7,
+                    "max_tokens": 1500,
+                },
+                timeout=30,
+            )
+            if res.ok:
+                data = res.json()
+                reply = data["choices"][0]["message"]["content"]
+                update_job(
+                    job_id,
+                    status="completed",
+                    finished_at=now(),
+                    result={
+                        "reply": reply,
+                        "messages": messages + [{"role": "assistant", "content": reply}],
+                        "provider": "gemini",
+                        "service_tier": "priority",
+                    }
+                )
+                return jsonify({"reply": reply})
+            gemini_error = f"Gemini Error: {res.status_code} - {res.text}"
+
+        openrouter_key = os.environ.get("OPENROUTER_API_KEY", "").strip()
+        openrouter_error = ""
+        if openrouter_key:
+            res = requests.post(
+                "https://openrouter.ai/api/v1/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {openrouter_key}",
+                    "Content-Type": "application/json",
+                    "HTTP-Referer": "http://localhost:5000",
+                    "X-Title": "ProspectIQ"
+                },
+                json={
+                    "model": "google/gemini-2.5-flash-lite",
+                    "messages": messages,
+                    "temperature": 0.7,
+                    "max_tokens": 1500,
+                },
+                timeout=30,
+            )
+            if res.ok:
+                data = res.json()
+                reply = data["choices"][0]["message"]["content"]
+                update_job(
+                    job_id,
+                    status="completed",
+                    finished_at=now(),
+                    result={
+                        "reply": reply,
+                        "messages": messages + [{"role": "assistant", "content": reply}],
+                        "provider": "openrouter",
+                    }
+                )
+                return jsonify({"reply": reply})
+            openrouter_error = f"OpenRouter Error: {res.status_code} - {res.text}"
+        else:
+            openrouter_error = "OPENROUTER_API_KEY is not configured."
+
+        # --- Claude API Fallback ---
+        try:
+            import anthropic
+            claude_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+            if not claude_key:
+                raise ValueError("ANTHROPIC_API_KEY is not configured.")
+
+            client = anthropic.Anthropic(api_key=claude_key)
+
+            system_msg = ""
+            anthropic_messages = []
+
+            for msg in messages:
+                if msg.get("role") == "system":
+                    system_msg = msg.get("content")
+                else:
+                    anthropic_messages.append(msg)
+
+            kwargs = {
+                "model": "claude-haiku-4-5",
+                "max_tokens": 4096,
+                "messages": anthropic_messages
+            }
+            if system_msg:
+                kwargs["system"] = system_msg
+
+            full_response = ""
+            max_continuations = 5
+            continuation_count = 0
+
+            while True:
+                claude_res = client.messages.create(**kwargs)
+
+                for block in claude_res.content:
+                    if block.type == "text":
+                        full_response += block.text
+
+                stop_reason = claude_res.stop_reason
+
+                if stop_reason == "end_turn":
+                    break
+                elif stop_reason == "max_tokens":
+                    continuation_count += 1
+                    if continuation_count >= max_continuations:
+                        break
+
+                    kwargs["messages"].append({"role": "assistant", "content": claude_res.content})
+                    kwargs["messages"].append({
+                        "role": "user",
+                        "content": "Your previous response was cut off. Please continue exactly from where you left off."
+                    })
+                elif stop_reason == "refusal":
+                    full_response += "\n\n[Refusal: Claude declined to respond]"
+                    break
+                else:
+                    break
+
+            reply = full_response
+
+            update_job(
+                job_id,
+                status="completed",
+                finished_at=now(),
+                result={
+                    "reply": reply,
+                    "messages": messages + [{"role": "assistant", "content": reply}],
+                    "provider": "claude",
+                }
+            )
+            return jsonify({"reply": reply})
+        except Exception as claude_exc:
+            error_msg = f"{gemini_error} | {openrouter_error} | Claude Error: {str(claude_exc)}".strip(" |")
+            update_job(job_id, status="failed", finished_at=now(), error=error_msg)
+            return jsonify({"error": error_msg}), 500
+    except Exception as exc:
+        update_job(job_id, status="failed", finished_at=now(), error=str(exc))
+        return jsonify({"error": str(exc)}), 500
+
+@ai_bp.post("/api/ai/restructure")
+def api_ai_restructure():
+    import os
+    import json
+    import requests
+
+    payload = request.get_json(force=True, silent=True) or {}
+    text = payload.get("text", "")
+    category = payload.get("category", "")
+
+    if not text:
+        return jsonify({"error": "No text provided"}), 400
+
+    openrouter_key, missing_response = get_openrouter_key_response()
+    if missing_response:
+        return missing_response
+    api_url = "https://openrouter.ai/api/v1/chat/completions"
+
+    headers = {
+        "Authorization": f"Bearer {openrouter_key}",
+        "Content-Type": "application/json",
+        "HTTP-Referer": "http://localhost:5000",
+        "X-Title": "ProspectIQ"
+    }
+
+    system_prompt = f"""
+    You are an expert procurement and sourcing assistant.
+    Your task is to extract, clean, and structure raw company research text into a clean list of facts, bullet points, or metric key-value fields.
+    Focus on formatting the category: {category}.
+    Format the response as a clean, structured JSON object with a list of key-value pairs or sections, so it can be parsed and rendered inside a dashboard.
+    Response must be ONLY valid JSON in this format (no markdown code blocks, no backticks, no other text):
+    {{
+        "title": "Category Name",
+        "sections": [
+            {{
+                "heading": "Section Heading",
+                "items": [
+                    {{"label": "Label name", "detail": "Detail text"}}
+                ]
+            }}
+        ]
+    }}
+    """
+
+    req_payload = {
+        "model": "openai/gpt-oss-120b",
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": text}
+        ],
+        "temperature": 0.3,
+        "max_tokens": 1200
+    }
+
+    try:
+        res = requests.post(api_url, headers=headers, json=req_payload)
+        if not res.ok:
+            return jsonify({"error": f"API Error: {res.status_code} - {res.text}"}), 502
+        data = res.json()
+        content = data["choices"][0]["message"]["content"]
+        content = content.replace("```json", "").replace("```", "").strip()
+        # Ensure it is valid JSON
+        parsed = json.loads(content)
+        return jsonify(parsed)
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@ai_bp.post("/api/ai/fit-analysis")
+def api_ai_fit_analysis():
+    import os
+    import json
+    import requests
+    import hashlib
+    from db import cache_get, cache_set
+
+    payload = request.get_json(force=True, silent=True) or {}
+    company_name = payload.get("company_name", "the company")
+    staff_size = payload.get("staff_size", 0)
+    industry = payload.get("industry", "")
+    expansion = payload.get("expansion", "")
+
+    # Generate cache key
+    input_str = f"{company_name.lower().strip()}:{staff_size}:{industry.lower().strip()}:{expansion.lower().strip()}"
+    input_hash = hashlib.md5(input_str.encode('utf-8')).hexdigest()
+    cache_key = f"prospectiq:fit_analysis:{input_hash}"
+
+    cached_val = cache_get(cache_key)
+    if cached_val is not None:
+        return jsonify(cached_val)
+
+    openrouter_key, missing_response = get_openrouter_key_response()
+    if missing_response:
+        return missing_response
+    api_url = "https://openrouter.ai/api/v1/chat/completions"
+
+    headers = {
+        "Authorization": f"Bearer {openrouter_key}",
+        "Content-Type": "application/json",
+        "HTTP-Referer": "http://localhost:5000",
+        "X-Title": "ProspectIQ"
+    }
+
+    system_prompt = """
+    You are an expert sales analyst for a corporate office water supply service (recurring 20-litre cans).
+    Assess this company's compatibility for water supply services.
+    Assign a fit grade (High, Medium, or Low), estimate weekly consumption (number of cans, e.g. 40-60 cans/week), list 3 key compatibility drivers (short phrases), and write a 2-sentence rationale.
+    Return ONLY a valid JSON object in this format (no backticks, no other text):
+    {
+        "grade": "High",
+        "estimated_cans": "40-60 cans/week",
+        "drivers": [
+            "Driver 1...",
+            "Driver 2...",
+            "Driver 3..."
+        ],
+        "rationale": "Rationale..."
+    }
+    """
+
+    user_content = f"Company: {company_name}\nStaff Size: {staff_size}\nIndustry: {industry}\nExpansion/Sourcing signals: {expansion}"
+
+    req_payload = {
+        "model": "openai/gpt-oss-120b",
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content}
+        ],
+        "temperature": 0.3,
+        "max_tokens": 800
+    }
+
+    try:
+        res = requests.post(api_url, headers=headers, json=req_payload)
+        if not res.ok:
+            raise RuntimeError(f"API Error: {res.status_code}")
+        data = res.json()
+        content = data["choices"][0]["message"]["content"]
+        content = content.replace("```json", "").replace("```", "").strip()
+        parsed = json.loads(content)
+
+        # Save to database if company_id is present
+        company_id = payload.get("company_id")
+        if company_id:
+            try:
+                from db import get_db_connection
+                with get_db_connection() as conn:
+                    with conn.cursor() as cursor:
+                        cursor.execute(
+                            "SELECT id FROM ai_field_values WHERE company_id = ? AND field_name = ?",
+                            (int(company_id), "ai_fit_analysis")
+                        )
+                        row = cursor.fetchone()
+                        if row:
+                            cursor.execute(
+                                "UPDATE ai_field_values SET value = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+                                (json.dumps(parsed), row[0])
+                            )
+                        else:
+                            cursor.execute(
+                                "INSERT INTO ai_field_values (company_id, field_name, value) VALUES (?, ?, ?)",
+                                (int(company_id), "ai_fit_analysis", json.dumps(parsed))
+                            )
+            except Exception as e:
+                print(f"Error persisting fit analysis to DB: {e}")
+
+        # Cache successful briefing for 24 hours
+        cache_set(cache_key, parsed, timeout=86400)
+        return jsonify(parsed)
+    except Exception as exc:
+        # Fallback response
+        fallback = {
+            "grade": "High" if int(staff_size or 0) > 100 else "Medium",
+            "estimated_cans": f"{max(5, int(staff_size or 0) // 10)}-{max(10, int(staff_size or 0) // 5)} cans/week",
+            "drivers": [
+                f"Headcount of {staff_size} requires consistent workspace amenities.",
+                f"Sourcing signals indicate facility operational scales.",
+                "High office/facility density boosts water replenishment rate."
+            ],
+            "rationale": f"{company_name} presents a strong opportunity due to its operational scale. The active headcount and office layout support a recurring hydration contract."
+        }
+
+        # Save fallback to database if company_id is present
+        company_id = payload.get("company_id")
+        if company_id:
+            try:
+                from db import get_db_connection
+                with get_db_connection() as conn:
+                    with conn.cursor() as cursor:
+                        cursor.execute(
+                            "SELECT id FROM ai_field_values WHERE company_id = ? AND field_name = ?",
+                            (int(company_id), "ai_fit_analysis")
+                        )
+                        row = cursor.fetchone()
+                        if row:
+                            cursor.execute(
+                                "UPDATE ai_field_values SET value = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+                                (json.dumps(fallback), row[0])
+                            )
+                        else:
+                            cursor.execute(
+                                "INSERT INTO ai_field_values (company_id, field_name, value) VALUES (?, ?, ?)",
+                                (int(company_id), "ai_fit_analysis", json.dumps(fallback))
+                            )
+            except Exception as e:
+                print(f"Error persisting fit analysis fallback to DB: {e}")
+
+        # Cache fallback for 1 hour
+        cache_set(cache_key, fallback, timeout=3600)
+        return jsonify(fallback)
+
+@ai_bp.post("/api/ai/briefing")
+def api_ai_briefing():
+    import os
+    import json
+    import requests
+    import hashlib
+    from db import cache_get, cache_set
+
+    payload = request.get_json(force=True, silent=True) or {}
+    company_name = payload.get("company_name", "the company")
+    contact_name = payload.get("contact_name", "Facilities Team")
+    contact_title = payload.get("contact_title", "Facilities Representative")
+    triggers = payload.get("triggers", "")
+
+    # Generate cache key
+    input_str = f"{company_name.lower().strip()}:{contact_name.lower().strip()}:{contact_title.lower().strip()}:{triggers.lower().strip()}"
+    input_hash = hashlib.md5(input_str.encode('utf-8')).hexdigest()
+    cache_key = f"prospectiq:briefing:{input_hash}"
+
+    cached_val = cache_get(cache_key)
+    if cached_val is not None:
+        return jsonify(cached_val)
+
+    openrouter_key, missing_response = get_openrouter_key_response()
+    if missing_response:
+        return missing_response
+    api_url = "https://openrouter.ai/api/v1/chat/completions"
+
+    headers = {
+        "Authorization": f"Bearer {openrouter_key}",
+        "Content-Type": "application/json",
+        "HTTP-Referer": "http://localhost:5000",
+        "X-Title": "ProspectIQ"
+    }
+
+    system_prompt = """
+    You are an AI sales assistant drafting briefing dossiers and cold outreach emails for a corporate water supply vendor.
+    Create a sales briefing dossier (3 bullet points of critical triggers/talking points) and a tailored B2B cold email pitch offering 20-litre recurring water supply services.
+    Address the email to the contact. Refer to their company expansion/recent triggers.
+    Return ONLY a valid JSON object in this format (no backticks, no other text):
+    {
+        "dossier_bullets": [
+            "Point 1...",
+            "Point 2...",
+            "Point 3..."
+        ],
+        "email_subject": "Subject...",
+        "email_body": "Dear [Name],\\n\\n[Body...]"
+    }
+    """
+
+    user_content = f"Company: {company_name}\nContact: {contact_name} ({contact_title})\nTriggers: {triggers}"
+
+    req_payload = {
+        "model": "openai/gpt-oss-120b",
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content}
+        ],
+        "temperature": 0.4,
+        "max_tokens": 1000
+    }
+
+    try:
+        res = requests.post(api_url, headers=headers, json=req_payload)
+        if not res.ok:
+            raise RuntimeError(f"API Error: {res.status_code}")
+        data = res.json()
+        content = data["choices"][0]["message"]["content"]
+        content = content.replace("```json", "").replace("```", "").strip()
+        parsed = json.loads(content)
+
+        # Save to database if company_id is present
+        company_id = payload.get("company_id")
+        if company_id:
+            try:
+                from db import get_db_connection
+                with get_db_connection() as conn:
+                    with conn.cursor() as cursor:
+                        cursor.execute(
+                            "SELECT id FROM ai_field_values WHERE company_id = ? AND field_name = ?",
+                            (int(company_id), "ai_briefing")
+                        )
+                        row = cursor.fetchone()
+                        if row:
+                            cursor.execute(
+                                "UPDATE ai_field_values SET value = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+                                (json.dumps(parsed), row[0])
+                            )
+                        else:
+                            cursor.execute(
+                                "INSERT INTO ai_field_values (company_id, field_name, value) VALUES (?, ?, ?)",
+                                (int(company_id), "ai_briefing", json.dumps(parsed))
+                            )
+            except Exception as e:
+                print(f"Error persisting briefing to DB: {e}")
+
+        # Cache successful briefing for 24 hours
+        cache_set(cache_key, parsed, timeout=86400)
+        return jsonify(parsed)
+    except Exception as exc:
+        # Fallback response
+        fallback = {
+            "dossier_bullets": [
+                f"Refer to {company_name}'s recent headcount growth signals.",
+                f"Focus discussion on facilities and office amenities.",
+                f"Target outreach directly to {contact_name} as the primary operational stakeholder."
+            ],
+            "email_subject": "Sleek and Sustainable Hydration for your Facilities",
+            "email_body": f"Dear {contact_name},\n\nI hope this email finds you well.\n\nGiven your role as {contact_title} at {company_name}, I wanted to reach out regarding your office amenity setups. We specialize in providing premium, high-frequency recurring 20-litre drinking water supply services, customized specifically for dynamic environments like yours.\n\nWe would love to set up a quick 5-minute call to discuss how we can streamline your drinking water supply.\n\nBest regards,\nBD Team"
+        }
+
+        # Save fallback to database if company_id is present
+        company_id = payload.get("company_id")
+        if company_id:
+            try:
+                from db import get_db_connection
+                with get_db_connection() as conn:
+                    with conn.cursor() as cursor:
+                        cursor.execute(
+                            "SELECT id FROM ai_field_values WHERE company_id = ? AND field_name = ?",
+                            (int(company_id), "ai_briefing")
+                        )
+                        row = cursor.fetchone()
+                        if row:
+                            cursor.execute(
+                                "UPDATE ai_field_values SET value = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+                                (json.dumps(fallback), row[0])
+                            )
+                        else:
+                            cursor.execute(
+                                "INSERT INTO ai_field_values (company_id, field_name, value) VALUES (?, ?, ?)",
+                                (int(company_id), "ai_briefing", json.dumps(fallback))
+                            )
+            except Exception as e:
+                print(f"Error persisting briefing fallback to DB: {e}")
+
+        # Cache fallback for 1 hour
+        cache_set(cache_key, fallback, timeout=3600)
+        return jsonify(fallback)

routes/auth.py

@@ -0,0 +1,615 @@
+import bcrypt
+from flask import Blueprint, request, jsonify, session
+from db import get_db_connection, dict_from_row, get_request_user
+
+auth_bp = Blueprint('auth', __name__)
+
+def hash_password(password: str) -> str:
+    salt = bcrypt.gensalt()
+    return bcrypt.hashpw(password.encode('utf-8'), salt).decode('utf-8')
+
+def check_password(password: str, hashed: str) -> bool:
+    return bcrypt.checkpw(password.encode('utf-8'), hashed.encode('utf-8'))
+
+# =====================================================================
+# Registration & Login
+# =====================================================================
+
+@auth_bp.route("/register", methods=["POST"])
+def register():
+    data = request.get_json() or {}
+    org_name = data.get("org_name")
+    admin_name = data.get("name")
+    email = data.get("email")
+    password = data.get("password")
+
+    if not all([org_name, admin_name, email, password]):
+        return jsonify({"error": "All fields are required"}), 400
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        # Check if email exists
+        cursor.execute("SELECT id FROM users WHERE email = ?", (email,))
+        if cursor.fetchone():
+            conn.close()
+            return jsonify({"error": "Email is already registered"}), 400
+
+        # 1. Create Tenant (Organization)
+        cursor.execute(
+            "INSERT INTO tenants (name, brand_color) VALUES (?, ?)",
+            (org_name, "#3b82f6")
+        )
+        # Handle lastrowid for SQLite / Postgres
+        cursor.execute("SELECT last_insert_rowid() FROM tenants") if not hasattr(cursor, 'lastrowid') or cursor.lastrowid is None else None
+        tenant_id = cursor.lastrowid or cursor.fetchone()[0]
+
+        # 2. Seed Default Roles for this Tenant
+        cursor.execute("INSERT INTO roles (tenant_id, name, description) VALUES (?, ?, ?)", (tenant_id, "Admin", "Full administrative access"))
+        cursor.execute("SELECT last_insert_rowid() FROM roles") if not hasattr(cursor, 'lastrowid') or cursor.lastrowid is None else None
+        admin_role_id = cursor.lastrowid or cursor.fetchone()[0]
+
+        cursor.execute("INSERT INTO roles (tenant_id, name, description) VALUES (?, ?, ?)", (tenant_id, "BD Rep", "Access assigned companies and log activities"))
+        cursor.execute("SELECT last_insert_rowid() FROM roles") if not hasattr(cursor, 'lastrowid') or cursor.lastrowid is None else None
+        rep_role_id = cursor.lastrowid or cursor.fetchone()[0]
+
+        cursor.execute("INSERT INTO roles (tenant_id, name, description) VALUES (?, ?, ?)", (tenant_id, "Viewer", "Read-only access"))
+        cursor.execute("SELECT last_insert_rowid() FROM roles") if not hasattr(cursor, 'lastrowid') or cursor.lastrowid is None else None
+        viewer_role_id = cursor.lastrowid or cursor.fetchone()[0]
+
+        # 3. Associate all global permissions to the Admin role
+        cursor.execute("SELECT id FROM permissions")
+        perm_ids = [r[0] for r in cursor.fetchall()]
+        for pid in perm_ids:
+            cursor.execute(
+                "INSERT INTO role_permissions (role_id, permission_id) VALUES (?, ?)",
+                (admin_role_id, pid)
+            )
+
+        # 4. Associate read/write permissions to the BD Rep role
+        cursor.execute("SELECT id FROM permissions WHERE code NOT IN ('users:manage', 'settings:manage')")
+        rep_perm_ids = [r[0] for r in cursor.fetchall()]
+        for pid in rep_perm_ids:
+            cursor.execute(
+                "INSERT INTO role_permissions (role_id, permission_id) VALUES (?, ?)",
+                (rep_role_id, pid)
+            )
+
+        # 5. Associate read permissions to the Viewer role
+        cursor.execute("SELECT id FROM permissions WHERE code IN ('companies:read', 'contacts:read')")
+        viewer_perm_ids = [r[0] for r in cursor.fetchall()]
+        for pid in viewer_perm_ids:
+            cursor.execute(
+                "INSERT INTO role_permissions (role_id, permission_id) VALUES (?, ?)",
+                (viewer_role_id, pid)
+            )
+
+        # 6. Create Admin User
+        pwd_hash = hash_password(password)
+        cursor.execute(
+            "INSERT INTO users (tenant_id, email, name, password_hash, role_id, role) VALUES (?, ?, ?, ?, ?, ?)",
+            (tenant_id, email, admin_name, pwd_hash, admin_role_id, "Admin")
+        )
+        conn.commit()
+        return jsonify({"success": True, "message": "Organization and Admin registered successfully."})
+    except Exception as e:
+        conn.rollback()
+        return jsonify({"error": str(e)}), 500
+    finally:
+        conn.close()
+
+@auth_bp.route("/login", methods=["POST"])
+def login():
+    data = request.get_json() or {}
+    email = data.get("email")
+    password = data.get("password")
+
+    if not email or not password:
+        return jsonify({"error": "Email and password are required"}), 400
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("""
+        SELECT u.id, u.tenant_id, u.email, u.name, u.password_hash, r.name as role_name, u.role_id
+        FROM users u
+        LEFT JOIN roles r ON u.role_id = r.id
+        WHERE u.email = ? AND u.is_active = 1
+    """, (email,))
+    row = cursor.fetchone()
+    conn.close()
+
+    if not row or not row['password_hash'] or not check_password(password, row['password_hash']):
+        return jsonify({"error": "Invalid email or password"}), 401
+
+    # Store user in Flask Session
+    session['user_id'] = row['id']
+    session['tenant_id'] = row['tenant_id']
+    session['user_role'] = row['role_name']
+    session['user_name'] = row['name']
+
+    return jsonify({
+        "success": True,
+        "user": {
+            "id": row['id'],
+            "name": row['name'],
+            "email": row['email'],
+            "role": row['role_name']
+        }
+    })
+
+@auth_bp.route("/me", methods=["GET"])
+def me():
+    if 'user_id' not in session:
+        return jsonify({"authenticated": False}), 401
+
+    # Fetch fresh user permissions and role from DB
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("""
+        SELECT p.code
+        FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?)
+    """, (session['user_id'],))
+    permissions = [r[0] for r in cursor.fetchall()]
+
+    # Also fetch tenant name
+    cursor.execute("SELECT name FROM tenants WHERE id = ?", (session['tenant_id'],))
+    tenant_name = cursor.fetchone()[0]
+    conn.close()
+
+    return jsonify({
+        "authenticated": True,
+        "user": {
+            "id": session['user_id'],
+            "tenant_id": session['tenant_id'],
+            "tenant_name": tenant_name,
+            "name": session['user_name'],
+            "role": session['user_role'],
+            "permissions": permissions
+        }
+    })
+
+@auth_bp.route("/logout", methods=["POST"])
+def logout():
+    session.clear()
+    return jsonify({"success": True})
+
+# =====================================================================
+# Administration & Roles Console
+# =====================================================================
+
+@auth_bp.route("/users", methods=["GET"])
+def get_tenant_users():
+    # Only authenticated users
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    # Check permission
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("""
+        SELECT COUNT(*) FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?) AND p.code = 'users:manage'
+    """, (session['user_id'],))
+    is_admin = cursor.fetchone()[0] > 0
+
+    if not is_admin:
+        conn.close()
+        return jsonify({"error": "Forbidden: Requires user management permission"}), 403
+
+    cursor.execute("""
+        SELECT u.id, u.email, u.name, r.name as role_name, u.role_id, u.is_active
+        FROM users u
+        LEFT JOIN roles r ON u.role_id = r.id
+        WHERE u.tenant_id = ? ORDER BY u.id ASC
+    """, (session['tenant_id'],))
+    rows = cursor.fetchall()
+    users = [dict_from_row(r) for r in rows]
+    conn.close()
+    return jsonify(users)
+
+@auth_bp.route("/admin/dashboard", methods=["GET"])
+def get_admin_dashboard_stats():
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Validate permission
+    cursor.execute("""
+        SELECT COUNT(*) FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?) AND p.code = 'users:manage'
+    """, (session['user_id'],))
+    is_admin = cursor.fetchone()[0] > 0
+    if not is_admin:
+        conn.close()
+        return jsonify({"error": "Forbidden: Requires user management permission"}), 403
+
+    tenant_id = session['tenant_id']
+
+    # 1. Total reps (non-admin roles)
+    cursor.execute("""
+        SELECT COUNT(*)
+        FROM users u
+        LEFT JOIN roles r ON u.role_id = r.id
+        WHERE u.tenant_id = ? AND r.name != 'Admin'
+    """, (tenant_id,))
+    total_reps = cursor.fetchone()[0]
+
+    # 2. Total active reps
+    cursor.execute("""
+        SELECT COUNT(*)
+        FROM users u
+        LEFT JOIN roles r ON u.role_id = r.id
+        WHERE u.tenant_id = ? AND r.name != 'Admin' AND u.is_active = 1
+    """, (tenant_id,))
+    active_reps = cursor.fetchone()[0]
+
+    # 3. Total companies in organization
+    cursor.execute("SELECT COUNT(*) FROM companies WHERE tenant_id = ?", (tenant_id,))
+    total_companies = cursor.fetchone()[0]
+
+    # 4. Total activities in organization
+    cursor.execute("""
+        SELECT COUNT(*)
+        FROM activities a
+        JOIN users u ON a.user_id = u.id
+        WHERE u.tenant_id = ?
+    """, (tenant_id,))
+    total_activities = cursor.fetchone()[0]
+
+    # Fetch list of reps with stats
+    cursor.execute("""
+        SELECT
+            u.id,
+            u.name,
+            u.email,
+            u.is_active,
+            r.name as role_name,
+            (SELECT COUNT(*) FROM companies c WHERE c.assigned_rep_id = u.id) as assigned_companies,
+            (SELECT COUNT(*) FROM activities a WHERE a.user_id = u.id) as total_activities,
+            u.role_id
+        FROM users u
+        LEFT JOIN roles r ON u.role_id = r.id
+        WHERE u.tenant_id = ? AND r.name != 'Admin'
+        ORDER BY u.id ASC
+    """, (tenant_id,))
+
+    reps = []
+    for row in cursor.fetchall():
+        reps.append({
+            "id": row[0],
+            "name": row[1],
+            "email": row[2],
+            "is_active": row[3],
+            "role_name": row[4],
+            "assigned_companies": row[5],
+            "total_activities": row[6],
+            "role_id": row[7]
+        })
+
+    conn.close()
+
+    return jsonify({
+        "stats": {
+            "total_reps": total_reps,
+            "active_reps": active_reps,
+            "total_companies": total_companies,
+            "total_activities": total_activities
+        },
+        "reps": reps
+    })
+
+@auth_bp.route("/users/create", methods=["POST"])
+def create_tenant_user():
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Validate permission
+    cursor.execute("""
+        SELECT COUNT(*) FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?) AND p.code = 'users:manage'
+    """, (session['user_id'],))
+    is_admin = cursor.fetchone()[0] > 0
+    if not is_admin:
+        conn.close()
+        return jsonify({"error": "Forbidden: Requires user management permission"}), 403
+
+    data = request.get_json() or {}
+    name = data.get("name")
+    email = data.get("email")
+    password = data.get("password")
+    role_id = data.get("role_id")
+
+    if not all([name, email, password, role_id]):
+        conn.close()
+        return jsonify({"error": "Missing required user fields"}), 400
+
+    try:
+        # Check if email exists
+        cursor.execute("SELECT id FROM users WHERE email = ?", (email,))
+        if cursor.fetchone():
+            conn.close()
+            return jsonify({"error": "Email is already registered"}), 400
+
+        # Validate that the role belongs to this tenant
+        cursor.execute("SELECT name FROM roles WHERE id = ? AND tenant_id = ?", (role_id, session['tenant_id']))
+        role_row = cursor.fetchone()
+        if not role_row:
+            conn.close()
+            return jsonify({"error": "Invalid role selected"}), 400
+        role_name = role_row[0]
+
+        if role_name.strip().lower() == "admin":
+            conn.close()
+            return jsonify({"error": "Creating additional Administrator accounts is disabled. Only BD Rep and Viewer roles can be created."}), 400
+
+        pwd_hash = hash_password(password)
+        cursor.execute("""
+            INSERT INTO users (tenant_id, email, name, password_hash, role_id, role)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """, (session['tenant_id'], email, name, pwd_hash, role_id, role_name))
+        conn.commit()
+        return jsonify({"success": True, "message": "User created successfully."})
+    except Exception as e:
+        conn.rollback()
+        return jsonify({"error": str(e)}), 500
+    finally:
+        conn.close()
+
+@auth_bp.route("/roles", methods=["GET"])
+def get_tenant_roles():
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Fetch roles and their permissions list
+    cursor.execute("""
+        SELECT id, name, description
+        FROM roles
+        WHERE tenant_id = ? ORDER BY id ASC
+    """, (session['tenant_id'],))
+    roles = [dict_from_row(r) for r in cursor.fetchall()]
+
+    for r in roles:
+        cursor.execute("""
+            SELECT p.code
+            FROM role_permissions rp
+            JOIN permissions p ON rp.permission_id = p.id
+            WHERE rp.role_id = ?
+        """, (r['id'],))
+        r['permissions'] = [row[0] for row in cursor.fetchall()]
+
+    conn.close()
+    return jsonify(roles)
+
+@auth_bp.route("/permissions", methods=["GET"])
+def get_all_permissions():
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT id, code, description FROM permissions ORDER BY id ASC")
+    permissions = [dict_from_row(r) for r in cursor.fetchall()]
+    conn.close()
+    return jsonify(permissions)
+
+@auth_bp.route("/roles/<int:role_id>/permissions", methods=["POST"])
+def update_role_permissions(role_id):
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Validate permission to manage users/roles
+    cursor.execute("""
+        SELECT COUNT(*) FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?) AND p.code = 'users:manage'
+    """, (session['user_id'],))
+    is_admin = cursor.fetchone()[0] > 0
+    if not is_admin:
+        conn.close()
+        return jsonify({"error": "Forbidden: Requires role management permission"}), 403
+
+    # Validate that role belongs to the current tenant
+    cursor.execute("SELECT name FROM roles WHERE id = ? AND tenant_id = ?", (role_id, session['tenant_id']))
+    role_row = cursor.fetchone()
+    if not role_row:
+        conn.close()
+        return jsonify({"error": "Role not found or access denied"}), 404
+
+    # Do not allow modifying the primary 'Admin' role's permissions to prevent lock-outs
+    if role_row[0] == 'Admin':
+        conn.close()
+        return jsonify({"error": "Cannot modify permissions of the core Admin role"}), 400
+
+    data = request.get_json() or {}
+    permission_codes = data.get("permissions", [])
+
+    try:
+        # Delete existing permissions mapping
+        cursor.execute("DELETE FROM role_permissions WHERE role_id = ?", (role_id,))
+
+        # Resolve permission codes to IDs
+        if permission_codes:
+            # Prepare SQL IN clause safely
+            placeholders = ",".join(["?"] * len(permission_codes))
+            cursor.execute(f"SELECT id FROM permissions WHERE code IN ({placeholders})", tuple(permission_codes))
+            perm_ids = [r[0] for r in cursor.fetchall()]
+
+            # Insert new mappings
+            for pid in perm_ids:
+                cursor.execute("INSERT INTO role_permissions (role_id, permission_id) VALUES (?, ?)", (role_id, pid))
+
+        conn.commit()
+        return jsonify({"success": True, "message": "Role permissions updated successfully."})
+    except Exception as e:
+        conn.rollback()
+        return jsonify({"error": str(e)}), 500
+    finally:
+        conn.close()
+
+@auth_bp.route("/roles/create", methods=["POST"])
+def create_custom_role():
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Validate permission
+    cursor.execute("""
+        SELECT COUNT(*) FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?) AND p.code = 'users:manage'
+    """, (session['user_id'],))
+    is_admin = cursor.fetchone()[0] > 0
+    if not is_admin:
+        conn.close()
+        return jsonify({"error": "Forbidden: Requires role management permission"}), 403
+
+    data = request.get_json() or {}
+    name = data.get("name")
+    description = data.get("description", "")
+
+    if not name:
+        conn.close()
+        return jsonify({"error": "Role name is required"}), 400
+
+    try:
+        cursor.execute("""
+            INSERT INTO roles (tenant_id, name, description)
+            VALUES (?, ?, ?)
+        """, (session['tenant_id'], name, description))
+        conn.commit()
+        return jsonify({"success": True, "message": f"Role '{name}' created successfully."})
+    except Exception as e:
+        conn.rollback()
+        return jsonify({"error": str(e)}), 500
+    finally:
+        conn.close()
+
+@auth_bp.route("/users/<int:target_user_id>/update", methods=["POST"])
+def update_tenant_user(target_user_id):
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Validate permission of caller
+    cursor.execute("""
+        SELECT COUNT(*) FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?) AND p.code = 'users:manage'
+    """, (session['user_id'],))
+    is_admin = cursor.fetchone()[0] > 0
+    if not is_admin:
+        conn.close()
+        return jsonify({"error": "Forbidden"}), 403
+
+    # Check that target user belongs to same tenant
+    cursor.execute("SELECT tenant_id, role_id FROM users WHERE id = ?", (target_user_id,))
+    target_user = cursor.fetchone()
+    if not target_user or target_user[0] != session['tenant_id']:
+        conn.close()
+        return jsonify({"error": "User not found in your organization"}), 404
+
+    data = request.get_json() or {}
+    role_id = data.get("role_id")
+    is_active = data.get("is_active") # 0 or 1
+    name = data.get("name")
+    email = data.get("email")
+
+    if role_id is not None:
+        # Verify role_id belongs to the tenant
+        cursor.execute("SELECT name FROM roles WHERE id = ? AND tenant_id = ?", (role_id, session['tenant_id']))
+        role_row = cursor.fetchone()
+        if not role_row:
+            conn.close()
+            return jsonify({"error": "Invalid role selection"}), 400
+
+        # Don't let an admin change their own role or remove the last admin role
+        if target_user_id == session['user_id'] and role_row[0] != 'Admin':
+            conn.close()
+            return jsonify({"error": "You cannot remove your own Admin privileges"}), 400
+
+        # Admin restriction guard: cannot assign Admin role to others
+        if target_user_id != session['user_id'] and role_row[0].strip().lower() == "admin":
+            conn.close()
+            return jsonify({"error": "Creating additional Administrator accounts is disabled."}), 400
+
+        cursor.execute("UPDATE users SET role_id = ?, role = ? WHERE id = ?", (role_id, role_row[0], target_user_id))
+
+    if is_active is not None:
+        if target_user_id == session['user_id'] and int(is_active) == 0:
+            conn.close()
+            return jsonify({"error": "You cannot deactivate your own account"}), 400
+        cursor.execute("UPDATE users SET is_active = ? WHERE id = ?", (int(is_active), target_user_id))
+
+    if name:
+        cursor.execute("UPDATE users SET name = ? WHERE id = ?", (name, target_user_id))
+    if email:
+        cursor.execute("UPDATE users SET email = ? WHERE id = ?", (email, target_user_id))
+
+    conn.commit()
+    conn.close()
+    return jsonify({"success": True})
+
+@auth_bp.route("/users/<int:target_user_id>/delete", methods=["POST"])
+def delete_tenant_user(target_user_id):
+    if 'user_id' not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Validate permission
+    cursor.execute("""
+        SELECT COUNT(*) FROM role_permissions rp
+        JOIN permissions p ON rp.permission_id = p.id
+        WHERE rp.role_id = (SELECT role_id FROM users WHERE id = ?) AND p.code = 'users:manage'
+    """, (session['user_id'],))
+    is_admin = cursor.fetchone()[0] > 0
+    if not is_admin:
+        conn.close()
+        return jsonify({"error": "Forbidden"}), 403
+
+    if target_user_id == session['user_id']:
+        conn.close()
+        return jsonify({"error": "You cannot delete your own account"}), 400
+
+    # Verify target belongs to same tenant
+    cursor.execute("SELECT tenant_id FROM users WHERE id = ?", (target_user_id,))
+    target_user = cursor.fetchone()
+    if not target_user or target_user[0] != session['tenant_id']:
+        conn.close()
+        return jsonify({"error": "User not found in your organization"}), 404
+
+    try:
+        cursor.execute("DELETE FROM users WHERE id = ?", (target_user_id,))
+        conn.commit()
+        success = True
+        error_msg = None
+    except Exception as e:
+        success = False
+        error_msg = "This user has active pipeline history (assigned companies or activities) and cannot be deleted. Deactivate their account instead."
+
+    conn.close()
+    if success:
+        return jsonify({"success": True})
+    else:
+        return jsonify({"error": error_msg}), 409

routes/command.py

@@ -0,0 +1,1246 @@
+import os
+import json
+import re
+import datetime
+import requests
+from flask import Blueprint, request, jsonify, session
+from db import get_db_connection
+from routes.auth import hash_password
+from services.ai_service import clean_int, db_list_interactions, db_list_interactions_by_kinds
+from services.tool_router import heuristic_tool_route, normalize_tool_route, save_tool_route
+
+def db_handle_rep_command(action, query_data, tenant_id):
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        if action == "add_rep":
+            name = query_data.get("name")
+            email = query_data.get("email")
+            role_name = query_data.get("role", "BD Rep")
+
+            if role_name.strip().lower() == "admin":
+                return {"action": "answer", "reply": "Creating additional Administrator accounts is disabled. Only BD Rep and Viewer roles can be created."}
+            password = query_data.get("password", "password123")
+            is_active = int(query_data.get("is_active", 1))
+
+            if not name or not email:
+                return {"action": "answer", "reply": "Representative registration requires both a name and a valid email address."}
+
+            # Check duplicate email
+            cursor.execute("SELECT id FROM users WHERE email = ?", (email,))
+            if cursor.fetchone():
+                return {"action": "answer", "reply": f"The email {email} is already registered."}
+
+            # Get role ID
+            cursor.execute("SELECT id FROM roles WHERE tenant_id = ? AND LOWER(name) = LOWER(?)", (tenant_id, role_name))
+            role_row = cursor.fetchone()
+            if not role_row:
+                cursor.execute("SELECT id FROM roles WHERE tenant_id = ? AND name = ?", (tenant_id, "BD Rep"))
+                role_row = cursor.fetchone()
+            role_id = role_row[0] if role_row else 1
+
+            pwd_hash = hash_password(password)
+            cursor.execute("""
+                INSERT INTO users (tenant_id, email, name, password_hash, role_id, role, is_active)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            """, (tenant_id, email, name, pwd_hash, role_id, role_name, is_active))
+            conn.commit()
+            return {"action": "refresh_reps", "reply": f"Successfully registered new representative: {name} ({email}) as {role_name}."}
+
+        elif action == "edit_rep":
+            target_user_id = query_data.get("target_user_id")
+            email_lookup = query_data.get("email_lookup")
+
+            # Find user
+            if target_user_id:
+                cursor.execute("SELECT id, name, email, role_id FROM users WHERE id = ? AND tenant_id = ?", (target_user_id, tenant_id))
+            elif email_lookup:
+                cursor.execute("SELECT id, name, email, role_id FROM users WHERE LOWER(email) = LOWER(?) AND tenant_id = ?", (email_lookup, tenant_id))
+            else:
+                return {"action": "answer", "reply": "Could not identify the representative to edit."}
+
+            user_row = cursor.fetchone()
+            if not user_row:
+                return {"action": "answer", "reply": "Representative not found."}
+            uid, cur_name, cur_email, cur_role_id = user_row[0], user_row[1], user_row[2], user_row[3]
+
+            rep_data = query_data.get("rep_data", {})
+            new_name = rep_data.get("name", cur_name)
+            new_email = rep_data.get("email", cur_email)
+            new_role_name = rep_data.get("role")
+            new_is_active = rep_data.get("is_active")
+            new_password = rep_data.get("password")
+
+            if new_role_name and new_role_name.strip().lower() == "admin":
+                return {"action": "answer", "reply": "Elevating a user to Administrator is disabled. Only BD Rep and Viewer roles can be assigned."}
+
+            if uid == 1:
+                if new_is_active is not None and int(new_is_active) == 0:
+                    return {"action": "answer", "reply": "The primary Administrator account cannot be deactivated."}
+                if new_role_name and new_role_name.strip().lower() != "admin":
+                    return {"action": "answer", "reply": "The primary Administrator account's role cannot be changed."}
+
+            new_role_id = cur_role_id
+            if new_role_name:
+                cursor.execute("SELECT id FROM roles WHERE tenant_id = ? AND LOWER(name) = LOWER(?)", (tenant_id, new_role_name))
+                role_row = cursor.fetchone()
+                if role_row:
+                    new_role_id = role_row[0]
+                else:
+                    new_role_name = None
+
+            if new_password:
+                pwd_hash = hash_password(new_password)
+                cursor.execute("UPDATE users SET password_hash = ? WHERE id = ?", (pwd_hash, uid))
+            if new_is_active is not None:
+                if int(new_is_active) == 0 and uid == session.get('user_id'):
+                    return {"action": "answer", "reply": "You cannot deactivate your own administrator account."}
+                cursor.execute("UPDATE users SET is_active = ? WHERE id = ?", (int(new_is_active), uid))
+
+            cursor.execute("""
+                UPDATE users SET name = ?, email = ?, role_id = ?, role = COALESCE(?, role)
+                WHERE id = ?
+            """, (new_name, new_email, new_role_id, new_role_name, uid))
+            conn.commit()
+            return {"action": "refresh_reps", "reply": f"Successfully updated representative: {new_name}."}
+
+        elif action == "delete_rep":
+            target_user_id = query_data.get("target_user_id")
+            email_lookup = query_data.get("email_lookup")
+
+            # Find user
+            if target_user_id:
+                cursor.execute("SELECT id, name, email FROM users WHERE id = ? AND tenant_id = ?", (target_user_id, tenant_id))
+            elif email_lookup:
+                cursor.execute("SELECT id, name, email FROM users WHERE LOWER(email) = LOWER(?) AND tenant_id = ?", (email_lookup, tenant_id))
+            else:
+                return {"action": "answer", "reply": "Could not identify the representative to delete."}
+
+            user_row = cursor.fetchone()
+            if not user_row:
+                return {"action": "answer", "reply": "Representative not found."}
+            uid, cur_name, cur_email = user_row[0], user_row[1], user_row[2]
+
+            if uid == session.get('user_id'):
+                return {"action": "answer", "reply": "You cannot delete your own administrator account."}
+
+            try:
+                cursor.execute("SELECT COUNT(*) FROM companies WHERE assigned_rep_id = ?", (uid,))
+                c_cnt = cursor.fetchone()[0]
+                cursor.execute("SELECT COUNT(*) FROM activities WHERE user_id = ?", (uid,))
+                a_cnt = cursor.fetchone()[0]
+
+                if c_cnt > 0 or a_cnt > 0:
+                    return {"action": "answer", "reply": f"Representative {cur_name} cannot be deleted because they have associated pipeline records. Please deactivate them instead."}
+
+                cursor.execute("DELETE FROM users WHERE id = ?", (uid,))
+                conn.commit()
+                return {"action": "refresh_reps", "reply": f"Successfully deleted representative: {cur_name}."}
+            except Exception as del_err:
+                conn.rollback()
+                return {"action": "answer", "reply": f"Could not delete representative: {del_err}. We recommend deactivating their account instead."}
+    except Exception as e:
+        conn.rollback()
+        return {"action": "answer", "reply": f"An error occurred while managing representative: {e}"}
+    finally:
+        conn.close()
+
+command_bp = Blueprint('command', __name__)
+
+GROQ_URL = "https://api.groq.com/openai/v1/chat/completions"
+OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
+
+DEFAULT_STAGE_NAMES = [
+    "New",
+    "Shortlisted",
+    "Research Done",
+    "Contacted",
+    "Engaged",
+    "Meeting Scheduled",
+    "Meeting Done",
+    "Proposal Sent",
+    "Won",
+    "Paused / Not a Fit",
+]
+
+COMMON_LOCATION_WORDS = {
+    "toronto": ("city", "Toronto"),
+    "windsor": ("city", "Windsor"),
+    "brampton": ("city", "Brampton"),
+    "mississauga": ("city", "Mississauga"),
+    "hamilton": ("city", "Hamilton"),
+    "ottawa": ("city", "Ottawa"),
+    "montreal": ("city", "Montreal"),
+    "vancouver": ("city", "Vancouver"),
+    "calgary": ("city", "Calgary"),
+    "pune": ("city", "Pune"),
+    "mumbai": ("city", "Mumbai"),
+    "delhi": ("city", "Delhi"),
+    "bengaluru": ("city", "Bengaluru"),
+    "bangalore": ("city", "Bengaluru"),
+    "chennai": ("city", "Chennai"),
+    "hyderabad": ("city", "Hyderabad"),
+    "ontario": ("province", "Ontario"),
+    "quebec": ("province", "Quebec"),
+    "alberta": ("province", "Alberta"),
+    "california": ("province", "California"),
+}
+
+def _answer(reply):
+    return {"action": "answer", "reply": reply}
+
+def _clean_text(value):
+    return re.sub(r"\s+", " ", str(value or "")).strip()
+
+def _norm(value):
+    return re.sub(r"[^a-z0-9]+", " ", str(value or "").lower()).strip()
+
+def _has_word(query, words):
+    return any(re.search(rf"\b{re.escape(word)}\b", query, re.I) for word in words)
+
+def _has_phrase(query, phrases):
+    normalized = _norm(query)
+    return any(_norm(phrase) in normalized for phrase in phrases)
+
+def _extract_context_list(context, labels):
+    decoder = json.JSONDecoder()
+    for label in labels:
+        idx = context.find(label)
+        if idx < 0:
+            continue
+        start = context.find("[", idx)
+        if start < 0:
+            continue
+        try:
+            value, _ = decoder.raw_decode(context[start:])
+            if isinstance(value, list):
+                return value
+        except Exception:
+            continue
+    return []
+
+def _context_entities(context):
+    return (
+        _extract_context_list(context, ["Full Database (Companies):", "Companies:"]),
+        _extract_context_list(context, ["Full Database (Contacts):", "Contacts:"]),
+    )
+
+def _stage_names(companies):
+    names = []
+    for company in companies:
+        stage = company.get("stage") or company.get("stage_name")
+        if stage and stage not in names:
+            names.append(stage)
+    for stage in DEFAULT_STAGE_NAMES:
+        if stage not in names:
+            names.append(stage)
+    return names
+
+def _stage_id_for_name(companies, stage_name):
+    wanted = _norm(stage_name)
+    for company in companies:
+        if _norm(company.get("stage") or company.get("stage_name")) == wanted and company.get("stage_id"):
+            return company.get("stage_id")
+    stage_order = {name.lower(): idx + 1 for idx, name in enumerate(DEFAULT_STAGE_NAMES)}
+    return stage_order.get(str(stage_name or "").lower())
+
+def _find_company(query, companies):
+    qnorm = _norm(query)
+    id_match = re.search(r"\b(?:company\s*)?id\s*#?\s*(\d+)\b", query, re.I)
+    if id_match:
+        cid = int(id_match.group(1))
+        for company in companies:
+            if int(company.get("id") or 0) == cid:
+                return company
+
+    best = None
+    best_score = 0
+    for company in companies:
+        name = company.get("name") or company.get("company_name") or ""
+        nnorm = _norm(name)
+        if not nnorm:
+            continue
+        score = 0
+        if nnorm and nnorm in qnorm:
+            score = len(nnorm) + 100
+        else:
+            tokens = [token for token in nnorm.split() if len(token) > 2]
+            matched = sum(1 for token in tokens if re.search(rf"\b{re.escape(token)}\b", qnorm))
+            if tokens and matched:
+                score = int((matched / len(tokens)) * 80) + matched
+        if score > best_score:
+            best = company
+            best_score = score
+    return best if best_score >= 45 else None
+
+def _find_contact(query, contacts):
+    qnorm = _norm(query)
+    id_match = re.search(r"\b(?:contact\s*)?id\s*#?\s*(\d+)\b", query, re.I)
+    if id_match:
+        contact_id = int(id_match.group(1))
+        for contact in contacts:
+            if int(contact.get("id") or 0) == contact_id:
+                return contact
+
+    best = None
+    best_score = 0
+    for contact in contacts:
+        full_name = _norm(f"{contact.get('first_name', '')} {contact.get('last_name', '')}")
+        if not full_name:
+            continue
+        if full_name in qnorm:
+            score = len(full_name) + 100
+        else:
+            tokens = [token for token in full_name.split() if len(token) > 1]
+            matched = sum(1 for token in tokens if re.search(rf"\b{re.escape(token)}\b", qnorm))
+            score = int((matched / max(len(tokens), 1)) * 80) if matched else 0
+        if score > best_score:
+            best = contact
+            best_score = score
+    return best if best_score >= 45 else None
+
+def _extract_known_value(query, values):
+    qnorm = _norm(query)
+    for value in sorted([v for v in values if v], key=len, reverse=True):
+        if _norm(value) and re.search(rf"\b{re.escape(_norm(value))}\b", qnorm):
+            return value
+    return ""
+
+def _clean_company_name_candidate(value):
+    name = _clean_text(value.strip(" ,.-"))
+    name = re.split(
+        r"\s+(?:so|then|and\s+then|please)\s+(?:add|create|register|save|put|insert)\b",
+        name,
+        1,
+        flags=re.I,
+    )[0]
+    name = re.split(
+        r"\s+(?:in|at|with|where|who|whose|which|when|located|doing|and\s+they\s+do|staff|size|around|industry|stage|city|province|state|country|phone|website|email|CEO|VP|president|founder)\b|,|\.|\;|\-",
+        name,
+        1,
+        flags=re.I,
+    )[0]
+    name = _clean_text(name.strip(" ,.-"))
+    if _norm(name) in {"it", "them", "this", "that", "these", "those", "him", "her"}:
+        return ""
+    return name
+
+def _extract_company_name_for_add(query):
+    explicit_subject_patterns = [
+        r"\b(?:company|business|supplier|vendor|manufacturer|firm)\s+(?:called|named)\s+(.+?)(?=\s+(?:so|then|and\s+then|please)\s+(?:add|create|register|save|put|insert)\b|$)",
+        r"\b(?:called|named)\s+(.+?)(?=\s+(?:so|then|and\s+then|please)\s+(?:add|create|register|save|put|insert)\b|$)",
+    ]
+    action_patterns = [
+        r"\badd\s+(?:this|that|the)\s+(?:company|supplier|vendor|manufacturer|business)\s+(?:called|named)\s+(.+)$",
+        r"\badd\s+(?:(?:a|the)\s+)?(?:new\s+)?(?:company|supplier|vendor|manufacturer|business)\s+(?:called|named)?\s*(.+)$",
+        r"\bcreate\s+(?:(?:a|the)\s+)?(?:new\s+)?(?:company|supplier|vendor|manufacturer|business)\s+(?:called|named)?\s*(.+)$",
+        r"\bcreate\s+(?:(?:a|the)\s+)?(?:new\s+)?company\s+called\s+(.+)$",
+        r"\b(?:register|save|put|insert)\s+(.+?)\s+(?:as|into|to)\s+(?:a\s+|the\s+)?(?:company|supplier|vendor|manufacturer|business|companies)\b",
+        r"\b(?:add|register|save|put|insert)\s+(.+?)\s+(?:in|into|to)\s+(?:the\s+)?crm\b",
+        r"\b(.+?)\s+should\s+be\s+(?:added|created|registered|saved)\s+(?:as|into|to)\s+(?:a\s+|the\s+)?(?:company|supplier|vendor|manufacturer|business|companies)\b",
+    ]
+    for pattern in explicit_subject_patterns + action_patterns:
+        match = re.search(pattern, query, re.I)
+        if not match:
+            continue
+        name = _clean_company_name_candidate(match.group(1))
+        if name:
+            return name
+    return ""
+
+def _split_trailing_location_from_name(name, known_locations):
+    cleaned = _clean_text(name)
+    lowered = _norm(cleaned)
+    for location in sorted(known_locations, key=len, reverse=True):
+        loc_norm = _norm(location)
+        if loc_norm and lowered.endswith(" " + loc_norm):
+            return _clean_text(cleaned[:-(len(location))].strip(" ,.-")), location
+    return cleaned, ""
+
+def _known_locations(companies):
+    values = set(COMMON_LOCATION_WORDS.keys())
+    for company in companies:
+        for key in ("city", "province", "country"):
+            value = company.get(key)
+            if value:
+                values.add(str(value))
+    return values
+
+def _apply_company_location(company_data, query, raw_name, companies):
+    known_locations = _known_locations(companies)
+    explicit_location = re.search(r"\b(?:in|at|from)\s+([^,]+)", query, re.I)
+    location = _clean_text(explicit_location.group(1)) if explicit_location else ""
+    if location:
+        location = _clean_text(re.split(r"\s+(?:with|industry|stage|city|province|state|country|phone|website|email)\b", location, 1, flags=re.I)[0].strip(" ,.-"))
+        if _norm(location) in {"crm", "the crm"}:
+            location = ""
+    if not location:
+        name_without_location, trailing_location = _split_trailing_location_from_name(raw_name, known_locations)
+        if trailing_location:
+            company_data["name"] = name_without_location
+            location = trailing_location
+
+    if not location:
+        return
+
+    loc_key = _norm(location)
+    loc_type, canonical = COMMON_LOCATION_WORDS.get(loc_key, ("", location))
+    if not loc_type:
+        for company in companies:
+            if _norm(company.get("city")) == loc_key:
+                loc_type, canonical = "city", company.get("city")
+                break
+            if _norm(company.get("province")) == loc_key:
+                loc_type, canonical = "province", company.get("province")
+                break
+    if loc_type == "province":
+        company_data["province"] = canonical
+    else:
+        company_data["city"] = canonical
+
+def _extract_contact_data(query, companies):
+    match = re.search(r"\b(?:add|create|register|save|put)\s+(?:a\s+|new\s+)?contact\s+(.+)$", query, re.I)
+    if not match:
+        match = re.search(r"\b(?:add|create|register|save|put)\s+(.+?)\s+(?:as|into|to)\s+(?:a\s+)?contact\b", query, re.I)
+    if not match:
+        match = re.search(r"\b(.+?)\s+should\s+be\s+(?:added|created|registered|saved)\s+(?:as|into|to)\s+(?:a\s+)?contact\b", query, re.I)
+    if not match:
+        return None
+    tail = match.group(1)
+    name_part = re.split(r"\s+(?:at|for|with|email|phone|title|linkedin)\b|,", tail, 1, flags=re.I)[0]
+    names = _clean_text(name_part).split()
+    if len(names) < 2:
+        return {"error": "Please include both first and last name for the contact."}
+
+    contact_data = {"first_name": names[0], "last_name": " ".join(names[1:])}
+    email = re.search(r"[\w.+-]+@[\w.-]+\.\w+", query)
+    if email:
+        contact_data["email"] = email.group(0)
+    phone = re.search(r"\b(?:phone|mobile|call)\s*(?:is|:)?\s*([+()0-9][+()0-9 .-]{5,})", query, re.I)
+    if phone:
+        contact_data["phone"] = _clean_text(phone.group(1))
+    title = re.search(r"\btitle\s*(?:is|to|:)?\s*([^,]+)", query, re.I)
+    if title:
+        contact_data["title"] = _clean_text(title.group(1))
+    linkedin = re.search(r"\b(?:linkedin|linkedin\s*url|linkedin\s*id)\s*(?:is|to|:)?\s*(\S+)", query, re.I)
+    if linkedin:
+        contact_data["linkedin"] = _clean_text(linkedin.group(1))
+
+    company_id = re.search(r"\bcompany\s*id\s*#?\s*(\d+)\b", query, re.I)
+    if company_id:
+        contact_data["company_id"] = int(company_id.group(1))
+    else:
+        company = _find_company(query, companies)
+        if company:
+            contact_data["company_id"] = company.get("id")
+    if not contact_data.get("company_id"):
+        return {"error": "Please specify which company this contact belongs to, for example: Add contact Jane Mari at Acme Robotics."}
+    return contact_data
+
+def _parse_client_date(client_time):
+    if not client_time:
+        return datetime.date.today()
+    text = str(client_time)
+    for fmt in ("%a %b %d %Y %H:%M:%S", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.datetime.strptime(text[:len(fmt)], fmt).date()
+        except Exception:
+            continue
+    iso_match = re.search(r"\b(\d{4}-\d{2}-\d{2})\b", text)
+    if iso_match:
+        try:
+            return datetime.date.fromisoformat(iso_match.group(1))
+        except Exception:
+            pass
+    return datetime.date.today()
+
+def _parse_task_date(query, client_time):
+    if re.search(r"\b(?:unscheduled|unassigned)\b", query, re.I):
+        return ""
+    base = _parse_client_date(client_time)
+    lowered = query.lower()
+    if re.search(r"\btoday\b", lowered):
+        return base.isoformat()
+    if re.search(r"\btomorrow\b", lowered):
+        return (base + datetime.timedelta(days=1)).isoformat()
+
+    iso_match = re.search(r"\b(\d{4}-\d{2}-\d{2})\b", query)
+    if iso_match:
+        return iso_match.group(1)
+
+    weekdays = {
+        "monday": 0,
+        "tuesday": 1,
+        "wednesday": 2,
+        "thursday": 3,
+        "friday": 4,
+        "saturday": 5,
+        "sunday": 6,
+    }
+    for day_name, day_num in weekdays.items():
+        if re.search(rf"\bnext\s+{day_name}\b", lowered):
+            days_ahead = (day_num - base.weekday()) % 7
+            if days_ahead == 0:
+                days_ahead = 7
+            return (base + datetime.timedelta(days=days_ahead)).isoformat()
+        if re.search(rf"\b{day_name}\b", lowered):
+            days_ahead = (day_num - base.weekday()) % 7
+            return (base + datetime.timedelta(days=days_ahead)).isoformat()
+    return ""
+
+def _parse_task_time(query):
+    if re.search(r"\b(?:unscheduled|unassigned)\b", query, re.I):
+        return ""
+    match = re.search(r"\b(?:at\s*)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)\b", query, re.I)
+    if match:
+        hour = int(match.group(1))
+        minute = int(match.group(2) or 0)
+        suffix = match.group(3).lower()
+        if suffix == "pm" and hour != 12:
+            hour += 12
+        if suffix == "am" and hour == 12:
+            hour = 0
+        return f"{hour:02d}:{minute:02d}"
+    match = re.search(r"\b(?:at\s*)?([01]?\d|2[0-3]):([0-5]\d)\b", query)
+    if match:
+        return f"{int(match.group(1)):02d}:{int(match.group(2)):02d}"
+    return ""
+
+def _extract_task_title(query):
+    cleaned = re.sub(r"\b(?:add|create|schedule|save|put)\s+(?:a\s+|new\s+)?(?:task|todo|to-do|reminder|action)\b", " ", query, flags=re.I)
+    cleaned = re.sub(r"\bremind\s+me\s+to\b", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\bi\s+need\s+to\b", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\b(?:unscheduled|unassigned)\b", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\b(?:next\s+)?(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\b(?:today|tomorrow)\b", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\b\d{4}-\d{2}-\d{2}\b", " ", cleaned)
+    cleaned = re.sub(r"\b(?:at\s*)?\d{1,2}(?::\d{2})?\s*(?:am|pm)\b", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\b(?:at\s*)?(?:[01]?\d|2[0-3]):[0-5]\d\b", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\s+", " ", cleaned).strip(" ,.-")
+    return cleaned
+
+def _infer_command_intent(query):
+    q = _clean_text(query)
+    add_words = ("add", "create", "register", "save", "put", "insert")
+    edit_words = ("change", "update", "set", "edit", "modify")
+    delete_words = ("delete", "remove")
+    view_words = ("open", "show", "view")
+    list_words = ("show", "sow", "shwo", "list", "find", "view", "display", "get", "fetch", "all", "bring", "give")
+    company_words = ("company", "companies", "business", "supplier", "vendor", "manufacturer", "firm")
+    contact_words = ("contact", "person")
+    task_words = ("task", "todo", "to-do", "reminder", "action")
+
+    is_add = _has_word(q, add_words) or _has_phrase(q, ("should be added", "should be registered", "should be saved"))
+    is_edit = _has_word(q, edit_words)
+    is_delete = _has_word(q, delete_words)
+    is_view = _has_word(q, view_words) or re.search(r"\bgo\s+to\b", q, re.I)
+    is_list = _has_word(q, list_words)
+    has_company = _has_word(q, company_words) or _has_phrase(q, ("as a company", "into companies", "to companies"))
+    rep_words = ("rep", "representative", "user", "team member", "role", "admin", "viewer", "bd rep")
+    is_rep = _has_word(q, rep_words)
+    has_contact = (_has_word(q, contact_words) or _has_phrase(q, ("as a contact", "into contacts", "to contacts"))) and not is_rep
+    has_task = _has_word(q, task_words) or re.search(r"\bremind\s+me\s+to\b", q, re.I)
+    if is_add and _has_word(q, ("crm",)) and not has_contact and not has_task and not is_rep:
+        has_company = True
+
+    if (is_add or _has_word(q, ("schedule",)) or re.search(r"\bremind\s+me\s+to\b", q, re.I)) and has_task:
+        return "add_task"
+    if (is_add or _has_phrase(q, ("should be added",))) and has_contact:
+        return "add_contact"
+    if is_edit and (has_contact or (_has_word(q, ("email", "title")) and not has_company and not is_rep)):
+        return "edit_contact"
+    if is_delete and has_contact:
+        return "delete_contact"
+    if is_list and re.search(r"\bcontacts\b", q, re.I):
+        return "filter_contacts"
+    if (is_add or _has_phrase(q, ("should be added", "should be registered", "should be saved"))) and has_company and not has_contact and not has_task and not is_rep:
+        return "add_company"
+    if is_edit and (has_company or _has_word(q, ("stage", "industry", "city", "province", "website", "phone"))):
+        return "edit_company"
+    if is_delete and has_company:
+        return "delete_company"
+    if is_view and re.search(r"\b(?:profile|page|card|company)\b", q, re.I):
+        return "view_company_profile"
+    if (is_list or re.search(r"\b(?:companies|stage|stages|pipeline)\b", q, re.I)) and re.search(r"\b(?:companies|stage|stages|pipeline)\b", q, re.I) and not is_add and not is_edit and not is_delete and not has_task and not is_rep and not has_contact:
+        return "filter_companies"
+    return ""
+
+def deterministic_command_route(query, context, client_time=None):
+    query = _clean_text(query)
+    if not query:
+        return None
+    # 1. Deactivate representative
+    deact_match = re.search(r"\b(?:deactivate|disable|suspend)\s+(?:rep|representative|user|member)?\s*(.+)", query, re.I)
+    if deact_match:
+        target = deact_match.group(1).strip()
+        email_match = re.search(r"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})", target)
+        email_lookup = email_match.group(1) if email_match else None
+        target_name = target
+        if email_lookup:
+            target_name = target.replace(email_lookup, "").strip()
+        return {
+            "action": "edit_rep_handler",
+            "email_lookup": email_lookup,
+            "name_lookup": target_name,
+            "rep_data": {"is_active": 0}
+        }
+
+    # 2. Activate representative
+    act_match = re.search(r"\b(?:activate|enable)\s+(?:rep|representative|user|member)?\s*(.+)", query, re.I)
+    if act_match:
+        target = act_match.group(1).strip()
+        email_match = re.search(r"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})", target)
+        email_lookup = email_match.group(1) if email_match else None
+        target_name = target
+        if email_lookup:
+            target_name = target.replace(email_lookup, "").strip()
+        return {
+            "action": "edit_rep_handler",
+            "email_lookup": email_lookup,
+            "name_lookup": target_name,
+            "rep_data": {"is_active": 1}
+        }
+
+    # 3. Delete representative
+    del_match = re.search(r"\b(?:delete|remove|purge)\s+(?:rep|representative|user|member)\s+(.+)", query, re.I)
+    if del_match:
+        target = del_match.group(1).strip()
+        email_match = re.search(r"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})", target)
+        email_lookup = email_match.group(1) if email_match else None
+        target_name = target
+        if email_lookup:
+            target_name = target.replace(email_lookup, "").strip()
+        return {
+            "action": "delete_rep_handler",
+            "email_lookup": email_lookup,
+            "name_lookup": target_name
+        }
+
+    # 4. Add representative / User / Role
+    add_rep_match = re.search(r"\b(?:add|create|register|new)\s+(?:rep|representative|user|team member|member|role|bd rep|admin|viewer)\b", query, re.I)
+    if add_rep_match:
+        email_match = re.search(r"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})", query)
+        email = email_match.group(1).strip() if email_match else ""
+        # Extract name if present
+        cleaned_query = re.sub(r"\b(?:add|create|register|new)\s+(?:rep|representative|user|team member|member|role|bd rep|admin|viewer)\b", "", query, flags=re.I)
+        if email:
+            cleaned_query = cleaned_query.replace(email, "")
+        cleaned_query = re.sub(r"\b(?:with\s+)?email\b", "", cleaned_query, flags=re.I)
+        cleaned_query = re.sub(r"\bas\s+(?:BD Rep|Admin|Viewer)\b", "", cleaned_query, flags=re.I).strip(" ,.-:")
+        name = cleaned_query or (email.split("@")[0] if email else "")
+        role_name = "BD Rep"
+        if re.search(r"\badmin\b", query, re.I):
+            role_name = "Admin"
+        elif re.search(r"\bviewer\b", query, re.I):
+            role_name = "Viewer"
+
+        if not email or not name:
+            return _answer(
+                "To add an **internal team member (User/Representative)** who logs into ProspectIQ, please provide their **Name**, **Email**, and **Role** (e.g., `BD Rep` or `Viewer`).\n\n"
+                "Example: *Add rep Sarah Connor with email sarah@example.com as BD Rep*.\n\n"
+                "*(Note: If you meant to add an **external CRM Contact** at a client company, please say: Add contact [First Name] [Last Name] for company [Company Name]).*"
+            )
+        return {
+            "action": "add_rep_handler",
+            "name": name,
+            "email": email,
+            "role": role_name
+        }
+
+    # 5. Change role
+    role_match = re.search(r"\b(?:change|set)\s+(?:role|permission)\s+of\s+(.+?)\s+to\s+(Admin|BD Rep|Viewer)", query, re.I)
+    if role_match:
+        target = role_match.group(1).strip()
+        role_name = role_match.group(2).strip()
+        email_match = re.search(r"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})", target)
+        email_lookup = email_match.group(1) if email_match else None
+        target_name = target
+        if email_lookup:
+            target_name = target.replace(email_lookup, "").strip()
+        return {
+            "action": "edit_rep_handler",
+            "email_lookup": email_lookup,
+            "name_lookup": target_name,
+            "rep_data": {"role": role_name}
+        }
+
+    qnorm = _norm(query)
+    companies, contacts = _context_entities(context)
+    stage_names = _stage_names(companies)
+    stage_value = _extract_known_value(query, stage_names)
+    intent = _infer_command_intent(query)
+
+    if re.search(r"\b(?:ocr|business card|scan card|card scan|extract text|read image)\b", query, re.I):
+        return None
+
+    if not intent and _has_word(query, ("delete", "remove")):
+        contact = _find_contact(query, contacts)
+        company = _find_company(query, companies)
+        if contact and not company:
+            intent = "delete_contact"
+        elif company and not contact:
+            intent = "delete_company"
+        elif company and contact:
+            return _answer("Please clarify whether you want to delete the company or the contact.")
+
+    if intent == "view_company_profile":
+        company = _find_company(query, companies)
+        if company:
+            return {"action": "view_company_profile", "company_id": company.get("id"), "company_name": company.get("name")}
+        if not re.search(r"\b(?:research|extract|enrich|company extractor|company research)\b", query, re.I):
+            return _answer("I could not find that company in CRM. Please use the exact company name from the database, or ask me to research it with Company Research.")
+
+    if intent == "filter_contacts":
+        return {"action": "filter_contacts", "filters": {}}
+
+    if intent == "add_task":
+        task_title = _extract_task_title(query)
+        if not task_title:
+            return _answer("Please include the task title. Example: Create task review supplier profile next Monday.")
+        payload = {"action": "add_task", "task_title": task_title}
+        date_value = _parse_task_date(query, client_time)
+        time_value = _parse_task_time(query)
+        if date_value:
+            payload["date"] = date_value
+        if time_value:
+            payload["time"] = time_value
+        return payload
+
+    if intent == "filter_companies":
+        is_crm_explicit = bool(re.search(r"\b(?:database|crm|saved|my companies|already in|in crm|from crm|in database|from database|stage|stages|pipeline|new stage|shortlisted|contacted|engaged|proposal|won|paused)\b", query, re.I))
+        if not is_crm_explicit and (re.search(r"\b(?:near|nearby|around|within|coordinates|latitude|longitude|geo finder|map search|prospect|prospecting)\b", query, re.I) or _has_word(query, ("find", "search", "prospect", "discover"))):
+            return {"action": "tool_route", "tool": "geo", "tool_input": {"query": query}, "auto_start": True, "message": "Opening Regional Prospecting to discover companies matching your search."}
+
+        if is_crm_explicit or not re.search(r"\b(?:near|nearby|around|within|coordinates|latitude|longitude|geo finder|map search|prospect|prospecting)\b", query, re.I):
+            industries = sorted({c.get("industry") for c in companies if c.get("industry")})
+            provinces = sorted({c.get("province") for c in companies if c.get("province")})
+            cities = sorted({c.get("city") for c in companies if c.get("city")})
+            filters = {}
+            industry = _extract_known_value(query, industries)
+            province = _extract_known_value(query, provinces)
+            city = _extract_known_value(query, cities)
+            if industry:
+                filters["industry"] = industry
+            if province:
+                filters["province"] = province
+            if city:
+                filters["city"] = city
+            if stage_value:
+                filters["stage"] = stage_value
+
+            filtered_comps = companies
+            if filters.get("industry"):
+                filtered_comps = [c for c in filtered_comps if _norm(c.get("industry")) == _norm(filters["industry"])]
+            if filters.get("province"):
+                filtered_comps = [c for c in filtered_comps if _norm(c.get("province")) == _norm(filters["province"])]
+            if filters.get("city"):
+                filtered_comps = [c for c in filtered_comps if _norm(c.get("city")) == _norm(filters["city"])]
+            if filters.get("stage"):
+                filtered_comps = [c for c in filtered_comps if _norm(c.get("stage")) == _norm(filters["stage"])]
+
+            top_match = re.search(r"\btop\s+(\d+)\b", query, re.I)
+            reply_text = ""
+            if top_match and filtered_comps:
+                n = min(int(top_match.group(1)), len(filtered_comps)) if top_match.group(1).isdigit() else 3
+                from services.ai_service import clean_int
+                sorted_comps = sorted(filtered_comps, key=lambda c: clean_int(c.get("size_staff") or c.get("maplempss_fit_score") or 0, 0, 0, 1_000_000_000), reverse=True)
+                top_list = sorted_comps[:n]
+                items_str = "\n".join(f"{idx+1}. **{c.get('name')}** (Industry: {c.get('industry') or 'N/A'}, Stage: {c.get('stage') or 'N/A'}, Staff: {c.get('size_staff') or 0})" for idx, c in enumerate(top_list))
+                reply_text = f"Here are the top {n} companies matching your criteria in the CRM database:\n\n{items_str}"
+            elif filtered_comps:
+                items_str = "\n".join(f"{idx+1}. **{c.get('name')}** (Industry: {c.get('industry') or 'N/A'}, Stage: {c.get('stage') or 'N/A'}, Location: {c.get('city') or 'N/A'}, {c.get('province') or 'N/A'})" for idx, c in enumerate(filtered_comps[:20]))
+                if len(filtered_comps) > 20:
+                    items_str += f"\n\n*(And {len(filtered_comps) - 20} more companies shown in the CRM table)*"
+                if filters:
+                    reply_text = f"Here are the {len(filtered_comps)} companies matching your filters in the CRM database:\n\n{items_str}"
+                else:
+                    reply_text = f"Here are the {len(filtered_comps)} companies currently present in your CRM database:\n\n{items_str}"
+            else:
+                reply_text = "No companies matched your criteria in the CRM database."
+
+            view_type = "board" if re.search(r"\b(?:kanban|board)\b", query, re.I) else ("table" if re.search(r"\btable\b", query, re.I) else "")
+            res = {"action": "filter_companies", "filters": filters, "view_type": view_type}
+            if reply_text:
+                res["reply"] = reply_text
+            return res
+
+    if intent == "add_contact":
+        contact_data = _extract_contact_data(query, companies)
+        if isinstance(contact_data, dict) and contact_data.get("error"):
+            return _answer(contact_data["error"])
+        if contact_data:
+            return {"action": "add_contact", "contact_data": contact_data}
+
+    if intent == "add_company":
+        if re.search(r"\b(?:where|who|whose|CEO|VP|president|founder|doing|they do|business|staff size|around|revenue|\d+-\d+|\.|\,)\b", query, re.I) or len(query.split()) > 8:
+            return None
+        name = _extract_company_name_for_add(query)
+        if not name:
+            return _answer("I need the company name before I can add it to CRM. Please say the name directly, for example: Add Bikehackers India to CRM.")
+        company_data = {"name": name}
+        industry_match = re.search(r"\bindustry\s*(?:is|:)?\s*([^,]+)", query, re.I) or re.search(r"\b(?:doing|do|in)\s+([a-zA-Z\s]+?)\s+business\b", query, re.I)
+        if industry_match:
+            company_data["industry"] = _clean_text(industry_match.group(1))
+        size_match = re.search(r"\b(?:with|has)?\s*(\d[\d,]*)\s*(?:staff|employees|people)\b", query, re.I) or re.search(r"\b(?:staff|size|employees|team)\D*(\d+)(?:\s*-\s*(\d+))?", query, re.I)
+        if size_match:
+            if size_match.lastindex and size_match.lastindex >= 2 and size_match.group(2):
+                company_data["size_staff"] = int((int(size_match.group(1).replace(",", "")) + int(size_match.group(2).replace(",", ""))) / 2)
+            else:
+                company_data["size_staff"] = int(size_match.group(1).replace(",", ""))
+        provinces = sorted({c.get("province") for c in companies if c.get("province")})
+        cities = sorted({c.get("city") for c in companies if c.get("city")})
+        _apply_company_location(company_data, query, name, companies)
+        province = _extract_known_value(query, provinces)
+        city = _extract_known_value(query, cities)
+        if province:
+            company_data["province"] = province
+        if city:
+            company_data["city"] = city
+        if stage_value:
+            company_data["stage_id"] = _stage_id_for_name(companies, stage_value) or 1
+        return {"action": "add_company", "company_data": company_data}
+
+    if intent == "edit_company":
+        company = _find_company(query, companies)
+        if not company:
+            return _answer("Please specify the exact company to update. I could not confidently match that company in CRM.")
+        company_data = {}
+        if stage_value and re.search(r"\bstage\b", query, re.I):
+            stage_id = _stage_id_for_name(companies, stage_value)
+            if not stage_id:
+                return _answer(f"I could not match that stage. Valid stages are: {', '.join(stage_names)}.")
+            company_data["stage_id"] = stage_id
+        for field in ("industry", "city", "province", "website", "phone"):
+            match = re.search(rf"\b{field}\s+(?:to|as|is)\s+([^,]+)", query, re.I)
+            if match:
+                company_data[field] = _clean_text(match.group(1))
+        if not company_data:
+            return _answer("Please say what company field to update, for example: Set Apple Computer stage to Contacted.")
+        return {"action": "edit_company", "company_id": company.get("id"), "company_data": company_data}
+
+    if intent == "delete_company":
+        company = _find_company(query, companies)
+        if company:
+            return {"action": "delete_company", "company_id": company.get("id")}
+        if re.search(r"\bcompany\b", query, re.I):
+            return _answer("Please specify the exact company to delete. I could not confidently match it in CRM.")
+
+    if intent == "edit_contact":
+        contact = _find_contact(query, contacts)
+        if not contact:
+            return _answer("Please specify the exact contact to update. I could not confidently match that contact in CRM.")
+        contact_data = {}
+        for field in ("email", "phone", "title", "linkedin"):
+            if field == "linkedin":
+                match = re.search(r"\b(?:linkedin|linkedin\s*url|linkedin\s*id)\s+(?:to|as|is|:)\s+([^\s,]+)", query, re.I)
+            else:
+                match = re.search(rf"\b{field}\s+(?:to|as|is)\s+([^,]+)", query, re.I)
+            if match:
+                contact_data[field] = _clean_text(match.group(1))
+        if not contact_data:
+            return _answer("Please say what contact field to update, for example: Change John Smith email to john@example.com or Update John Smith linkedin to https://linkedin.com/in/john.")
+        return {"action": "edit_contact", "contact_id": contact.get("id"), "contact_data": contact_data}
+
+    if intent == "delete_contact":
+        contact = _find_contact(query, contacts)
+        if contact:
+            return {"action": "delete_contact", "contact_id": contact.get("id")}
+        return _answer("Please specify the exact contact to delete. I could not confidently match it in CRM.")
+
+    return None
+
+@command_bp.route("", methods=["POST"])
+def process_command():
+    data = request.json
+    query = data.get("query", "")
+    context = data.get("context", "")
+    client_time = data.get("client_time")
+    if not client_time:
+        import datetime
+        client_time = datetime.datetime.now().strftime("%a %b %d %Y %H:%M:%S")
+
+    deterministic_route = deterministic_command_route(query, context, client_time)
+    if deterministic_route:
+        action = deterministic_route.get("action")
+        if action in {"add_rep_handler", "edit_rep_handler", "delete_rep_handler"}:
+            if 'user_id' not in session:
+                return jsonify({"action": "answer", "reply": "You must be logged in to manage representatives."})
+            if session.get('user_role') != 'Admin':
+                return jsonify({"action": "answer", "reply": "Unauthorized. Only administrators can manage representatives."})
+
+            tenant_id = session.get('tenant_id')
+            if action == "add_rep_handler":
+                res = db_handle_rep_command("add_rep", deterministic_route, tenant_id)
+                return jsonify(res)
+            elif action == "edit_rep_handler":
+                email_lookup = deterministic_route.get("email_lookup")
+                name_lookup = deterministic_route.get("name_lookup")
+                target_user_id = None
+
+                conn = get_db_connection()
+                cursor = conn.cursor()
+                if email_lookup:
+                    cursor.execute("SELECT id FROM users WHERE LOWER(email) = LOWER(?) AND tenant_id = ?", (email_lookup, tenant_id))
+                    row = cursor.fetchone()
+                    if row: target_user_id = row[0]
+                elif name_lookup:
+                    cursor.execute("SELECT id FROM users WHERE LOWER(name) LIKE LOWER(?) AND tenant_id = ?", (f"%{name_lookup}%", tenant_id))
+                    row = cursor.fetchone()
+                    if row: target_user_id = row[0]
+                conn.close()
+
+                deterministic_route["target_user_id"] = target_user_id
+                res = db_handle_rep_command("edit_rep", deterministic_route, tenant_id)
+                return jsonify(res)
+            elif action == "delete_rep_handler":
+                email_lookup = deterministic_route.get("email_lookup")
+                name_lookup = deterministic_route.get("name_lookup")
+                target_user_id = None
+
+                conn = get_db_connection()
+                cursor = conn.cursor()
+                if email_lookup:
+                    cursor.execute("SELECT id FROM users WHERE LOWER(email) = LOWER(?) AND tenant_id = ?", (email_lookup, tenant_id))
+                    row = cursor.fetchone()
+                    if row: target_user_id = row[0]
+                elif name_lookup:
+                    cursor.execute("SELECT id FROM users WHERE LOWER(name) LIKE LOWER(?) AND tenant_id = ?", (f"%{name_lookup}%", tenant_id))
+                    row = cursor.fetchone()
+                    if row: target_user_id = row[0]
+                conn.close()
+
+                deterministic_route["target_user_id"] = target_user_id
+                res = db_handle_rep_command("delete_rep", deterministic_route, tenant_id)
+                return jsonify(res)
+
+        return jsonify(deterministic_route)
+
+    fallback_tool_route = heuristic_tool_route(query)
+    if fallback_tool_route and fallback_tool_route.get("confidence") == "rule":
+        fallback_tool_route["memory_id"] = save_tool_route(query, fallback_tool_route)
+        return jsonify(fallback_tool_route)
+
+    prompt = f"""
+    You are ProspectIQ's AI Command Bar assistant.
+
+    Current Date/Time: {client_time}
+
+    {context}
+
+    Determine the action to take based on the user's query. Valid actions:
+    - "view_company_profile": User wants to open, view, or show the profile page of a specific existing company. Look through the list of companies in the context. If you find a matching company (e.g. "Tesla" matching "Tesla Inc."), extract its "company_id" (integer) and "company_name" (exact name in database).
+    - "tool_route": User wants to use one of ProspectIQ's tools. Select this before CRM actions when the user is asking to scan, geocode/find nearby companies, or research/extract a company profile.
+      Valid tools:
+      1. "ocr" for Business Card Parser, OCR, business card scanning, card/image/document text extraction. Upload is required, so route to the tool; do not invent extracted data.
+      2. "geo" for Regional Prospecting, Geo Finder, geographic company discovery, nearby/location/company category search, map/coordinate searches.
+      3. "research" for Company Research, Company Extractor, company enrichment, company profile generation, extracting public information about a named company.
+    - "filter_companies": User wants to view, show, find, rank, or list companies already in CRM (including when they ask "list top 3 companies from database" or "top companies in CRM"). Extract any mentioned filters. Valid stages are EXACTLY: "New", "Shortlisted", "Research Done", "Contacted", "Engaged", "Meeting Scheduled", "Meeting Done", "Proposal Sent", "Won", "Paused / Not a Fit". Also extract `view_type` if they specify "table" or "kanban"/"board". If they ask for top/ranked companies from the database, also include `reply` with the formatted markdown list from the context.
+    - "add_company": User wants to add a new company. Carefully extract all descriptive details into "company_data":
+      * "name": Clean, exact short company name ONLY without descriptive clauses (e.g. if prompt says "called Abel music house where the CEO is Abel...", extract only "Abel music house").
+      * "industry": The industry or business type (e.g. if prompt says "they do Music labelling business", extract "Music labelling").
+      * "province" / "city" / "country": Geographic location (e.g. "Ontario" -> province: "Ontario", country: "Canada").
+      * "size_staff": Employee count as integer (e.g. if "around 50-70", use midpoint 60).
+      * "current_supplier_notes": Any leadership summary, meeting notes, background, products, or extra descriptive info mentioned in the query (e.g. if prompt says "We just met with a prospective vendor called NorthStar Dynamics... CEO is Elena, VP is Marcus...", set this to "We just met with a prospective vendor. CEO is Dr. Elena Rostova, VP of Procurement is Marcus Vance (m.vance@northstardynamics.ca, 905-555-0199)"). NEVER leave this empty or "N/A" when any background/notes are provided.
+      * "notes": Also copy the summary or meeting context here so it is logged in the Notes & Activity tab.
+      * "contacts": Array of any decision makers, executives, or contacts mentioned (e.g. if prompt says "CEO is Sarah Connor, VP is Kyle Reese", extract [{{"first_name": "Sarah", "last_name": "Connor", "title": "CEO", "is_primary": true}}, {{"first_name": "Kyle", "last_name": "Reese", "title": "VP", "is_primary": false}}]).
+    - "edit_company": User wants to edit a company. Extract "company_id" and "company_data" to update.
+    - "delete_company": User wants to delete a company. Extract "company_id".
+    - "filter_contacts": User wants to view, show, find, or list contacts.
+    - "add_contact": User wants to add a new contact (EXTERNAL buyer/client person). Extract "contact_data" (first_name, last_name, company_id, email, phone, linkedin).
+    - "edit_contact": User wants to edit a contact (e.g. updating email, phone, title, or linkedin URL/ID). Extract "contact_id" and "contact_data" (e.g. {{"linkedin": "https://linkedin.com/in/..."}}) to update.
+    - "delete_contact": User wants to delete a contact. Extract "contact_id".
+    - "add_task": If the user wants to add, create, or schedule a new task. Extract the "task_title". Also extract "date" (format YYYY-MM-DD), "time" (format HH:MM), and "notes" if the user mentions scheduling or specifies date/time/notes in the query. Unless and until date or time is explicitly mentioned (or if the user says unscheduled or unassigned), set "date" to null and "time" to null so that it stays an unassigned task that does not appear in the calendar.
+    - "edit_task": If the user wants to edit, update, reschedule, or postpone an existing task. Identify the "task_id" from the context.
+    - "complete_task": If the user wants to mark a task as completed, done, or finished. Identify the "task_id".
+    - "delete_task": If the user wants to delete or remove a task. Identify the "task_id".
+    - "add_rep": User wants to add/create/register a new representative (INTERNAL user/team member who logs into ProspectIQ). Extract "rep_data" (name, email, role, password).
+    - "edit_rep": User wants to edit/update a representative's credentials or status (active/inactive). Extract "email" and "rep_data" (name, role, is_active, password).
+    - "delete_rep": User wants to delete/remove a representative. Extract "email".
+    - "answer": For answering general questions, requests for summaries, clarifying ambiguous prompts, asking follow-up questions, suggesting MCQ options, or drafting emails.
+
+    CRITICAL CONVERSATIONAL & AMBIGUITY RULES:
+    1. Be Conversational & Clarifying: If the user's prompt is unclear, ambiguous, or missing required details (e.g. adding a contact without a name or company, or updating a stage without specifying which company), do NOT output a blunt error or make assumptions. Output "answer" asking friendly clarifying follow-up questions so they understand what is needed and can ask the right question.
+    2. Suggest MCQ Options for Ambiguous Requests: Whenever the query is ambiguous between multiple actions or options, suggest a clear Multiple-Choice Question (MCQ) numbered list (e.g., `1) Option A\n2) Option B\n3) Option C`) so the user can pick the option they meant.
+    3. Distinguish Between Contacts and Users/Representatives:
+       - External CRM Contacts (`add_contact` / `edit_contact` / `delete_contact` / `filter_contacts`): People working at client or prospect companies (buyers, managers, executives).
+       - Internal Users/Representatives (`add_rep` / `edit_rep` / `delete_rep`): Internal team members (BD Rep, Viewer, Admin) who log into ProspectIQ.
+       If the user says "add user", "add role", "add rep", or mentions login permissions/roles, this is an INTERNAL representative (`add_rep`), NOT a CRM contact. If it is unclear whether they mean an internal team member or an external CRM contact, ask a conversational follow-up with MCQ options:
+       "Would you like to add an **Internal Team Member (User/Rep)** who logs into ProspectIQ, or an **External CRM Contact** at a client company?\n1) **Internal Team Member** (Requires Name, Email, Role)\n2) **External CRM Contact** (Requires Name, Company, Email/Phone)"
+    4. CRM Database vs. Regional/External Prospecting:
+       - If the user asks to list, show, check, find, or rank companies and explicitly mentions "from database", "in CRM", "saved companies", "my companies", or "top companies in database/CRM", ALWAYS treat it as a CRM database request (`filter_companies` with `reply` synthesizing from the context `companies` list, or `answer`). NEVER output `tool_route` (`geo` or `research`) for requests referring to existing records already in the database/CRM.
+       - Conversely, if the user asks to "find", "search", "discover", or "prospect" companies across a location or industry (e.g., "Find aerospace companies and CNC shops in Mississauga Ontario" or "Find machine shops near Toronto") WITHOUT explicitly saying "in database" or "in CRM", you MUST output `tool_route` with `tool: "geo"` and `tool_input: {{"query": "<query>"}}` to open Regional Prospecting.
+
+    CRITICAL ROUTING RULE: If the query asks to "open", "show", "view", or "go to" the profile, card, info, or page of a company (e.g. "open the profile of Tesla"), check the list of companies in the context.
+    - If the company is already present in the database context (e.g., "Tesla Inc."), you MUST output "view_company_profile" with its "company_id" and "company_name". DO NOT output "tool_route" (research) for existing companies.
+    - If the company is NOT in the database context, and they want to extract/sourcing it, output "tool_route" with "research".
+
+    CRITICAL FILTER RULE: If the query says "show me", "view", or "list" followed by companies already in CRM (e.g. "Aerospace companies in CRM", "contacted companies", "top 3 companies in database"), you MUST output "filter_companies".
+    CRITICAL TOOL RULE: If the query explicitly mentions Business Card Parser, OCR, business card scan, Regional Prospecting, Geo Finder, Company Research, company extractor, nearby/around/within companies, coordinates, or external discovery, output "tool_route".
+    If the user asks a question about the data in the context provided, answer it usefully using the "answer" action.
+
+    Respond ONLY with a STRICTLY VALID JSON object. Do not include markdown formatting or extra text. Include only the fields relevant to the chosen action. Example formats:
+
+    For viewing/opening a company profile:
+    {{"action": "view_company_profile", "company_id": 123, "company_name": "Tesla Inc."}}
+
+    For filtering companies:
+    {{"action": "filter_companies", "filters": {{"industry": "...", "stage": "..."}}, "view_type": "table"}}
+
+    For adding a company:
+    {{"action": "add_company", "company_data": {{"name": "Abel music house", "industry": "Music labelling", "province": "Ontario", "country": "Canada", "size_staff": 60, "current_supplier_notes": "CEO is Abel, VP is Weeknd", "contacts": [{{"first_name": "Abel", "last_name": "-", "title": "CEO", "is_primary": true}}, {{"first_name": "Weeknd", "last_name": "-", "title": "VP", "is_primary": false}}]}}}}
+
+    For editing a company:
+    {{"action": "edit_company", "company_id": 123, "company_data": {{"name": "..."}}}}
+
+    For deleting a company:
+    {{"action": "delete_company", "company_id": 123}}
+
+    For adding a contact:
+    {{"action": "add_contact", "contact_data": {{"first_name": "...", "last_name": "...", "linkedin": "https://linkedin.com/in/..."}}}}
+
+    For editing a contact (e.g. adding or changing linkedin, email, phone):
+    {{"action": "edit_contact", "contact_id": 12, "contact_data": {{"linkedin": "https://linkedin.com/in/..."}}}}
+
+    For adding a task (if unscheduled/unassigned or no date/time given, set date and time to null):
+    {{"action": "add_task", "task_title": "...", "date": null, "time": null, "notes": "..."}}
+
+    For editing/updating/rescheduling a task:
+    {{"action": "edit_task", "task_id": 12345, "task_title": "...", "date": "YYYY-MM-DD", "time": "HH:MM", "notes": "..."}}
+    (Note: only include the fields that need to be changed/updated)
+
+    For completing a task:
+    {{"action": "complete_task", "task_id": 12345}}
+
+    For deleting a task:
+    {{"action": "delete_task", "task_id": 12345}}
+
+    For tool routing:
+    {{"action": "tool_route", "tool": "geo", "tool_input": {{"query": "CNC machining companies near Windsor Ontario"}}, "auto_start": true, "message": "Opening Regional Prospecting and starting the search."}}
+    {{"action": "tool_route", "tool": "research", "tool_input": {{"company": "Prestige Constructions India"}}, "auto_start": true, "message": "Opening Company Research and starting the research."}}
+    {{"action": "tool_route", "tool": "ocr", "tool_input": {{"query": "business card scan"}}, "auto_start": false, "message": "Opening Business Card Parser. Upload a business card image to begin."}}
+
+    For answering:
+    {{"action": "answer", "reply": "..."}}
+    """
+
+    # Format and include chat history if provided
+    history = data.get("history", [])
+    formatted_messages = [{"role": "system", "content": prompt}]
+    for msg in history:
+        r = msg.get("role")
+        c = msg.get("content", "")
+        if r == "bot":
+            role_name = "assistant"
+            # Format assistant response as JSON to keep LLM aligned with JSON constraints
+            try:
+                json.loads(c)
+                content_str = c
+            except Exception:
+                content_str = json.dumps({"action": "answer", "reply": c})
+            formatted_messages.append({"role": role_name, "content": content_str})
+        elif r == "user":
+            formatted_messages.append({"role": "user", "content": c})
+
+    formatted_messages.append({"role": "user", "content": query})
+
+    # Collect available API keys
+    gemini_keys = [
+        os.environ.get("GEMINI_API_KEY_prime_1"),
+        os.environ.get("GEMINI_API_KEY_prime_2"),
+        os.environ.get("GEMINI_API_KEY_prime_3"),
+    ]
+    gemini_keys = [k for k in gemini_keys if k]
+
+    content = None
+    errors = []
+
+    # 1. Try Gemini natively via interactions streaming
+    if not content:
+        for k in gemini_keys:
+            if content:
+                break
+            try:
+                from google import genai
+                client = genai.Client(api_key=k)
+
+                # Convert structured messages to a string for the interactions input
+                prompt_str = ""
+                for m in formatted_messages:
+                    prompt_str += m["role"].upper() + ":\n" + m["content"] + "\n\n"
+
+                stream = client.interactions.create(
+                    model="gemini-2.5-flash",
+                    input=prompt_str.strip(),
+                    stream=True
+                )
+
+                gemini_content = ""
+                for event in stream:
+                    if getattr(event, "event_type", "") == "step.delta":
+                        if hasattr(event.delta, "text"):
+                            gemini_content += event.delta.text
+
+                if gemini_content:
+                    content = gemini_content
+            except Exception as e:
+                errors.append(f"Gemini streaming exception: {str(e)}")
+
+    # 2. Try Claude API with streaming fallback
+    if not content:
+        try:
+            claude_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+            if claude_key:
+                import anthropic
+                client = anthropic.Anthropic(api_key=claude_key)
+
+                system_msg = ""
+                anthropic_messages = []
+                for msg in formatted_messages:
+                    if msg.get("role") == "system":
+                        system_msg = msg.get("content")
+                    else:
+                        anthropic_messages.append(msg)
+
+                kwargs = {
+                    "model": "claude-haiku-4-5",
+                    "max_tokens": 4096,
+                    "messages": anthropic_messages
+                }
+                if system_msg:
+                    kwargs["system"] = system_msg
+
+                claude_content = ""
+                max_continuations = 5
+                continuation_count = 0
+
+                while True:
+                    with client.messages.stream(**kwargs) as stream:
+                        for text in stream.text_stream:
+                            claude_content += text
+
+                        final_msg = stream.get_final_message()
+                        stop_reason = final_msg.stop_reason
+
+                        if stop_reason == "end_turn":
+                            break
+                        elif stop_reason == "max_tokens":
+                            continuation_count += 1
+                            if continuation_count >= max_continuations:
+                                break
+
+                            kwargs["messages"].append({"role": "assistant", "content": final_msg.content})
+                            kwargs["messages"].append({
+                                "role": "user",
+                                "content": "Your previous response was cut off. Please continue exactly from where you left off. Do not include markdown or explanations, just the JSON."
+                            })
+                        elif stop_reason == "refusal":
+                            break
+                        else:
+                            break
+
+                if claude_content:
+                    content = claude_content
+            else:
+                errors.append("Claude API key not configured")
+        except Exception as e:
+            errors.append(f"Claude exception: {str(e)}")
+
+    if not content:
+        if fallback_tool_route:
+            fallback_tool_route["memory_id"] = save_tool_route(query, fallback_tool_route)
+            return jsonify(fallback_tool_route)
+        err_msg = " | ".join(errors[-3:])
+        return jsonify({"error": f"All AI providers failed: {err_msg}", "reply": "I encountered an error connecting to my AI providers."}), 500
+
+    try:
+        content = content.replace("```json", "").replace("```", "").strip()
+        parsed = json.loads(content)
+
+        if parsed.get("action") in {"add_rep", "edit_rep", "delete_rep"}:
+            if 'user_id' not in session:
+                return jsonify({"action": "answer", "reply": "You must be logged in to manage representatives."})
+            if session.get('user_role') != 'Admin':
+                return jsonify({"action": "answer", "reply": "Unauthorized. Only administrators can manage representatives."})
+
+            tenant_id = session.get('tenant_id')
+            if parsed.get("action") == "add_rep":
+                rep_data = parsed.get("rep_data", {})
+                res = db_handle_rep_command("add_rep", rep_data, tenant_id)
+                return jsonify(res)
+            elif parsed.get("action") == "edit_rep":
+                email_lookup = parsed.get("email")
+                rep_data = parsed.get("rep_data", {})
+
+                target_user_id = None
+                conn = get_db_connection()
+                cursor = conn.cursor()
+                if email_lookup:
+                    cursor.execute("SELECT id FROM users WHERE LOWER(email) = LOWER(?) AND tenant_id = ?", (email_lookup, tenant_id))
+                else:
+                    name_lookup = rep_data.get("name")
+                    if name_lookup:
+                        cursor.execute("SELECT id FROM users WHERE LOWER(name) LIKE LOWER(?) AND tenant_id = ?", (f"%{name_lookup}%", tenant_id))
+                row = cursor.fetchone()
+                if row: target_user_id = row[0]
+                conn.close()
+
+                query_data = {"target_user_id": target_user_id, "rep_data": rep_data}
+                res = db_handle_rep_command("edit_rep", query_data, tenant_id)
+                return jsonify(res)
+            elif parsed.get("action") == "delete_rep":
+                email_lookup = parsed.get("email")
+
+                target_user_id = None
+                conn = get_db_connection()
+                cursor = conn.cursor()
+                if email_lookup:
+                    cursor.execute("SELECT id FROM users WHERE LOWER(email) = LOWER(?) AND tenant_id = ?", (email_lookup, tenant_id))
+                row = cursor.fetchone()
+                if row: target_user_id = row[0]
+                conn.close()
+
+                query_data = {"target_user_id": target_user_id}
+                res = db_handle_rep_command("delete_rep", query_data, tenant_id)
+                return jsonify(res)
+
+        if parsed.get("action") == "tool_route":
+            routed = normalize_tool_route(parsed, query)
+            if fallback_tool_route and fallback_tool_route.get("confidence") == "rule":
+                routed = fallback_tool_route
+            routed["memory_id"] = save_tool_route(query, routed)
+            return jsonify(routed)
+        return jsonify(parsed)
+    except Exception as e:
+        if fallback_tool_route:
+            fallback_tool_route["memory_id"] = save_tool_route(query, fallback_tool_route)
+            return jsonify(fallback_tool_route)
+        return jsonify({"error": str(e), "reply": "I had trouble parsing the response from my AI service."}), 500
+
+@command_bp.route("/memory", methods=["GET"])
+def command_memory():
+    limit = clean_int(request.args.get("limit"), 20, 1, 80)
+    # Use efficient DB-level filtering by kind instead of fetching all and filtering in Python
+    items = db_list_interactions_by_kinds(["tool_route", "ocr", "geo", "research"], limit)
+    memory = []
+    for item in items:
+        memory.append({
+            "id": item.get("id"),
+            "kind": item.get("kind"),
+            "title": item.get("title"),
+            "status": item.get("status"),
+            "created_at": item.get("created_at"),
+            "input": {
+                "query": item.get("input", {}).get("query"),
+                "filename": item.get("input", {}).get("filename"),
+                "selected_tool": item.get("input", {}).get("selected_tool"),
+                "route": item.get("input", {}).get("route"),
+                "tool_input": item.get("input", {}).get("tool_input") or {},
+            },
+            "result": {
+                "selected_tool": item.get("result", {}).get("selected_tool"),
+                "tool_label": item.get("result", {}).get("tool_label"),
+                "route": item.get("result", {}).get("route"),
+                "message": item.get("result", {}).get("message"),
+            },
+        })
+    return jsonify(memory)

routes/companies.py

@@ -0,0 +1,942 @@
+import re
+from flask import Blueprint, jsonify, request
+from db import get_db_connection, dict_from_row, get_request_user, get_user_access_level, is_supabase_active, sync_postgres_sequence, get_request_tenant_id
+
+companies_bp = Blueprint('companies', __name__)
+
+def insert_and_get_id(cursor, sql, params):
+    cursor.execute(sql, params)
+    return cursor.lastrowid
+
+def safe_int(value, default):
+    if value is None or value == "":
+        return default
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+def log_stage_change(cursor, company_id, to_stage_id, user_id, source="manual", from_stage_id=None):
+    if is_supabase_active():
+        sync_postgres_sequence("stage_changes")
+    if from_stage_id is None:
+        cursor.execute("""
+            INSERT INTO stage_changes (company_id, to_stage_id, changed_by_user_id, source)
+            VALUES (?, ?, ?, ?)
+        """, (company_id, to_stage_id, user_id, source))
+    else:
+        cursor.execute("""
+            INSERT INTO stage_changes (company_id, from_stage_id, to_stage_id, changed_by_user_id, source)
+            VALUES (?, ?, ?, ?, ?)
+        """, (company_id, from_stage_id, to_stage_id, user_id, source))
+
+def extract_int(val, default=0):
+    if val is None:
+        return default
+    if isinstance(val, int):
+        return val
+    s = re.sub(r'[^\d]', '', str(val))
+    return int(s) if s else default
+
+def extract_float(val, default=0.0):
+    if val is None:
+        return default
+    if isinstance(val, (int, float)):
+        return float(val)
+    match = re.search(r'\d+(\.\d+)?', str(val))
+    return float(match.group()) if match else default
+
+def clean_profile_value(value):
+    value = re.sub(r"\s+", " ", str(value or "")).strip()
+    value = re.sub(r"^\s*[-*+]\s*", "", value).strip()
+    value = value.replace("**", "").replace("__", "").replace("`", "").strip()
+    if value.lower() in {"not publicly available", "not available", "n/a", "none"}:
+        return ""
+    return value
+
+def clean_profile_heading(value):
+    value = re.sub(r"^\s*#{1,6}\s*", "", str(value or "").strip())
+    return clean_profile_value(value.rstrip(":"))
+
+def split_profile_sections(text):
+    sections = {}
+    current = "Profile"
+    lines = []
+    for raw_line in str(text or "").splitlines():
+        line = raw_line.strip()
+        heading = clean_profile_heading(line)
+        is_heading = bool(
+            line
+            and len(heading) < 90
+            and (
+                line.startswith("#")
+                or re.match(r"^\*\*[^*]+:\*\*\s*$", line)
+                or (not line.startswith((" ", "\t", "-", "*", "+")) and not line.endswith(":"))
+            )
+        )
+        if is_heading:
+            if lines:
+                sections[current] = "\n".join(lines).strip()
+            current = heading
+            lines = []
+        else:
+            lines.append(raw_line)
+    if lines:
+        sections[current] = "\n".join(lines).strip()
+    return sections
+
+def labeled_line_pattern(label):
+    return re.compile(
+        rf"^\s*(?:[-*+]\s*)?(?:\*\*)?\s*{re.escape(label)}\s*(?:\*\*)?\s*:\s*(.*?)\s*$",
+        re.I,
+    )
+
+def looks_like_labeled_line(line):
+    return bool(re.match(r"^\s*(?:[-*+]\s*)?(?:\*\*)?\s*[A-Za-z][A-Za-z0-9 /&().'-]{1,80}\s*(?:\*\*)?\s*:", line))
+
+def extract_labeled_value(text, label):
+    pattern = labeled_line_pattern(label)
+    for line in str(text or "").splitlines():
+        match = pattern.match(line)
+        if match:
+            return clean_profile_value(match.group(1))
+    return ""
+
+def extract_multiline_labeled_value(text, label):
+    pattern = labeled_line_pattern(label)
+    collecting = False
+    values = []
+    for line in str(text or "").splitlines():
+        if not collecting:
+            match = pattern.match(line)
+            if match:
+                collecting = True
+                values.append(match.group(1))
+            continue
+        stripped = line.strip()
+        if stripped.startswith("#") or looks_like_labeled_line(line):
+            break
+        values.append(line)
+    return clean_profile_value("\n".join(values).strip(" \n\t:-"))
+
+def infer_company_name(text):
+    for line in str(text or "").splitlines():
+        cleaned = clean_profile_heading(line)
+        match = re.match(r"Company Research\s*:\s*(.+)$", cleaned, re.I)
+        if match:
+            return clean_profile_value(match.group(1))
+        match = re.match(r"(.+?)\s*:\s*Company Profile\b", cleaned, re.I)
+        if match:
+            return clean_profile_value(match.group(1))
+    return ""
+
+def parse_employee_count(value):
+    match = re.search(r"\d[\d,]*", str(value or ""))
+    return int(match.group(0).replace(",", "")) if match else 0
+
+def normalize_website(value):
+    value = clean_profile_value(value)
+    if value and not re.match(r"^https?://", value, re.I):
+        return "https://" + value
+    return value
+
+def parse_address(value):
+    value = clean_profile_value(value)
+    if not value:
+        return {"street": "", "city": "", "province": "", "postal_code": "", "country": ""}
+    parenthetical = re.search(r"\((.*?)\)", value)
+    address = parenthetical.group(1) if parenthetical else value
+    parts = [part.strip() for part in address.split(",") if part.strip()]
+    country = parts[-1] if parts else ""
+    province = parts[-2] if len(parts) >= 2 else ""
+    city = parts[-3] if len(parts) >= 3 else (parts[0] if parts else "")
+    street = ", ".join(parts[:-3]) if len(parts) > 3 else ""
+    postal_match = re.search(r"\b\d{5,6}\b", address)
+    return {
+        "street": street,
+        "city": city,
+        "province": province,
+        "postal_code": postal_match.group(0) if postal_match else "",
+        "country": country,
+    }
+
+def split_name(name):
+    parts = clean_profile_value(name).split()
+    if not parts:
+        return "", ""
+    if len(parts) == 1:
+        return parts[0], "-"
+    return " ".join(parts[:-1]), parts[-1]
+
+def parse_decision_makers(text):
+    contacts = []
+    primary_name = extract_labeled_value(text, "Primary Contact")
+    person_blocks = re.split(r"^\s*(?:\*\*)?\s*Person\s+\d+\s*:\s*(?:\*\*)?\s*$", str(text or ""), flags=re.I | re.M)
+    for block in person_blocks[1:]:
+        name = extract_labeled_value(block, "Name")
+        if not name:
+            continue
+        first_name, last_name = split_name(name)
+        contacts.append({
+            "first_name": first_name,
+            "last_name": last_name,
+            "title": extract_labeled_value(block, "Title"),
+            "email": extract_labeled_value(block, "Email (if available)") or extract_labeled_value(block, "Email"),
+            "phone": extract_labeled_value(block, "Phone (if available)") or extract_labeled_value(block, "Phone"),
+            "linkedin": extract_labeled_value(block, "LinkedIn URL"),
+            "is_primary": clean_profile_value(name).lower() == clean_profile_value(primary_name).lower(),
+        })
+    if contacts and not any(contact["is_primary"] for contact in contacts):
+        contacts[0]["is_primary"] = True
+    return contacts
+
+def extract_contacts_from_descriptive_notes(text):
+    if not text:
+        return []
+    contacts = []
+    matches = re.findall(
+        r"\b(CEO|VP|Vice\s+President|President|Founder|Director|Manager|COO|CFO|CTO|Head\s+of\s+[A-Za-z]+)\b\s*(?:is|are|:|of\s+[A-Za-z]+\s+is)?\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)",
+        str(text),
+        re.I,
+    )
+    for title, full_name in matches:
+        fn, ln = split_name(full_name.strip())
+        if fn or ln:
+            clean_t = title.strip().upper() if len(title.strip()) <= 3 else title.strip().title()
+            if not any(c["first_name"] == fn and c["last_name"] == ln for c in contacts):
+                contacts.append({
+                    "first_name": fn,
+                    "last_name": ln or "-",
+                    "title": clean_t,
+                    "is_primary": len(contacts) == 0 or clean_t in ("CEO", "PRESIDENT", "FOUNDER")
+                })
+    matches2 = re.findall(
+        r"\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\s*\(\s*(CEO|VP|Vice\s+President|President|Founder|Director|Manager|COO|CFO|CTO)\s*\)",
+        str(text),
+        re.I,
+    )
+    for full_name, title in matches2:
+        fn, ln = split_name(full_name.strip())
+        if fn or ln:
+            clean_t = title.strip().upper() if len(title.strip()) <= 3 else title.strip().title()
+            if not any(c["first_name"] == fn and c["last_name"] == ln for c in contacts):
+                contacts.append({
+                    "first_name": fn,
+                    "last_name": ln or "-",
+                    "title": clean_t,
+                    "is_primary": len(contacts) == 0 or clean_t in ("CEO", "PRESIDENT", "FOUNDER")
+                })
+    if contacts and not any(c.get("is_primary") for c in contacts):
+        contacts[0]["is_primary"] = True
+    return contacts
+
+def build_company_from_extractor(text):
+    basics = split_profile_sections(text).get("Company Basics", text)
+    address = parse_address(extract_labeled_value(basics, "Headquarters"))
+    company_name = (
+        extract_labeled_value(basics, "Company Name")
+        or extract_labeled_value(text, "Company Name")
+        or infer_company_name(text)
+    )
+    return {
+        "name": company_name,
+        "legal_name": company_name,
+        "website": normalize_website(extract_labeled_value(basics, "Website")),
+        "phone": extract_labeled_value(basics, "Phone"),
+        "industry": extract_labeled_value(basics, "Industry"),
+        "street": address["street"],
+        "city": address["city"],
+        "province": address["province"],
+        "postal_code": address["postal_code"],
+        "country": address["country"] or "India",
+        "size_staff": parse_employee_count(extract_labeled_value(basics, "Employee Count")),
+        "revenue_band": extract_labeled_value(basics, "Revenue Estimate") or "<1M",
+        "business_type": "other",
+        "products_made": extract_multiline_labeled_value(basics, "Products / Services"),
+        "parts_sourced": extract_labeled_value(basics, "Customer Segments"),
+        "current_supplier_notes": "\n\n".join(
+            part for part in [
+                extract_labeled_value(basics, "Business Description"),
+                extract_multiline_labeled_value(text, "Primary Contact Reason"),
+                extract_multiline_labeled_value(text, "Secondary Contact Reason"),
+            ] if part
+        ),
+        "maplempss_fit_score": 0.0,
+    }
+
+def ensure_extractor_stage(cursor):
+    stage_name = "From Company Extractor"
+    cursor.execute("SELECT id FROM stages WHERE lower(name) = lower(?)", (stage_name,))
+    row = cursor.fetchone()
+    if row:
+        return row[0]
+    cursor.execute("SELECT COALESCE(MAX(order_index), 0) + 1 FROM stages")
+    order_index = cursor.fetchone()[0]
+    return insert_and_get_id(
+        cursor,
+        "INSERT INTO stages (name, order_index, color_bg, color_text) VALUES (?, ?, ?, ?)",
+        (stage_name, order_index, "#f8f9fa", "#000000"),
+    )
+
+def store_extractor_ai_fields(cursor, company_id, text):
+    sections = split_profile_sections(text)
+    for section, body in sections.items():
+        if not body.strip():
+            continue
+        cursor.execute("""
+            INSERT INTO ai_field_values (company_id, field_name, value, source_url, confidence_score)
+            VALUES (?, ?, ?, ?, ?)
+        """, (company_id, f"Company Extractor: {section}", body[:12000], "company-extractor", 0.85))
+
+def get_stage_id_by_name(cursor, stage_name):
+    cursor.execute("SELECT id FROM stages WHERE lower(name) = lower(?)", (stage_name,))
+    row = cursor.fetchone()
+    return row[0] if row else None
+
+def phone_from_ocr(value):
+    if isinstance(value, dict):
+        return clean_profile_value(value.get("office") or value.get("mobile") or value.get("phone") or "")
+    return clean_profile_value(value)
+
+def has_meaningful_ocr_company_data(company_data, address):
+    values = [
+        company_data.get("company_name"),
+        company_data.get("website"),
+        address.get("full_address"),
+        address.get("street"),
+        address.get("city"),
+        address.get("state_province") or address.get("state"),
+        address.get("postal_code"),
+        address.get("country"),
+    ]
+    return any(clean_profile_value(value) for value in values)
+
+def add_primary_contact_from_ocr(cursor, company_id, person):
+    first_name = clean_profile_value(person.get("first_name"))
+    last_name = clean_profile_value(person.get("last_name"))
+    if not first_name and not last_name:
+        return None
+    if not last_name:
+        last_name = "-"
+    social = person.get("social") if isinstance(person.get("social"), dict) else {}
+    cursor.execute("UPDATE contacts SET is_primary = 0 WHERE company_id = ?", (company_id,))
+    return insert_and_get_id(cursor, """
+        INSERT INTO contacts (
+            company_id, first_name, last_name, title, email, phone, linkedin, is_primary
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, 1)
+    """, (
+        company_id,
+        first_name,
+        last_name,
+        clean_profile_value(person.get("job_title")),
+        clean_profile_value(person.get("email")),
+        phone_from_ocr(person.get("phone")),
+        clean_profile_value(social.get("linkedin")),
+    ))
+
+@companies_bp.route("", methods=["GET"])
+def get_companies():
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    if role in ('Super Admin', 'Admin', 'Viewer'):
+        cursor.execute("""
+            SELECT c.*, s.name as stage_name, s.color_bg as stage_color_bg, s.color_text as stage_color_text, u.name as rep_name
+            FROM companies c
+            JOIN stages s ON c.stage_id = s.id
+            LEFT JOIN users u ON c.assigned_rep_id = u.id
+            ORDER BY c.maplempss_fit_score DESC, c.name ASC
+        """)
+    else:
+        cursor.execute("""
+            SELECT
+                c.id, c.tenant_id, c.name, c.legal_name, c.industry, c.street, c.city, c.province, c.postal_code, c.country,
+                c.business_type, c.stage_id, c.assigned_rep_id, c.created_by, c.updated_by, c.import_batch_id, c.created_at, c.updated_at,
+                s.name as stage_name, s.color_bg as stage_color_bg, s.color_text as stage_color_text, u.name as rep_name,
+                CASE WHEN c.assigned_rep_id = ? THEN c.website ELSE '[Restricted]' END as website,
+                CASE WHEN c.assigned_rep_id = ? THEN c.phone ELSE '[Restricted]' END as phone,
+                CASE WHEN c.assigned_rep_id = ? THEN c.size_staff ELSE NULL END as size_staff,
+                CASE WHEN c.assigned_rep_id = ? THEN c.revenue_band ELSE '[Restricted]' END as revenue_band,
+                CASE WHEN c.assigned_rep_id = ? THEN c.products_made ELSE '[Restricted]' END as products_made,
+                CASE WHEN c.assigned_rep_id = ? THEN c.parts_sourced ELSE '[Restricted]' END as parts_sourced,
+                CASE WHEN c.assigned_rep_id = ? THEN c.current_supplier_notes ELSE '[Restricted]' END as current_supplier_notes,
+                CASE WHEN c.assigned_rep_id = ? THEN c.maplempss_fit_score ELSE NULL END as maplempss_fit_score
+            FROM companies c
+            JOIN stages s ON c.stage_id = s.id
+            LEFT JOIN users u ON c.assigned_rep_id = u.id
+            ORDER BY c.maplempss_fit_score DESC, c.name ASC
+        """, (user_id, user_id, user_id, user_id, user_id, user_id, user_id, user_id))
+    rows = cursor.fetchall()
+    companies = [dict_from_row(row) for row in rows]
+    conn.close()
+    return jsonify(companies)
+
+@companies_bp.route("", methods=["POST"])
+def add_company():
+    data = request.json
+    if not data or not data.get("name"):
+        return jsonify({"error": "Company name is required"}), 400
+
+    user_id, role, _ = get_request_user()
+    tenant_id = get_request_tenant_id() or 1
+    if role == 'Viewer':
+        return jsonify({"error": "Viewers are not authorized to create companies."}), 403
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        assigned_rep = int(data.get("assigned_rep_id", user_id)) if data.get("assigned_rep_id") else user_id
+        notes_text = clean_profile_value(data.get("current_supplier_notes", ""))
+        if not notes_text or notes_text == "N/A":
+            notes_text = clean_profile_value(data.get("notes", ""))
+        contacts_list = data.get("contacts", []) if isinstance(data.get("contacts"), list) else []
+        if (not notes_text or notes_text == "N/A") and contacts_list:
+            contact_strs = []
+            for c in contacts_list:
+                if isinstance(c, dict) and (c.get("first_name") or c.get("last_name") or c.get("title")):
+                    contact_strs.append(f"{c.get('title', 'Contact')} is {clean_profile_value(c.get('first_name', ''))} {clean_profile_value(c.get('last_name', ''))}".strip())
+            if contact_strs:
+                notes_text = "Leadership / Contacts: " + ", ".join(contact_strs)
+        if not notes_text or notes_text == "N/A":
+            notes_text = ""
+
+        company_id = insert_and_get_id(cursor, """
+            INSERT INTO companies (
+                tenant_id, name, legal_name, website, phone, nic_code, industry,
+                street, city, province, postal_code, country, size_staff, revenue_band,
+                business_type, products_made, parts_sourced, current_supplier_notes,
+                maplempss_fit_score, stage_id, assigned_rep_id
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            tenant_id,
+            data.get("name"),
+            data.get("legal_name", data.get("name")),
+            data.get("website", ""),
+            data.get("phone", ""),
+            data.get("nic_code", ""),
+            data.get("industry", ""),
+            data.get("street", ""),
+            data.get("city", ""),
+            data.get("province", ""),
+            data.get("postal_code", ""),
+            data.get("country", "Canada"),
+            extract_int(data.get("size_staff"), 0),
+            data.get("revenue_band", "<1M"),
+            data.get("business_type", "OEM"),
+            data.get("products_made", ""),
+            data.get("parts_sourced", ""),
+            notes_text,
+            extract_float(data.get("maplempss_fit_score"), 0.0),
+            safe_int(data.get("stage_id"), 1),
+            assigned_rep
+        ))
+        conn.commit()
+
+        log_stage_change(cursor, company_id, safe_int(data.get("stage_id"), 1), user_id, "manual")
+
+        contacts_to_add = data.get("contacts", []) if isinstance(data.get("contacts"), list) else []
+        if not contacts_to_add and data.get("current_supplier_notes"):
+            contacts_to_add = extract_contacts_from_descriptive_notes(data.get("current_supplier_notes"))
+        if not contacts_to_add and data.get("notes"):
+            contacts_to_add = extract_contacts_from_descriptive_notes(data.get("notes"))
+
+        for idx_c, contact in enumerate(contacts_to_add):
+            if isinstance(contact, dict) and (contact.get("first_name") or contact.get("last_name") or contact.get("name")):
+                fn = clean_profile_value(contact.get("first_name"))
+                ln = clean_profile_value(contact.get("last_name"))
+                if not fn and not ln:
+                    fn, ln = split_name(clean_profile_value(contact.get("name")))
+                if not ln:
+                    ln = "-"
+                is_prim = 1 if (contact.get("is_primary") or idx_c == 0) else 0
+                if is_prim == 1 and idx_c > 0:
+                    cursor.execute("UPDATE contacts SET is_primary = 0 WHERE company_id = ?", (company_id,))
+                cursor.execute("""
+                    INSERT INTO contacts (
+                        company_id, first_name, last_name, title, email, phone, linkedin, is_primary
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """, (
+                    company_id, fn, ln,
+                    clean_profile_value(contact.get("title", "")),
+                    clean_profile_value(contact.get("email", "")),
+                    clean_profile_value(contact.get("phone", "")),
+                    clean_profile_value(contact.get("linkedin", "")),
+                    is_prim
+                ))
+
+        if notes_text and notes_text != "N/A":
+            cursor.execute("""
+                INSERT INTO activities (company_id, user_id, type, outcome, notes, next_action, next_action_date)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            """, (company_id, user_id, "Note", "Logged during onboarding", notes_text, "", None))
+            cursor.execute("""
+                INSERT INTO notes (company_id, user_id, body, is_pinned)
+                VALUES (?, ?, ?, ?)
+            """, (company_id, user_id, notes_text, 0))
+
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True, "id": company_id})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@companies_bp.route("/from-extractor", methods=["POST"])
+def add_company_from_extractor():
+    user_id, role, _ = get_request_user()
+    tenant_id = get_request_tenant_id() or 1
+    if role == 'Viewer':
+        return jsonify({"error": "Viewers are not authorized to import profiles."}), 403
+
+    data = request.json or {}
+    profile_text = str(data.get("profile_text") or "").strip()
+    profile_path = str(data.get("profile_path") or "").strip()
+    if not profile_text:
+        return jsonify({"error": "Company Research profile text is required"}), 400
+
+    company = build_company_from_extractor(profile_text)
+    if not company.get("name"):
+        return jsonify({"error": "Could not find a company name in the extractor profile"}), 400
+
+    contacts = parse_decision_makers(profile_text)
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        stage_id = ensure_extractor_stage(cursor)
+        company_id = insert_and_get_id(cursor, """
+            INSERT INTO companies (
+                tenant_id, name, legal_name, website, phone, nic_code, industry,
+                street, city, province, postal_code, country, size_staff, revenue_band,
+                business_type, products_made, parts_sourced, current_supplier_notes,
+                maplempss_fit_score, stage_id, assigned_rep_id, created_by, updated_by
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            tenant_id,
+            company.get("name"),
+            company.get("legal_name") or company.get("name"),
+            company.get("website", ""),
+            company.get("phone", ""),
+            "",
+            company.get("industry", ""),
+            company.get("street", ""),
+            company.get("city", ""),
+            company.get("province", ""),
+            company.get("postal_code", ""),
+            company.get("country", "India"),
+            extract_int(company.get("size_staff"), 0),
+            company.get("revenue_band", "<1M"),
+            company.get("business_type", "other"),
+            company.get("products_made", ""),
+            company.get("parts_sourced", ""),
+            company.get("current_supplier_notes", ""),
+            extract_float(company.get("maplempss_fit_score"), 0.0),
+            stage_id,
+            user_id,
+            user_id,
+            user_id,
+        ))
+        log_stage_change(cursor, company_id, stage_id, user_id, "ai_confirmed")
+
+        for contact in contacts:
+            if contact.get("is_primary"):
+                cursor.execute("UPDATE contacts SET is_primary = 0 WHERE company_id = ?", (company_id,))
+            cursor.execute("""
+                INSERT INTO contacts (
+                    company_id, first_name, last_name, title, email, phone, linkedin, is_primary
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                company_id,
+                contact["first_name"],
+                contact["last_name"],
+                contact.get("title", ""),
+                contact.get("email", ""),
+                contact.get("phone", ""),
+                contact.get("linkedin", ""),
+                1 if contact.get("is_primary") else 0,
+            ))
+
+        note_body = "Imported from Company Extractor."
+        if profile_path:
+            note_body += f"\nSource profile: {profile_path}"
+        note_body += "\n\n" + profile_text[:12000]
+        cursor.execute("""
+            INSERT INTO notes (company_id, user_id, body, is_pinned)
+            VALUES (?, ?, ?, 1)
+        """, (company_id, user_id, note_body))
+        store_extractor_ai_fields(cursor, company_id, profile_text)
+        conn.commit()
+        conn.close()
+        return jsonify({
+            "success": True,
+            "company_id": company_id,
+            "contacts_added": len(contacts),
+            "stage": "From Company Extractor",
+        })
+    except Exception as e:
+        conn.rollback()
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@companies_bp.route("/from-ocr", methods=["POST"])
+def add_company_from_ocr():
+    user_id, role, _ = get_request_user()
+    tenant_id = get_request_tenant_id() or 1
+    if role == 'Viewer':
+        return jsonify({"error": "Viewers are not authorized to import Business Card Parser cards."}), 403
+
+    data = request.json or {}
+    card = data.get("card") if isinstance(data.get("card"), dict) else {}
+    company_data = card.get("company") if isinstance(card.get("company"), dict) else {}
+    person = card.get("person") if isinstance(card.get("person"), dict) else {}
+    address = company_data.get("address") if isinstance(company_data.get("address"), dict) else {}
+
+    if not has_meaningful_ocr_company_data(company_data, address):
+        return jsonify({
+            "error": "Business Card Parser did not find enough company information to add this to CRM. Please enter at least a Company Name, Website, or Location before adding."
+        }), 400
+
+    company_name = clean_profile_value(company_data.get("company_name"))
+    if not company_name:
+        full_name = " ".join(part for part in [
+            clean_profile_value(person.get("first_name")),
+            clean_profile_value(person.get("last_name")),
+        ] if part)
+        company_name = full_name or clean_profile_value(data.get("title")) or "Business Card Imported Company"
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        stage_id = get_stage_id_by_name(cursor, "New") or 1
+        company_id = insert_and_get_id(cursor, """
+            INSERT INTO companies (
+                tenant_id, name, legal_name, website, phone, nic_code, industry,
+                street, city, province, postal_code, country, size_staff, revenue_band,
+                business_type, products_made, parts_sourced, current_supplier_notes,
+                maplempss_fit_score, stage_id, assigned_rep_id, created_by, updated_by
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            tenant_id,
+            company_name,
+            company_name,
+            normalize_website(company_data.get("website")),
+            phone_from_ocr(person.get("phone")),
+            "",
+            "",
+            clean_profile_value(address.get("street")),
+            clean_profile_value(address.get("city")),
+            clean_profile_value(address.get("state_province") or address.get("state")),
+            clean_profile_value(address.get("postal_code")),
+            clean_profile_value(address.get("country")) or "USA",
+            0,
+            "<1M",
+            "other",
+            "",
+            "",
+            "Imported from Business Card Parser.\n\n" + clean_profile_value(address.get("full_address")),
+            extract_float(card.get("metadata", {}).get("confidence_score") if isinstance(card.get("metadata"), dict) else 0.0),
+            stage_id,
+            user_id,
+            user_id,
+            user_id,
+        ))
+        log_stage_change(cursor, company_id, stage_id, user_id, "ai_confirmed")
+
+        contact_id = add_primary_contact_from_ocr(cursor, company_id, person)
+        cursor.execute("""
+            INSERT INTO notes (company_id, user_id, body, is_pinned)
+            VALUES (?, ?, ?, 1)
+        """, (company_id, user_id, "Imported from Business Card Parser.\n\n" + str(card)[:12000]))
+        conn.commit()
+        conn.close()
+        return jsonify({
+            "success": True,
+            "company_id": company_id,
+            "contact_id": contact_id,
+            "stage": "New",
+        })
+    except Exception as e:
+        conn.rollback()
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@companies_bp.route("/<int:company_id>", methods=["GET"])
+def get_company_details(company_id):
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    level = get_user_access_level(conn, user_id, role, company_id)
+
+    if level == 'none':
+        conn.close()
+        return jsonify({"error": "Company not found"}), 404
+
+    cursor = conn.cursor()
+    cursor.execute("""
+        SELECT c.*, s.name as stage_name, s.color_bg as stage_color_bg, s.color_text as stage_color_text
+        FROM companies c
+        JOIN stages s ON c.stage_id = s.id
+        WHERE c.id = ?
+    """, (company_id,))
+    comp_row = cursor.fetchone()
+    if not comp_row:
+        conn.close()
+        return jsonify({"error": "Company not found"}), 404
+    company = dict_from_row(comp_row)
+
+    if level == 'basic':
+        redacted_company = {
+            "id": company["id"],
+            "tenant_id": company["tenant_id"],
+            "name": company["name"],
+            "legal_name": company["name"],
+            "website": "[Restricted]",
+            "phone": "[Restricted]",
+            "nic_code": "",
+            "industry": company["industry"],
+            "street": "",
+            "city": company["city"],
+            "province": company["province"],
+            "postal_code": "",
+            "country": company["country"],
+            "size_staff": None,
+            "revenue_band": "[Restricted]",
+            "business_type": "other",
+            "products_made": "[Restricted]",
+            "parts_sourced": "[Restricted]",
+            "current_supplier_notes": "[Restricted]",
+            "maplempss_fit_score": None,
+            "stage_id": company["stage_id"],
+            "assigned_rep_id": company["assigned_rep_id"],
+            "stage_name": company["stage_name"],
+            "stage_color_bg": company["stage_color_bg"],
+            "stage_color_text": company["stage_color_text"],
+        }
+        conn.close()
+        return jsonify({
+            "company": redacted_company,
+            "contacts": [],
+            "activities": [],
+            "notes": [],
+            "ai_fields": [],
+            "read_only": True,
+            "restricted": True
+        })
+
+    # Load remaining fields sequentially on the same connection
+    cursor.execute("SELECT * FROM contacts WHERE company_id = ? ORDER BY is_primary DESC", (company_id,))
+    contacts = [dict_from_row(r) for r in cursor.fetchall()]
+
+    cursor.execute("""
+        SELECT a.*, u.name as user_name
+        FROM activities a
+        LEFT JOIN users u ON a.user_id = u.id
+        WHERE a.company_id = ?
+        ORDER BY a.occurred_at DESC
+    """, (company_id,))
+    activities = [dict_from_row(r) for r in cursor.fetchall()]
+
+    cursor.execute("""
+        SELECT n.*, u.name as user_name
+        FROM notes n
+        LEFT JOIN users u ON n.user_id = u.id
+        WHERE n.company_id = ?
+        ORDER BY n.is_pinned DESC, n.created_at DESC
+    """, (company_id,))
+    notes = [dict_from_row(r) for r in cursor.fetchall()]
+
+    cursor.execute("SELECT * FROM ai_field_values WHERE company_id = ?", (company_id,))
+    ai_fields = [dict_from_row(r) for r in cursor.fetchall()]
+    conn.close()
+
+    return jsonify({
+        "company": company,
+        "contacts": contacts,
+        "activities": activities,
+        "notes": notes,
+        "ai_fields": ai_fields,
+        "read_only": (level == 'viewer'),
+        "restricted": False
+    })
+
+@companies_bp.route("/<int:company_id>", methods=["POST"])
+def update_company(company_id):
+    data = request.json
+    if not data or not data.get("name"):
+        return jsonify({"error": "Company name is required"}), 400
+
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    level = get_user_access_level(conn, user_id, role, company_id)
+    if level in ('basic', 'viewer'):
+        conn.close()
+        return jsonify({"error": "You are not authorized to edit this company."}), 403
+
+    cursor = conn.cursor()
+    try:
+        cursor.execute("SELECT stage_id FROM companies WHERE id = ?", (company_id,))
+        row = cursor.fetchone()
+        if not row:
+            conn.close()
+            return jsonify({"error": "Company not found"}), 404
+        old_stage_id = row[0]
+        new_stage_id = safe_int(data.get("stage_id"), old_stage_id)
+
+        cursor.execute("""
+            UPDATE companies SET
+                name = ?, legal_name = ?, website = ?, phone = ?, nic_code = ?, industry = ?,
+                street = ?, city = ?, province = ?, postal_code = ?, country = ?, size_staff = ?,
+                revenue_band = ?, business_type = ?, products_made = ?, parts_sourced = ?,
+                current_supplier_notes = ?, maplempss_fit_score = ?, stage_id = ?,
+                updated_at = CURRENT_TIMESTAMP
+            WHERE id = ?
+        """, (
+            data.get("name"), data.get("legal_name", data.get("name")), data.get("website", ""),
+            data.get("phone", ""), data.get("nic_code", ""), data.get("industry", ""),
+            data.get("street", ""), data.get("city", ""), data.get("province", ""),
+            data.get("postal_code", ""), data.get("country", "Canada"),
+            extract_int(data.get("size_staff"), 0), data.get("revenue_band", "<1M"),
+            data.get("business_type", "OEM"), data.get("products_made", ""),
+            data.get("parts_sourced", ""), data.get("current_supplier_notes", ""),
+            extract_float(data.get("maplempss_fit_score"), 0.0), new_stage_id, company_id
+        ))
+
+        if old_stage_id != new_stage_id:
+            log_stage_change(cursor, company_id, new_stage_id, user_id, "manual", old_stage_id)
+
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@companies_bp.route("/<int:company_id>/stage", methods=["POST"])
+def update_company_stage(company_id):
+    data = request.json
+    if not data or not data.get("stage_id"):
+        return jsonify({"error": "Stage ID is required"}), 400
+
+    new_stage_id = safe_int(data.get("stage_id"), None)
+    if new_stage_id is None:
+        return jsonify({"error": "Stage ID is required"}), 400
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    level = get_user_access_level(conn, user_id, role, company_id)
+    if level in ('basic', 'viewer'):
+        conn.close()
+        return jsonify({"error": "You are not authorized to update this company's stage."}), 403
+
+    cursor = conn.cursor()
+    cursor.execute("SELECT stage_id FROM companies WHERE id = ?", (company_id,))
+    row = cursor.fetchone()
+    if not row:
+        conn.close()
+        return jsonify({"error": "Company not found"}), 404
+    old_stage_id = row[0]
+
+    cursor.execute("UPDATE companies SET stage_id = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?", (new_stage_id, company_id))
+
+    log_stage_change(cursor, company_id, new_stage_id, user_id, "manual", old_stage_id)
+
+    conn.commit()
+    conn.close()
+    return jsonify({"success": True})
+
+@companies_bp.route("/<int:company_id>/notes", methods=["POST"])
+def add_company_note(company_id):
+    data = request.json
+    if not data or not data.get("body"):
+        return jsonify({"error": "Note text is required"}), 400
+
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    level = get_user_access_level(conn, user_id, role, company_id)
+    if level in ('basic', 'viewer'):
+        conn.close()
+        return jsonify({"error": "You are not authorized to add notes for this company."}), 403
+
+    cursor = conn.cursor()
+    cursor.execute("""
+        INSERT INTO notes (company_id, user_id, body, is_pinned)
+        VALUES (?, ?, ?, ?)
+    """, (company_id, user_id, data["body"], 1 if data.get("is_pinned") else 0))
+    conn.commit()
+    conn.close()
+    return jsonify({"success": True})
+
+@companies_bp.route("/<int:company_id>/activities", methods=["POST"])
+def add_company_activity(company_id):
+    data = request.json
+    if not data or not data.get("type"):
+        return jsonify({"error": "Activity type is required"}), 400
+
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    level = get_user_access_level(conn, user_id, role, company_id)
+    if level in ('basic', 'viewer'):
+        conn.close()
+        return jsonify({"error": "You are not authorized to log activities for this company."}), 403
+
+    cursor = conn.cursor()
+    cursor.execute("""
+        INSERT INTO activities (company_id, user_id, type, outcome, notes, next_action, next_action_date)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+    """, (
+        company_id, user_id, data["type"], data.get("outcome", ""), data.get("notes", ""),
+        data.get("next_action", ""), data.get("next_action_date", None)
+    ))
+    conn.commit()
+    conn.close()
+    return jsonify({"success": True})
+
+@companies_bp.route("/delete", methods=["POST"])
+def delete_companies():
+    data = request.json
+    if not data or not data.get("ids"):
+        return jsonify({"error": "No IDs provided"}), 400
+    ids = [int(x) for x in data["ids"]]
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    for company_id in ids:
+        level = get_user_access_level(conn, user_id, role, company_id)
+        if level in ('basic', 'viewer'):
+            conn.close()
+            return jsonify({"error": f"You are not authorized to delete company ID {company_id}."}), 403
+
+    cursor = conn.cursor()
+    try:
+        placeholders = ",".join("?" for _ in ids)
+        cursor.execute(f"DELETE FROM companies WHERE id IN ({placeholders})", ids)
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@companies_bp.route("/assign", methods=["POST"])
+def assign_companies():
+    data = request.json
+    if not data or not data.get("ids"):
+        return jsonify({"error": "No IDs provided"}), 400
+    ids = [int(x) for x in data["ids"]]
+    assigned_rep_id = data.get("assigned_rep_id")
+    if assigned_rep_id is not None and assigned_rep_id != "":
+        assigned_rep_id = int(assigned_rep_id)
+    else:
+        assigned_rep_id = None
+
+    user_id, role, _ = get_request_user()
+    if role not in ("Super Admin", "Admin"):
+        return jsonify({"error": "Only Admins can assign companies to representatives."}), 403
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        placeholders = ",".join("?" for _ in ids)
+        cursor.execute(f"UPDATE companies SET assigned_rep_id = ? WHERE id IN ({placeholders})", [assigned_rep_id] + ids)
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500

routes/contacts.py

@@ -0,0 +1,135 @@
+from flask import Blueprint, jsonify, request
+from db import get_db_connection, dict_from_row, get_request_user, get_user_access_level, is_supabase_active
+
+contacts_bp = Blueprint('contacts', __name__)
+
+def insert_and_get_id(cursor, sql, params):
+    cursor.execute(sql, params)
+    return cursor.lastrowid
+
+@contacts_bp.route("", methods=["GET"])
+def get_contacts():
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    if role in ('Super Admin', 'Admin', 'Viewer'):
+        cursor.execute("""
+            SELECT co.*, cp.name as company_name
+            FROM contacts co
+            JOIN companies cp ON co.company_id = cp.id
+            ORDER BY co.first_name ASC
+        """)
+    else:
+        cursor.execute("""
+            SELECT co.*, cp.name as company_name
+            FROM contacts co
+            JOIN companies cp ON co.company_id = cp.id
+            WHERE cp.assigned_rep_id = ?
+            ORDER BY co.first_name ASC
+        """, (user_id,))
+    rows = cursor.fetchall()
+    contacts = [dict_from_row(row) for row in rows]
+    conn.close()
+    return jsonify(contacts)
+
+@contacts_bp.route("", methods=["POST"])
+def add_contact():
+    data = request.json
+    if not data or not data.get("first_name") or not data.get("last_name") or not data.get("company_id"):
+        return jsonify({"error": "First name, Last name, and Company ID are required"}), 400
+
+    company_id = int(data["company_id"])
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    level = get_user_access_level(conn, user_id, role, company_id)
+    if level in ('basic', 'viewer'):
+        conn.close()
+        return jsonify({"error": "You are not authorized to add contacts to this company."}), 403
+
+    cursor = conn.cursor()
+    try:
+        is_primary = 1 if data.get("is_primary") else 0
+
+        if is_primary == 1:
+            cursor.execute("UPDATE contacts SET is_primary = 0 WHERE company_id = ?", (company_id,))
+
+        contact_id = insert_and_get_id(cursor, """
+            INSERT INTO contacts (
+                company_id, first_name, last_name, title, email, phone, linkedin, is_primary
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            company_id, data["first_name"], data["last_name"], data.get("title", ""),
+            data.get("email", ""), data.get("phone", ""), data.get("linkedin", ""), is_primary
+        ))
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True, "id": contact_id})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@contacts_bp.route("/<int:contact_id>", methods=["POST"])
+def update_contact(contact_id):
+    data = request.json
+    if not data or not data.get("first_name") or not data.get("last_name") or not data.get("company_id"):
+        return jsonify({"error": "First name, Last name, and Company ID are required"}), 400
+
+    company_id = int(data["company_id"])
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    level = get_user_access_level(conn, user_id, role, company_id)
+    if level in ('basic', 'viewer'):
+        conn.close()
+        return jsonify({"error": "You are not authorized to edit contacts for this company."}), 403
+
+    cursor = conn.cursor()
+    try:
+        is_primary = 1 if data.get("is_primary") else 0
+
+        if is_primary == 1:
+            cursor.execute("UPDATE contacts SET is_primary = 0 WHERE company_id = ? AND id != ?", (company_id, contact_id))
+
+        cursor.execute("""
+            UPDATE contacts SET
+                company_id = ?, first_name = ?, last_name = ?, title = ?, email = ?,
+                phone = ?, linkedin = ?, is_primary = ?
+            WHERE id = ?
+        """, (
+            company_id, data["first_name"], data["last_name"], data.get("title", ""),
+            data.get("email", ""), data.get("phone", ""), data.get("linkedin", ""),
+            is_primary, contact_id
+        ))
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@contacts_bp.route("/delete", methods=["POST"])
+def delete_contacts():
+    data = request.json
+    if not data or not data.get("ids"):
+        return jsonify({"error": "No IDs provided"}), 400
+    ids = [int(x) for x in data["ids"]]
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    for contact_id in ids:
+        cursor.execute("SELECT company_id FROM contacts WHERE id = ?", (contact_id,))
+        row = cursor.fetchone()
+        if not row:
+            continue
+        level = get_user_access_level(conn, user_id, role, row[0])
+        if level in ('basic', 'viewer'):
+            conn.close()
+            return jsonify({"error": f"You are not authorized to delete contact ID {contact_id}."}), 403
+    try:
+        placeholders = ",".join("?" for _ in ids)
+        cursor.execute(f"DELETE FROM contacts WHERE id IN ({placeholders})", ids)
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500

routes/learning.py

@@ -0,0 +1,224 @@
+"""Flask routes for the Learning section RAG chatbot."""
+
+from __future__ import annotations
+
+from flask import Blueprint, jsonify, request
+
+from db import get_request_user
+
+from services.rag_service import (
+    add_document,
+    add_youtube_url,
+    add_video_file,
+    create_collection,
+    create_session,
+    delete_collection,
+    delete_document,
+    delete_session,
+    get_session_messages,
+    list_collections,
+    list_documents,
+    list_sessions,
+    query_collection,
+    rename_collection,
+    rename_session,
+)
+
+learning_bp = Blueprint("learning", __name__)
+
+# ── Collections ───────────────────────────────────────────────────────────
+@learning_bp.post("/collections")
+def api_create_collection():
+    payload = request.get_json(force=True, silent=True) or {}
+    name = str(payload.get("name") or "").strip()
+    if not name:
+        return jsonify({"error": "Collection name is required."}), 400
+    visibility = str(payload.get("visibility") or "private").strip()
+    user_id_val, _, _ = get_request_user()
+    try:
+        return jsonify(create_collection(name, user_id=str(user_id_val), visibility=visibility))
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.get("/collections")
+def api_list_collections():
+    try:
+        user_id_val, role_val, _ = get_request_user()
+        return jsonify(list_collections(user_id=str(user_id_val), user_role=str(role_val)))
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.delete("/collections/<collection_id>")
+def api_delete_collection(collection_id: str):
+    try:
+        delete_collection(collection_id)
+        return jsonify({"success": True})
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.put("/collections/<collection_id>")
+def api_rename_collection(collection_id: str):
+    payload = request.get_json(force=True, silent=True) or {}
+    name = str(payload.get("name") or "").strip()
+    if not name:
+        return jsonify({"error": "New name is required."}), 400
+    try:
+        return jsonify(rename_collection(collection_id, name))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# ── Documents ─────────────────────────────────────────────────────────────
+@learning_bp.post("/collections/<collection_id>/upload")
+def api_upload_documents(collection_id: str):
+    files = request.files.getlist("files")
+    if not files or all(f.filename == "" for f in files):
+        return jsonify({"error": "No files uploaded."}), 400
+    results = []
+    errors = []
+    for f in files:
+        if not f.filename:
+            continue
+        try:
+            doc_info = add_document(collection_id, f)
+            results.append(doc_info)
+        except Exception as exc:
+            errors.append({"filename": f.filename, "error": str(exc)})
+    resp = {"documents": results}
+    if errors:
+        resp["errors"] = errors
+    status = 200 if results else 400
+    return jsonify(resp), status
+
+@learning_bp.get("/collections/<collection_id>/documents")
+def api_list_documents(collection_id: str):
+    try:
+        return jsonify(list_documents(collection_id))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.delete("/collections/<collection_id>/documents/<doc_id>")
+def api_delete_document(collection_id: str, doc_id: str):
+    try:
+        delete_document(collection_id, doc_id)
+        return jsonify({"success": True})
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# ── YouTube URL ────────────────────────────────────────────────────────────
+@learning_bp.post("/collections/<collection_id>/add-url")
+def api_add_youtube_url(collection_id: str):
+    payload = request.get_json(force=True, silent=True) or {}
+    url = str(payload.get("url") or "").strip()
+    if not url:
+        return jsonify({"error": "URL is required."}), 400
+    try:
+        result = add_youtube_url(collection_id, url)
+        return jsonify(result)
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# ── MP4 Video upload ──────────────────────��───────────────────────────────
+@learning_bp.post("/collections/<collection_id>/upload-video")
+def api_upload_video(collection_id: str):
+    f = request.files.get("video")
+    if not f or not f.filename:
+        return jsonify({"error": "No video file uploaded."}), 400
+    try:
+        result = add_video_file(collection_id, f)
+        return jsonify(result)
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# ── Sessions ──────────────────────────────────────────────────────────────
+@learning_bp.post("/collections/<collection_id>/sessions")
+def api_create_session(collection_id: str):
+    payload = request.get_json(force=True, silent=True) or {}
+    name = str(payload.get("name") or "").strip() or None
+    try:
+        return jsonify(create_session(collection_id, name))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.get("/collections/<collection_id>/sessions")
+def api_list_sessions(collection_id: str):
+    try:
+        return jsonify(list_sessions(collection_id))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.get("/collections/<collection_id>/sessions/<session_id>/messages")
+def api_get_session_messages(collection_id: str, session_id: str):
+    try:
+        return jsonify(get_session_messages(collection_id, session_id))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.delete("/collections/<collection_id>/sessions/<session_id>")
+def api_delete_session(collection_id: str, session_id: str):
+    try:
+        delete_session(collection_id, session_id)
+        return jsonify({"success": True})
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@learning_bp.put("/collections/<collection_id>/sessions/<session_id>")
+def api_rename_session(collection_id: str, session_id: str):
+    payload = request.get_json(force=True, silent=True) or {}
+    name = str(payload.get("name") or "").strip()
+    if not name:
+        return jsonify({"error": "New name is required."}), 400
+    try:
+        return jsonify(rename_session(collection_id, session_id, name))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# ── Chat (RAG query) ─────────────────────────────────────────────────────
+@learning_bp.post("/collections/<collection_id>/chat")
+def api_chat(collection_id: str):
+    payload = request.get_json(force=True, silent=True) or {}
+    question = str(payload.get("question") or "").strip()
+    session_id = str(payload.get("session_id") or "").strip() or None
+    if not question:
+        return jsonify({"error": "Question is required."}), 400
+    try:
+        result = query_collection(collection_id, question, session_id=session_id)
+        return jsonify(result)
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# ── Tasks ─────────────────────────────────────
+@learning_bp.get("/tasks/<task_id>")
+def check_task_status(task_id: str):
+    from celery_app import celery_app
+    task = celery_app.AsyncResult(task_id)
+    if task.state == 'PENDING':
+        response = {'status': 'processing'}
+    elif task.state != 'FAILURE':
+        response = {'status': task.state, 'result': task.result}
+    else:
+        response = {'status': 'error', 'error': str(task.info)}
+    return jsonify(response)

routes/stt.py

@@ -0,0 +1,24 @@
+from flask import Blueprint, jsonify
+import requests
+import os
+
+stt_bp = Blueprint('stt', __name__)
+
+ASSEMBLYAI_API_KEY = os.environ.get('ASSEMBLYAI_API_KEY', '9f7a6f9a621c45c29b70afd380ca63f0')
+
+@stt_bp.route('/api/stt/token', methods=['POST'])
+def get_stt_token():
+    """Generate a temporary authentication token for AssemblyAI real-time STT."""
+    try:
+        response = requests.get(
+            'https://streaming.assemblyai.com/v3/token',
+            headers={'Authorization': ASSEMBLYAI_API_KEY},
+            params={'expires_in_seconds': 600}
+        )
+        if response.status_code == 200:
+            data = response.json()
+            return jsonify({'token': data['token']})
+        else:
+            return jsonify({'error': 'Failed to generate token', 'details': response.text}), response.status_code
+    except Exception as e:
+        return jsonify({'error': str(e)}), 500

routes/system.py

@@ -0,0 +1,518 @@
+import re
+from flask import Blueprint, jsonify, request
+from db import get_db_connection, dict_from_row, get_request_user, get_user_access_level, get_request_tenant_id
+from services.ai_service import base_company_context_status, save_base_company_context
+
+stages_bp = Blueprint('stages', __name__)
+activities_bp = Blueprint('activities', __name__)
+stats_bp = Blueprint('stats', __name__)
+columns_bp = Blueprint('columns', __name__)
+settings_bp = Blueprint('settings', __name__)
+
+# =====================================================================
+# Settings Routes
+# =====================================================================
+@settings_bp.route("/company-context", methods=["GET"])
+def get_company_context_setting():
+    return jsonify(base_company_context_status(include_content=True))
+
+@settings_bp.route("/company-context", methods=["POST"])
+def save_company_context_setting():
+    uploaded_file = request.files.get("file")
+    raw_content = ""
+
+    if uploaded_file and uploaded_file.filename:
+        if not uploaded_file.filename.lower().endswith((".md", ".markdown", ".txt")):
+            return jsonify({"error": "Upload a Markdown or text file."}), 400
+        raw_content = uploaded_file.read().decode("utf-8-sig", errors="replace")
+    else:
+        payload = request.get_json(force=True, silent=True) or {}
+        raw_content = payload.get("content", "")
+
+    try:
+        return jsonify(save_base_company_context(raw_content))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+# =====================================================================
+# Users Route
+# =====================================================================
+@settings_bp.route("/users", methods=["GET"])
+def get_users():
+    from db import cache_get, cache_set
+    cached_users = cache_get("prospectiq:users")
+    if cached_users is not None:
+        return jsonify(cached_users)
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT id, name, role, email FROM users ORDER BY id ASC")
+    rows = cursor.fetchall()
+    users = [dict_from_row(row) for row in rows]
+    conn.close()
+
+    cache_set("prospectiq:users", users, timeout=3600)
+    return jsonify(users)
+
+# =====================================================================
+# Stages Routes
+# =====================================================================
+@stages_bp.route("", methods=["GET"])
+def get_stages():
+    from db import cache_get, cache_set
+    cached_stages = cache_get("prospectiq:stages")
+    if cached_stages is not None:
+        return jsonify(cached_stages)
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM stages ORDER BY order_index ASC")
+    rows = cursor.fetchall()
+    stages = [dict_from_row(row) for row in rows]
+    conn.close()
+
+    cache_set("prospectiq:stages", stages, timeout=3600)
+    return jsonify(stages)
+
+# =====================================================================
+# Activities / Notes Routes
+# =====================================================================
+@activities_bp.route("/<int:note_id>/toggle_pin", methods=["POST"])
+def toggle_note_pin(note_id):
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        cursor.execute("SELECT company_id FROM notes WHERE id = ?", (note_id,))
+        note_row = cursor.fetchone()
+        if not note_row:
+            conn.close()
+            return jsonify({"error": "Note not found"}), 404
+
+        level = get_user_access_level(conn, user_id, role, note_row[0])
+        if level in ('basic', 'viewer'):
+            conn.close()
+            return jsonify({"error": "You are not authorized to pin/unpin notes for this company."}), 403
+
+        cursor.execute("SELECT is_pinned FROM notes WHERE id = ?", (note_id,))
+        row = cursor.fetchone()
+        new_status = 1 if row[0] == 0 else 0
+        cursor.execute("UPDATE notes SET is_pinned = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?", (new_status, note_id))
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True, "is_pinned": new_status})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@activities_bp.route("/immediate-actions", methods=["GET"])
+def get_immediate_actions():
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        if role in ('Super Admin', 'Admin', 'Viewer'):
+            cursor.execute("""
+                SELECT a.id, a.next_action as title, a.next_action_date, c.name as company_name, c.id as company_id
+                FROM activities a
+                JOIN companies c ON a.company_id = c.id
+                WHERE a.next_action IS NOT NULL AND a.next_action != ''
+                ORDER BY a.occurred_at DESC
+            """)
+        else:
+            cursor.execute("""
+                SELECT a.id, a.next_action as title, a.next_action_date, c.name as company_name, c.id as company_id
+                FROM activities a
+                JOIN companies c ON a.company_id = c.id
+                WHERE a.next_action IS NOT NULL AND a.next_action != '' AND c.assigned_rep_id = ?
+                ORDER BY a.occurred_at DESC
+            """, (user_id,))
+        rows = cursor.fetchall()
+        actions = [dict_from_row(row) for row in rows]
+        conn.close()
+        return jsonify(actions)
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@activities_bp.route("/immediate-actions/<int:activity_id>/complete", methods=["POST"])
+def complete_immediate_action(activity_id):
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        cursor.execute("SELECT company_id FROM activities WHERE id = ?", (activity_id,))
+        act_row = cursor.fetchone()
+        if not act_row:
+            conn.close()
+            return jsonify({"error": "Activity not found"}), 404
+
+        level = get_user_access_level(conn, user_id, role, act_row[0])
+        if level in ('basic', 'viewer'):
+            conn.close()
+            return jsonify({"error": "You are not authorized to modify actions for this company."}), 403
+
+        cursor.execute("""
+            UPDATE activities
+            SET next_action = '', next_action_date = NULL
+            WHERE id = ?
+        """, (activity_id,))
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@activities_bp.route("/recent", methods=["GET"])
+def get_recent_activities():
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        if role in ('Super Admin', 'Admin', 'Viewer'):
+            cursor.execute("""
+                SELECT a.id, a.type, a.outcome, a.notes, a.occurred_at, c.name as company_name, c.id as company_id
+                FROM activities a
+                JOIN companies c ON a.company_id = c.id
+                ORDER BY a.occurred_at DESC
+                LIMIT 15
+            """)
+        else:
+            cursor.execute("""
+                SELECT a.id, a.type, a.outcome, a.notes, a.occurred_at, c.name as company_name, c.id as company_id
+                FROM activities a
+                JOIN companies c ON a.company_id = c.id
+                WHERE c.assigned_rep_id = ?
+                ORDER BY a.occurred_at DESC
+                LIMIT 15
+            """, (user_id,))
+        rows = cursor.fetchall()
+        activities = [dict_from_row(row) for row in rows]
+        conn.close()
+        return jsonify(activities)
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+# =====================================================================
+# Stats Routes
+# =====================================================================
+@stats_bp.route("", methods=["GET"])
+def get_stats():
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    # Filter stats to respect assigned scope for BD reps
+    if role in ('Super Admin', 'Admin', 'Viewer'):
+        cursor.execute("""
+            SELECT s.name, COUNT(c.id) as count
+            FROM stages s
+            LEFT JOIN companies c ON s.id = c.stage_id
+            GROUP BY s.id
+            ORDER BY s.order_index ASC
+        """)
+        pipeline = [{"stage": r[0], "count": r[1]} for r in cursor.fetchall()]
+
+        cursor.execute("SELECT COUNT(*) FROM companies")
+        total_companies = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM activities WHERE type = 'Cold Call'")
+        calls = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM activities WHERE type = 'Email'")
+        emails = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM activities WHERE type = 'Meeting'")
+        meetings = cursor.fetchone()[0]
+    else:
+        cursor.execute("""
+            SELECT s.name, COUNT(c.id) as count
+            FROM stages s
+            LEFT JOIN companies c ON s.id = c.stage_id AND c.assigned_rep_id = ?
+            GROUP BY s.id
+            ORDER BY s.order_index ASC
+        """, (user_id,))
+        pipeline = [{"stage": r[0], "count": r[1]} for r in cursor.fetchall()]
+
+        cursor.execute("SELECT COUNT(*) FROM companies WHERE assigned_rep_id = ?", (user_id,))
+        total_companies = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM activities WHERE type = 'Cold Call' AND user_id = ?", (user_id,))
+        calls = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM activities WHERE type = 'Email' AND user_id = ?", (user_id,))
+        emails = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM activities WHERE type = 'Meeting' AND user_id = ?", (user_id,))
+        meetings = cursor.fetchone()[0]
+
+    conn.close()
+    return jsonify({
+        "total_companies": total_companies,
+        "calls": calls,
+        "emails": emails,
+        "meetings": meetings,
+        "pipeline": pipeline
+    })
+
+# =====================================================================
+# Dynamic Columns Routes
+# =====================================================================
+@columns_bp.route("/columns/<string:table_name>", methods=["GET"])
+def get_columns(table_name):
+    if table_name not in ["companies", "contacts"]:
+        return jsonify({"error": "Invalid table"}), 400
+    from db import is_supabase_active, cache_get, cache_set
+
+    # Check cache first
+    cache_key = f"prospectiq:columns:{table_name}"
+    cached_columns = cache_get(cache_key)
+    if cached_columns is not None:
+        return jsonify(cached_columns)
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    if is_supabase_active():
+        cursor.execute("""
+            SELECT
+                ordinal_position AS cid,
+                column_name AS name,
+                data_type AS type,
+                CASE WHEN is_nullable = 'NO' THEN 1 ELSE 0 END AS notnull,
+                column_default AS dflt_value,
+                CASE WHEN column_name = 'id' THEN 1 ELSE 0 END AS pk
+            FROM information_schema.columns
+            WHERE table_name = %s
+            ORDER BY ordinal_position
+        """, (table_name,))
+    else:
+        cursor.execute(f"PRAGMA table_info({table_name})")
+    columns = [dict(r) for r in cursor.fetchall()]
+    conn.close()
+
+    # Cache schema for 1 hour
+    cache_set(cache_key, columns, timeout=3600)
+    return jsonify(columns)
+
+@columns_bp.route("/columns/<string:table_name>/add", methods=["POST"])
+def add_column(table_name):
+    if table_name not in ["companies", "contacts"]:
+        return jsonify({"error": "Invalid table"}), 400
+
+    user_id, role, _ = get_request_user()
+    if role not in ('Super Admin', 'Admin'):
+        return jsonify({"error": "Only admins can add custom columns."}), 403
+
+    data = request.json
+    if not data or not data.get("name"):
+        return jsonify({"error": "Column name is required"}), 400
+    column_name = data["name"]
+    clean_name = re.sub(r'[^a-zA-Z0-9_]', '', column_name)
+    if not clean_name:
+        return jsonify({"error": "Invalid column name"}), 400
+
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        cursor.execute(f"ALTER TABLE {table_name} ADD COLUMN {clean_name} TEXT")
+        conn.commit()
+        conn.close()
+
+        # Invalidate cached schema
+        from db import cache_delete
+        cache_delete(f"prospectiq:columns:{table_name}")
+
+        return jsonify({"success": True, "name": clean_name})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+@columns_bp.route("/update_cell", methods=["POST"])
+def update_cell():
+    data = request.json
+    if not data or not data.get("table") or not data.get("id") or not data.get("column"):
+        return jsonify({"error": "Missing required fields"}), 400
+
+    table = data["table"]
+    row_id = int(data["id"])
+    column = data["column"]
+    value = data.get("value")
+
+    if table not in ["companies", "contacts"]:
+        return jsonify({"error": "Invalid table"}), 400
+
+    clean_column = re.sub(r'[^a-zA-Z0-9_]', '', column)
+    if not clean_column:
+        return jsonify({"error": "Invalid column name"}), 400
+
+    user_id, role, _ = get_request_user()
+    conn = get_db_connection()
+
+    if table == 'companies':
+        level = get_user_access_level(conn, user_id, role, row_id)
+        if level in ('basic', 'viewer'):
+            conn.close()
+            return jsonify({"error": "You are not authorized to edit this company."}), 403
+    elif table == 'contacts':
+        cursor = conn.cursor()
+        cursor.execute("SELECT company_id FROM contacts WHERE id = ?", (row_id,))
+        row = cursor.fetchone()
+        if row:
+            level = get_user_access_level(conn, user_id, role, row[0])
+            if level in ('basic', 'viewer'):
+                conn.close()
+                return jsonify({"error": "You are not authorized to edit this contact."}), 403
+
+    cursor = conn.cursor()
+    try:
+        val_to_save = value
+        if clean_column == 'assigned_rep_id':
+            if value == '' or value is None:
+                val_to_save = None
+            else:
+                val_to_save = int(value)
+        cursor.execute(f"UPDATE {table} SET {clean_column} = ? WHERE id = ?", (val_to_save, row_id))
+        conn.commit()
+        conn.close()
+        return jsonify({"success": True})
+    except Exception as e:
+        conn.close()
+        return jsonify({"error": str(e)}), 500
+
+# =====================================================================
+# Bootstrap Endpoint — returns ALL initial page data in one request
+# Eliminates 5 sequential round-trips to Supabase on page load
+# =====================================================================
+bootstrap_bp = Blueprint('bootstrap', __name__)
+
+@bootstrap_bp.route("", methods=["GET"])
+def api_bootstrap():
+    """Return stages, companies, contacts, and column schemas in a single response.
+    Executes sequentially on a single DB connection to eliminate network connection pool
+    and TLS handshake overhead when communicating with Supabase.
+    """
+    from db import is_supabase_active, cache_get, cache_set
+    user_id, role, _ = get_request_user()
+
+    # 1. Retrieve cached stages & columns to avoid database round-trips entirely
+    stages = cache_get("prospectiq:stages")
+    cols_companies = cache_get("prospectiq:columns:companies")
+    cols_contacts = cache_get("prospectiq:columns:contacts")
+
+    # 2. Open single connection to retrieve uncached and dynamic transactional data
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    try:
+        # Fetch stages if not cached
+        if stages is None:
+            cursor.execute("SELECT * FROM stages ORDER BY order_index ASC")
+            stages = [dict_from_row(r) for r in cursor.fetchall()]
+            cache_set("prospectiq:stages", stages, timeout=3600)
+
+        # Fetch companies
+        tenant_id = get_request_tenant_id()
+        if role in ('Super Admin', 'Admin', 'Viewer'):
+            cursor.execute("""
+                SELECT c.*, s.name as stage_name, s.color_bg as stage_color_bg, s.color_text as stage_color_text, u.name as rep_name
+                FROM companies c
+                JOIN stages s ON c.stage_id = s.id
+                LEFT JOIN users u ON c.assigned_rep_id = u.id
+                WHERE c.tenant_id = ?
+                ORDER BY c.maplempss_fit_score DESC, c.name ASC
+            """, (tenant_id,))
+        else:
+            cursor.execute("""
+                SELECT
+                    c.id, c.tenant_id, c.name, c.legal_name, c.industry, c.street, c.city, c.province, c.postal_code, c.country,
+                    c.business_type, c.stage_id, c.assigned_rep_id, c.created_by, c.updated_by, c.import_batch_id, c.created_at, c.updated_at,
+                    s.name as stage_name, s.color_bg as stage_color_bg, s.color_text as stage_color_text, u.name as rep_name,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.website ELSE '[Restricted]' END as website,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.phone ELSE '[Restricted]' END as phone,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.size_staff ELSE NULL END as size_staff,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.revenue_band ELSE '[Restricted]' END as revenue_band,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.products_made ELSE '[Restricted]' END as products_made,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.parts_sourced ELSE '[Restricted]' END as parts_sourced,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.current_supplier_notes ELSE '[Restricted]' END as current_supplier_notes,
+                    CASE WHEN c.assigned_rep_id = ? THEN c.maplempss_fit_score ELSE NULL END as maplempss_fit_score
+                FROM companies c
+                JOIN stages s ON c.stage_id = s.id
+                LEFT JOIN users u ON c.assigned_rep_id = u.id
+                WHERE c.tenant_id = ?
+                ORDER BY c.maplempss_fit_score DESC, c.name ASC
+            """, (user_id, user_id, user_id, user_id, user_id, user_id, user_id, user_id, tenant_id))
+        companies = [dict_from_row(r) for r in cursor.fetchall()]
+
+        # Fetch contacts
+        if role in ('Super Admin', 'Admin', 'Viewer'):
+            cursor.execute("""
+                SELECT co.*, cp.name as company_name
+                FROM contacts co
+                JOIN companies cp ON co.company_id = cp.id
+                WHERE cp.tenant_id = ?
+                ORDER BY co.first_name ASC
+            """, (tenant_id,))
+        else:
+            cursor.execute("""
+                SELECT co.*, cp.name as company_name
+                FROM contacts co
+                JOIN companies cp ON co.company_id = cp.id
+                WHERE cp.tenant_id = ? AND cp.assigned_rep_id = ?
+                ORDER BY co.first_name ASC
+            """, (tenant_id, user_id))
+        contacts = [dict_from_row(r) for r in cursor.fetchall()]
+
+        # Fetch company columns schema if not cached
+        if cols_companies is None:
+            if is_supabase_active():
+                cursor.execute("""
+                    SELECT
+                        ordinal_position AS cid,
+                        column_name AS name,
+                        data_type AS type,
+                        CASE WHEN is_nullable = 'NO' THEN 1 ELSE 0 END AS notnull,
+                        column_default AS dflt_value,
+                        CASE WHEN column_name = 'id' THEN 1 ELSE 0 END AS pk
+                    FROM information_schema.columns
+                    WHERE table_name = %s
+                    ORDER BY ordinal_position
+                """, ("companies",))
+            else:
+                cursor.execute("PRAGMA table_info(companies)")
+            cols_companies = [dict(r) for r in cursor.fetchall()]
+            cache_set("prospectiq:columns:companies", cols_companies, timeout=3600)
+
+        # Fetch contacts columns schema if not cached
+        if cols_contacts is None:
+            if is_supabase_active():
+                cursor.execute("""
+                    SELECT
+                        ordinal_position AS cid,
+                        column_name AS name,
+                        data_type AS type,
+                        CASE WHEN is_nullable = 'NO' THEN 1 ELSE 0 END AS notnull,
+                        column_default AS dflt_value,
+                        CASE WHEN column_name = 'id' THEN 1 ELSE 0 END AS pk
+                    FROM information_schema.columns
+                    WHERE table_name = %s
+                    ORDER BY ordinal_position
+                """, ("contacts",))
+            else:
+                cursor.execute("PRAGMA table_info(contacts)")
+            cols_contacts = [dict(r) for r in cursor.fetchall()]
+            cache_set("prospectiq:columns:contacts", cols_contacts, timeout=3600)
+
+    finally:
+        conn.close()
+
+    result = {
+        "stages": stages,
+        "companies": companies,
+        "contacts": contacts,
+        "columns_companies": cols_companies,
+        "columns_contacts": cols_contacts,
+    }
+    return jsonify(result)

schema.sql

@@ -0,0 +1,187 @@
+-- ProspectIQ SQLite Database Schema for Cycle 1
+
+CREATE TABLE IF NOT EXISTS tenants (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    brand_color TEXT,
+    logo_url TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS permissions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    code TEXT UNIQUE NOT NULL,
+    description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS roles (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tenant_id INTEGER NOT NULL,
+    name TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
+    UNIQUE(tenant_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS role_permissions (
+    role_id INTEGER NOT NULL,
+    permission_id INTEGER NOT NULL,
+    PRIMARY KEY(role_id, permission_id),
+    FOREIGN KEY(role_id) REFERENCES roles(id) ON DELETE CASCADE,
+    FOREIGN KEY(permission_id) REFERENCES permissions(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tenant_id INTEGER NOT NULL,
+    email TEXT UNIQUE NOT NULL,
+    name TEXT NOT NULL,
+    password_hash TEXT,
+    role_id INTEGER,
+    role TEXT NOT NULL CHECK(role IN ('Super Admin', 'Admin', 'BD Rep', 'Viewer')),
+    is_active INTEGER DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(tenant_id) REFERENCES tenants(id),
+    FOREIGN KEY(role_id) REFERENCES roles(id)
+);
+
+CREATE TABLE IF NOT EXISTS stages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    order_index INTEGER NOT NULL UNIQUE,
+    color_bg TEXT,
+    color_text TEXT,
+    is_active INTEGER DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS companies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tenant_id INTEGER NOT NULL,
+    name TEXT NOT NULL,
+    legal_name TEXT,
+    website TEXT,
+    phone TEXT,
+    nic_code TEXT,
+    industry TEXT,
+    street TEXT,
+    city TEXT,
+    province TEXT,
+    postal_code TEXT,
+    country TEXT,
+    size_staff INTEGER,
+    revenue_band TEXT,
+    business_type TEXT CHECK(business_type IN ('OEM', 'distributor', 'other', 'OEM / distributor', 'OEM / Distributor')),
+    products_made TEXT,
+    parts_sourced TEXT,
+    current_supplier_notes TEXT,
+    maplempss_fit_score REAL DEFAULT 0.0,
+    stage_id INTEGER NOT NULL,
+    assigned_rep_id INTEGER,
+    created_by INTEGER,
+    updated_by INTEGER,
+    import_batch_id INTEGER,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(tenant_id) REFERENCES tenants(id),
+    FOREIGN KEY(stage_id) REFERENCES stages(id),
+    FOREIGN KEY(assigned_rep_id) REFERENCES users(id),
+    FOREIGN KEY(created_by) REFERENCES users(id),
+    FOREIGN KEY(updated_by) REFERENCES users(id)
+);
+
+CREATE TABLE IF NOT EXISTS contacts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    company_id INTEGER NOT NULL,
+    first_name TEXT NOT NULL,
+    last_name TEXT NOT NULL,
+    title TEXT,
+    email TEXT,
+    phone TEXT,
+    linkedin TEXT,
+    is_primary INTEGER DEFAULT 0 CHECK(is_primary IN (0, 1)),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(company_id) REFERENCES companies(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS activities (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    company_id INTEGER NOT NULL,
+    contact_id INTEGER,
+    user_id INTEGER NOT NULL,
+    type TEXT NOT NULL CHECK(type IN ('Cold Call', 'Email', 'LinkedIn Message', 'Meeting', 'Follow-Up', 'Note')),
+    outcome TEXT,
+    notes TEXT,
+    next_action TEXT,
+    next_action_date TEXT,
+    occurred_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(company_id) REFERENCES companies(id) ON DELETE CASCADE,
+    FOREIGN KEY(contact_id) REFERENCES contacts(id) ON DELETE SET NULL,
+    FOREIGN KEY(user_id) REFERENCES users(id)
+);
+
+CREATE TABLE IF NOT EXISTS notes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    company_id INTEGER NOT NULL,
+    contact_id INTEGER,
+    user_id INTEGER NOT NULL,
+    body TEXT NOT NULL,
+    is_pinned INTEGER DEFAULT 0 CHECK(is_pinned IN (0, 1)),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(company_id) REFERENCES companies(id) ON DELETE CASCADE,
+    FOREIGN KEY(contact_id) REFERENCES contacts(id) ON DELETE SET NULL,
+    FOREIGN KEY(user_id) REFERENCES users(id)
+);
+
+CREATE TABLE IF NOT EXISTS stage_changes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    company_id INTEGER NOT NULL,
+    from_stage_id INTEGER,
+    to_stage_id INTEGER NOT NULL,
+    changed_by_user_id INTEGER NOT NULL,
+    source TEXT NOT NULL CHECK(source IN ('manual', 'ai_suggested', 'ai_confirmed')),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(company_id) REFERENCES companies(id) ON DELETE CASCADE,
+    FOREIGN KEY(from_stage_id) REFERENCES stages(id),
+    FOREIGN KEY(to_stage_id) REFERENCES stages(id),
+    FOREIGN KEY(changed_by_user_id) REFERENCES users(id)
+);
+
+CREATE TABLE IF NOT EXISTS ai_field_values (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    company_id INTEGER NOT NULL,
+    field_name TEXT NOT NULL,
+    value TEXT,
+    source_url TEXT,
+    confidence_score REAL,
+    enriched_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    confirmed_by_user_id INTEGER,
+    confirmed_at TIMESTAMP,
+    FOREIGN KEY(company_id) REFERENCES companies(id) ON DELETE CASCADE,
+    FOREIGN KEY(confirmed_by_user_id) REFERENCES users(id)
+);
+
+CREATE TABLE IF NOT EXISTS import_batches (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    filename TEXT,
+    status TEXT,
+    total_rows INTEGER,
+    added INTEGER,
+    updated INTEGER,
+    skipped INTEGER,
+    errored INTEGER,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    completed_at TIMESTAMP,
+    FOREIGN KEY(user_id) REFERENCES users(id)
+);
+
+-- Indices for fast searching and filtering
+CREATE INDEX IF NOT EXISTS idx_companies_stage ON companies(stage_id);
+CREATE INDEX IF NOT EXISTS idx_companies_tenant ON companies(tenant_id);
+CREATE INDEX IF NOT EXISTS idx_companies_rep ON companies(assigned_rep_id);
+CREATE INDEX IF NOT EXISTS idx_contacts_company ON contacts(company_id);
+CREATE INDEX IF NOT EXISTS idx_activities_company ON activities(company_id);
+CREATE INDEX IF NOT EXISTS idx_notes_company ON notes(company_id);

scratch_check.py

@@ -0,0 +1,25 @@
+import sqlite3
+import json
+
+conn = sqlite3.connect('interactions.db')
+cursor = conn.cursor()
+cursor.execute("SELECT output_json, logs_json FROM interactions WHERE kind='geo' ORDER BY created_at DESC LIMIT 1")
+res = cursor.fetchone()
+
+if res:
+    print("LOGS:")
+    logs = json.loads(res[1]) if res[1] else []
+    for log in logs[-20:]:
+        print(log)
+    
+    print("\nOUTPUT_JSON (result):")
+    output = json.loads(res[0]) if res[0] else {}
+    print(json.dumps(output.get("result", "")[:1000], indent=2))
+    
+    stages = output.get("stages", [])
+    if stages:
+        for stage in stages:
+            print(f"\nStage: {stage.get('step')}")
+            data = stage.get("data", "")
+            if isinstance(data, str):
+                print(data[:500] + "..." if len(data) > 500 else data)

scratch_check_app.py

@@ -0,0 +1,26 @@
+import sys
+sys.path.append('.')
+from services.ai_service import db_list_interactions
+import json
+
+# Get the last geo interaction
+interactions = db_list_interactions(limit=1, kind="geo", include_full=True)
+if interactions:
+    last = interactions[0]
+    print(f"Title: {last.get('title')}")
+    print(f"Status: {last.get('status')}")
+    print("----- RESULT -----")
+    result = last.get('result', {})
+    if isinstance(result, dict):
+        print(json.dumps(result.get('result', ''), indent=2))
+        
+        stages = result.get('stages', [])
+        for stage in stages:
+            print(f"\nStage: {stage.get('step')}")
+            data = stage.get("data", "")
+            if isinstance(data, str):
+                print(data[:500] + "..." if len(data) > 500 else data)
+    else:
+        print(result)
+else:
+    print("No interactions found.")

scripts/deploy-azure.ps1

@@ -0,0 +1,49 @@
+param(
+    [string]$ResourceGroup = "ProspectIQ_centralindia",
+    [string]$ContainerApp = "prospectiq",
+    [string]$Registry = "prospectiqacr57421",
+    [string]$ImageName = "prospectiq",
+    [string]$Tag = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+if (-not $Tag) {
+    $gitSha = git rev-parse --short HEAD
+    $Tag = if ($gitSha) { $gitSha.Trim() } else { "latest" }
+}
+
+$loginServer = "$Registry.azurecr.io"
+$image = "$loginServer/$ImageName`:$Tag"
+$latest = "$loginServer/$ImageName`:latest"
+
+Write-Host "Checking Azure login..."
+az account show --query "{subscription:name,user:user.name}" -o table
+
+Write-Host "Logging in to Azure Container Registry: $Registry"
+az acr login --name $Registry
+
+Write-Host "Building Docker image: $image"
+docker build -t $image -t $latest .
+
+Write-Host "Pushing Docker image: $image"
+docker push $image
+
+Write-Host "Pushing Docker image: $latest"
+docker push $latest
+
+Write-Host "Updating Azure Container App: $ContainerApp"
+az containerapp update `
+    --name $ContainerApp `
+    --resource-group $ResourceGroup `
+    --image $image
+
+$fqdn = az containerapp show `
+    --name $ContainerApp `
+    --resource-group $ResourceGroup `
+    --query properties.configuration.ingress.fqdn `
+    -o tsv
+
+Write-Host ""
+Write-Host "Deployment complete."
+Write-Host "URL: https://$fqdn"

services/__init__.py

@@ -0,0 +1 @@
+"""Services package for ProspectIQ."""

services/ai_service.py

@@ -0,0 +1,998 @@
+from __future__ import annotations
+import contextlib
+import json
+import os
+import re
+import sqlite3
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, TypeVar
+
+# =====================================================================
+# Paths & Lock Configuration
+# =====================================================================
+SERVICES_DIR = Path(__file__).resolve().parent
+ROOT = SERVICES_DIR.parent
+RESEARCH_DIR = SERVICES_DIR / "research"
+PIPELINE_SCRIPT = RESEARCH_DIR / "pipeline.py"
+RESEARCH_OUTPUT_DIR = RESEARCH_DIR / "pipe_output"
+DATABASE_PATH = ROOT / "prospectiq_history.db"
+SETTINGS_DIR = ROOT / "settings"
+BASE_COMPANY_CONTEXT_PATH = SETTINGS_DIR / "base_company_context.md"
+
+DB_LOCK = threading.Lock()
+JOBS_LOCK = threading.Lock()
+JOBS: dict[str, dict[str, Any]] = {}
+JOB_CACHE_TTL = 24 * 60 * 60
+
+T = TypeVar("T")
+
+
+# =====================================================================
+# API Keys Utility Section (Failover & Fallback)
+# =====================================================================
+DEFAULT_ENV_PATHS = (ROOT / ".env", Path.cwd() / ".env")
+PAID_GEMINI_ENV_NAMES = (
+    "GEMINI_API_KEY_prime_1",
+    "GEMINI_API_KEY_prime_2",
+    "GEMINI_API_KEY_prime_3",
+)
+
+
+def load_dotenv_values() -> dict[str, str]:
+    values: dict[str, str] = {}
+    for path in DEFAULT_ENV_PATHS:
+        if not path.exists():
+            continue
+        for raw_line in path.read_text(encoding="utf-8-sig", errors="replace").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            name, value = line.split("=", 1)
+            values[name.strip()] = value.strip().strip('"').strip("'")
+    return values
+
+
+def env_value(name: str, dotenv_values: dict[str, str] | None = None) -> str:
+    values = dotenv_values if dotenv_values is not None else load_dotenv_values()
+    return os.environ.get(name, "").strip() or values.get(name, "").strip()
+
+
+def numbered_env_names(prefix: str, values: dict[str, str]) -> list[str]:
+    names = {
+        *[name for name in values if re.fullmatch(rf"{re.escape(prefix)}_\d+", name)],
+        *[name for name in os.environ if re.fullmatch(rf"{re.escape(prefix)}_\d+", name)],
+    }
+    return sorted(names, key=lambda name: int(name.rsplit("_", 1)[1]))
+
+
+def api_keys(primary_name: str, *preferred_names: str) -> list[str]:
+    values = load_dotenv_values()
+    keys: list[str] = []
+
+    for name in (*preferred_names, primary_name):
+        key = env_value(name, values)
+        if key and key not in keys:
+            keys.append(key)
+
+    for name in numbered_env_names(primary_name, values):
+        key = env_value(name, values)
+        if key and key not in keys:
+            keys.append(key)
+
+    return keys
+
+
+def gemini_keys(*preferred_names: str) -> list[str]:
+    values = load_dotenv_values()
+    keys: list[str] = []
+    for name in PAID_GEMINI_ENV_NAMES:
+        key = env_value(name, values)
+        if key and key not in keys:
+            keys.append(key)
+    return keys
+
+
+def groq_keys() -> list[str]:
+    return api_keys("GROQ_API_KEY")
+
+
+def with_gemini_key_fallback(preferred_names: tuple[str, ...], operation: Callable[[str], T]) -> T:
+    keys = gemini_keys(*preferred_names)
+    if not keys:
+        names = ", ".join(PAID_GEMINI_ENV_NAMES)
+        raise RuntimeError(f"No Gemini API keys configured. Set one of: {names}.")
+
+    failures: list[str] = []
+    for index, key in enumerate(keys, start=1):
+        try:
+            return operation(key)
+        except Exception as exc:
+            failures.append(f"key {index}/{len(keys)}: {type(exc).__name__}: {exc}")
+
+    raise RuntimeError("All configured Gemini API keys failed. " + " | ".join(failures))
+
+
+# =====================================================================
+# Database operations for prospectiq_history.db
+# =====================================================================
+
+def now() -> str:
+    return time.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def to_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, default=lambda val: str(val) if isinstance(val, Path) else str(val))
+
+
+def from_json(value: str | None, default: Any) -> Any:
+    if not value:
+        return default
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        return default
+
+
+def get_db():
+    from db import get_db_connection, pg_pool
+    # If PG connection parameters are specified, use PostgresConnectionPool
+    if pg_pool is not None or (os.environ.get("SUPABASE_DB_HOST") and os.environ.get("SUPABASE_DB_PASSWORD")):
+        try:
+            return get_db_connection()
+        except Exception as e:
+            print(f"Error redirecting get_db to PostgreSQL: {e}")
+            
+    connection = sqlite3.connect(DATABASE_PATH, timeout=30)
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+@contextlib.contextmanager
+def db_session():
+    from db import is_supabase_active
+    if is_supabase_active():
+        with get_db() as db:
+            yield db
+    else:
+        with DB_LOCK, get_db() as db:
+            yield db
+
+
+def init_database() -> None:
+    with db_session() as db:
+        db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS interactions (
+                id TEXT PRIMARY KEY,
+                kind TEXT NOT NULL,
+                title TEXT NOT NULL,
+                status TEXT NOT NULL,
+                input_json TEXT NOT NULL DEFAULT '{}',
+                output_json TEXT NOT NULL DEFAULT '{}',
+                result_text TEXT NOT NULL DEFAULT '',
+                logs_json TEXT NOT NULL DEFAULT '[]',
+                error TEXT NOT NULL DEFAULT '',
+                run_dir TEXT NOT NULL DEFAULT '',
+                profile_path TEXT NOT NULL DEFAULT '',
+                command_json TEXT NOT NULL DEFAULT '[]',
+                returncode INTEGER,
+                pid INTEGER,
+                created_at TEXT NOT NULL,
+                started_at TEXT NOT NULL DEFAULT '',
+                finished_at TEXT NOT NULL DEFAULT '',
+                updated_at TEXT NOT NULL
+            )
+            """
+        )
+        db.execute("CREATE INDEX IF NOT EXISTS idx_interactions_created_at ON interactions(created_at DESC)")
+        db.execute("CREATE INDEX IF NOT EXISTS idx_interactions_kind ON interactions(kind)")
+
+
+def result_text_from_job(job: dict[str, Any]) -> str:
+    result = job.get("result")
+    if isinstance(result, dict):
+        for key in ("text", "result", "answer", "profile_text"):
+            value = result.get(key)
+            if isinstance(value, str):
+                return value
+    if isinstance(result, str):
+        return result
+    return ""
+
+
+def profile_path_from_job(job: dict[str, Any]) -> str:
+    result = job.get("result")
+    if isinstance(result, dict):
+        return str(result.get("path") or result.get("profile_path") or "")
+    return ""
+
+
+def db_insert_interaction(job: dict[str, Any], input_payload: dict[str, Any] | None = None) -> None:
+    with db_session() as db:
+        db.execute(
+            """
+            INSERT OR REPLACE INTO interactions (
+                id, kind, title, status, input_json, output_json, result_text, logs_json,
+                error, run_dir, profile_path, command_json, returncode, pid,
+                created_at, started_at, finished_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                job["id"],
+                job["kind"],
+                job["title"],
+                job["status"],
+                to_json(input_payload or {}),
+                to_json(job.get("result") or {}),
+                result_text_from_job(job),
+                to_json(job.get("logs") or []),
+                job.get("error", ""),
+                job.get("run_dir", ""),
+                profile_path_from_job(job),
+                to_json(job.get("command") or []),
+                job.get("returncode"),
+                job.get("pid"),
+                job.get("created_at", now()),
+                job.get("started_at", ""),
+                job.get("finished_at", ""),
+                now(),
+            ),
+        )
+
+
+def db_update_interaction(job_id: str, **changes: Any) -> None:
+    allowed = {
+        "status",
+        "error",
+        "run_dir",
+        "returncode",
+        "pid",
+        "started_at",
+        "finished_at",
+    }
+    assignments: list[str] = []
+    values: list[Any] = []
+    for key, value in changes.items():
+        if key in allowed:
+            assignments.append(f"{key} = ?")
+            values.append(value)
+        elif key == "result":
+            assignments.extend(["output_json = ?", "result_text = ?", "profile_path = ?"])
+            temp_job = {"result": value}
+            values.extend([to_json(value or {}), result_text_from_job(temp_job), profile_path_from_job(temp_job)])
+        elif key == "logs":
+            assignments.append("logs_json = ?")
+            values.append(to_json(value or []))
+        elif key == "command":
+            assignments.append("command_json = ?")
+            values.append(to_json(value or []))
+
+    if not assignments:
+        return
+
+    assignments.append("updated_at = ?")
+    values.append(now())
+    values.append(job_id)
+    with db_session() as db:
+        db.execute(f"UPDATE interactions SET {', '.join(assignments)} WHERE id = ?", values)
+
+
+def db_get_interaction(job_id: str) -> dict[str, Any] | None:
+    with db_session() as db:
+        row = db.execute("SELECT * FROM interactions WHERE id = ?", (job_id,)).fetchone()
+    return interaction_from_row(row) if row else None
+
+
+def delete_job_cache(job_id: str) -> None:
+    try:
+        from db import cache_delete
+        cache_delete(job_cache_key(job_id))
+    except Exception:
+        pass
+
+
+def db_prune_geo_history(max_age_minutes: int = 20) -> int:
+    """Remove stale active Geo rows from history storage."""
+    max_age_minutes = max(1, int(max_age_minutes or 20))
+    cutoff = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(time.time() - (max_age_minutes * 60)))
+
+    with db_session() as db:
+        rows = db.execute(
+            """
+            SELECT id FROM interactions
+            WHERE kind = ?
+              AND status IN (?, ?)
+              AND COALESCE(NULLIF(started_at, ''), created_at) <= ?
+            """,
+            ("geo", "queued", "running", cutoff),
+        ).fetchall()
+        stale_ids = [str(row["id"]) for row in rows]
+        if stale_ids:
+            placeholders = ", ".join(["?"] * len(stale_ids))
+            db.execute(f"DELETE FROM interactions WHERE id IN ({placeholders})", stale_ids)
+
+    if stale_ids:
+        with JOBS_LOCK:
+            for job_id in stale_ids:
+                JOBS.pop(job_id, None)
+        for job_id in stale_ids:
+            delete_job_cache(job_id)
+
+    return len(stale_ids)
+
+
+def job_cache_key(job_id: str) -> str:
+    return f"prospectiq:job:{job_id}"
+
+
+def cache_job_state(job: dict[str, Any] | None) -> None:
+    if not job or not job.get("id"):
+        return
+    try:
+        from db import cache_set
+        cache_set(job_cache_key(str(job["id"])), job, timeout=JOB_CACHE_TTL)
+    except Exception:
+        pass
+
+
+def get_cached_job_state(job_id: str) -> dict[str, Any] | None:
+    try:
+        from db import cache_get
+        cached = cache_get(job_cache_key(job_id))
+        return cached if isinstance(cached, dict) else None
+    except Exception:
+        return None
+
+
+def get_job_state(job_id: str) -> dict[str, Any] | None:
+    cached = get_cached_job_state(job_id)
+    if cached:
+        if not cached.get("logs"):
+            saved = db_get_interaction(job_id)
+            if saved and saved.get("logs"):
+                cached["logs"] = saved.get("logs") or []
+                if not cached.get("result") and saved.get("result"):
+                    cached["result"] = saved.get("result")
+                cache_job_state(cached)
+        return cached
+    saved = db_get_interaction(job_id)
+    if saved:
+        cache_job_state(saved)
+        return saved
+    with JOBS_LOCK:
+        job = JOBS.get(job_id)
+        return dict(job) if job else None
+
+
+def db_list_interactions(limit: int = 80, kind: str = "", include_full: bool = False) -> list[dict[str, Any]]:
+    """List interactions. By default selects only lightweight columns for fast listing.
+    Set include_full=True to also fetch input_json, output_json, logs_json (slow over network).
+    """
+    limit = max(1, min(int(limit), 250))
+    kind = kind.strip()
+
+    if include_full:
+        cols = "*"
+    else:
+        # Only fetch lightweight columns — skip logs_json, input_json, output_json
+        # which can be very large and slow to transfer from Supabase
+        cols = "id, kind, title, status, result_text, error, run_dir, profile_path, returncode, pid, created_at, started_at, finished_at, updated_at"
+
+    with db_session() as db:
+        if kind:
+            if kind == "geo":
+                rows = db.execute(
+                    f"SELECT {cols} FROM interactions WHERE kind = ? AND status != ? ORDER BY created_at DESC, id DESC LIMIT ?",
+                    (kind, "queued", limit),
+                ).fetchall()
+            else:
+                rows = db.execute(
+                    f"SELECT {cols} FROM interactions WHERE kind = ? ORDER BY created_at DESC, id DESC LIMIT ?",
+                    (kind, limit),
+                ).fetchall()
+        else:
+            rows = db.execute(
+                f"SELECT {cols} FROM interactions ORDER BY created_at DESC, id DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+    return [interaction_from_row(row, include_logs=False, lightweight=not include_full) for row in rows]
+
+
+def db_list_interactions_by_kinds(kinds: list[str], limit: int = 80) -> list[dict[str, Any]]:
+    """Efficiently list interactions filtered to specific kinds with input_json and output_json.
+    Uses a single DB query with WHERE kind IN (...) instead of fetching all and filtering in Python.
+    """
+    if not kinds:
+        return []
+    limit = max(1, min(int(limit), 250))
+    # Lightweight columns plus input_json and output_json for memory endpoint
+    cols = "id, kind, title, status, input_json, output_json, result_text, error, run_dir, profile_path, returncode, pid, created_at, started_at, finished_at, updated_at"
+    placeholders = ", ".join(["?"] * len(kinds))
+    with db_session() as db:
+        rows = db.execute(
+            f"SELECT {cols} FROM interactions WHERE kind IN ({placeholders}) ORDER BY created_at DESC, id DESC LIMIT ?",
+            (*kinds, limit),
+        ).fetchall()
+    return [interaction_from_row(row, include_logs=False, lightweight=False) for row in rows]
+
+
+def interaction_from_row(row, include_logs: bool = True, lightweight: bool = False) -> dict[str, Any]:
+    item = {
+        "id": row["id"],
+        "kind": row["kind"],
+        "title": row["title"],
+        "status": row["status"],
+        "created_at": row["created_at"],
+        "started_at": row["started_at"],
+        "finished_at": row["finished_at"],
+        "updated_at": row["updated_at"],
+        "result_text": row["result_text"],
+        "error": row["error"],
+        "run_dir": row["run_dir"],
+        "profile_path": row["profile_path"],
+        "returncode": row["returncode"],
+        "pid": row["pid"],
+    }
+    if lightweight:
+        # When listing, we don't have the JSON columns — return empty defaults
+        item["input"] = {}
+        item["result"] = {}
+        item["command"] = []
+    else:
+        item["input"] = from_json(row["input_json"], {})
+        item["result"] = from_json(row["output_json"], {})
+        item["command"] = from_json(row["command_json"], []) if "command_json" in (row.keys() if hasattr(row, 'keys') else []) else []
+    if item["kind"] == "research":
+        result = item["result"] if isinstance(item.get("result"), dict) else {}
+        if item["result_text"] and not result.get("text"):
+            result["text"] = item["result_text"]
+        if item["profile_path"] and not result.get("path"):
+            result["path"] = item["profile_path"]
+        item["result"] = result
+    if include_logs:
+        item["logs"] = from_json(row["logs_json"], []) if "logs_json" in (row.keys() if hasattr(row, 'keys') else []) else []
+    return item
+
+
+# =====================================================================
+# Jobs Management & Background Runners Section
+# =====================================================================
+
+def new_job(kind: str, title: str, input_payload: dict[str, Any] | None = None) -> str:
+    job_id = f"{time.strftime('%Y%m%d%H%M%S')}-{uuid.uuid4().hex[:8]}"
+    with JOBS_LOCK:
+        JOBS[job_id] = {
+            "id": job_id,
+            "kind": kind,
+            "title": title,
+            "status": "queued",
+            "created_at": now(),
+            "started_at": "",
+            "finished_at": "",
+            "input": input_payload or {},
+            "logs": [],
+            "result": None,
+            "error": "",
+        }
+        job = dict(JOBS[job_id])
+    db_insert_interaction(job, input_payload)
+    cache_job_state(job)
+    return job_id
+
+
+def update_job(job_id: str, **changes: Any) -> None:
+    db_changes: dict[str, Any] = {}
+    job_for_cache: dict[str, Any] | None = None
+    with JOBS_LOCK:
+        job = JOBS.get(job_id)
+        if not job:
+            cached = get_cached_job_state(job_id) or db_get_interaction(job_id)
+            if cached:
+                cached.update(changes)
+                job_for_cache = cached
+                db_insert_interaction(job_for_cache, job_for_cache.get("input") if isinstance(job_for_cache.get("input"), dict) else {})
+            else:
+                db_update_interaction(job_id, **changes)
+            cache_job_state(job_for_cache)
+            return
+        job.update(changes)
+        db_changes = {key: job.get(key) for key in changes}
+        job_for_cache = dict(job)
+    if job_for_cache:
+        db_insert_interaction(job_for_cache, job_for_cache.get("input") if isinstance(job_for_cache.get("input"), dict) else {})
+    else:
+        db_update_interaction(job_id, **db_changes)
+    cache_job_state(job_for_cache)
+
+
+def append_log(job_id: str, line: str) -> None:
+    with JOBS_LOCK:
+        job = JOBS.get(job_id)
+        if not job:
+            saved = get_cached_job_state(job_id) or db_get_interaction(job_id)
+            logs = list(saved.get("logs") or []) if saved else []
+            logs.append(line)
+            if len(logs) > 2500:
+                logs = logs[-2500:]
+            run_dir = str(saved.get("run_dir") or "") if saved else ""
+            match = re.search(r"(?:Run folder|Everything is in):\s*(.+)", line)
+            if match:
+                run_dir = match.group(1).strip()
+            db_update_interaction(job_id, logs=logs, run_dir=run_dir)
+            if saved:
+                saved["logs"] = logs
+                saved["run_dir"] = run_dir
+                cache_job_state(saved)
+            return
+        job["logs"].append(line)
+        if len(job["logs"]) > 2500:
+            job["logs"] = job["logs"][-2500:]
+
+        match = re.search(r"(?:Run folder|Everything is in):\s*(.+)", line)
+        if match:
+            job["run_dir"] = match.group(1).strip()
+        logs = list(job["logs"])
+        run_dir = job.get("run_dir", "")
+        cached_job = dict(job)
+    db_update_interaction(job_id, logs=logs, run_dir=run_dir)
+    cache_job_state(cached_job)
+
+
+def current_job_status(job_id: str) -> str:
+    cached = get_cached_job_state(job_id)
+    if cached:
+        return str(cached.get("status") or "")
+    with JOBS_LOCK:
+        job = JOBS.get(job_id)
+        if job:
+            return str(job.get("status") or "")
+    saved = db_get_interaction(job_id)
+    return str(saved.get("status") or "") if saved else ""
+
+
+def stop_process_tree(pid: int) -> None:
+    if os.name == "nt":
+        subprocess.run(["taskkill", "/PID", str(pid), "/T", "/F"], capture_output=True, text=True)
+    else:
+        try:
+            os.kill(pid, 15)
+        except ProcessLookupError:
+            pass
+
+
+def build_search_query(card_data: dict[str, Any]) -> str:
+    person = card_data.get("person") or {}
+    company = card_data.get("company") or {}
+    address = company.get("address") or {}
+    parts = [
+        person.get("first_name"),
+        person.get("last_name"),
+        person.get("job_title"),
+        company.get("company_name"),
+        address.get("city") or address.get("full_address"),
+    ]
+    return " ".join(str(part).strip() for part in parts if str(part or "").strip())
+
+
+def clean_int(value: Any, default: int, lower: int, upper: int) -> int:
+    try:
+        number = int(value)
+    except (TypeError, ValueError):
+        return default
+    return max(lower, min(upper, number))
+
+
+def absorb_env() -> dict[str, str]:
+    env = os.environ.copy()
+    for path in (ROOT / ".env", RESEARCH_DIR / ".env"):
+        if not path.exists():
+            continue
+        for raw_line in path.read_text(encoding="utf-8-sig", errors="replace").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            key = key.strip().lstrip("\ufeff")
+            value = value.strip().strip('"').strip("'")
+            if key:
+                env.setdefault(key, value)
+    return env
+
+
+def safe_read_text(path: Path, max_chars: int = 250_000) -> str:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if len(text) > max_chars:
+        return text[:max_chars] + "\n\n[Output truncated in UI.]"
+    return text
+
+
+def get_base_company_context() -> str:
+    if not BASE_COMPANY_CONTEXT_PATH.exists():
+        return ""
+    return safe_read_text(BASE_COMPANY_CONTEXT_PATH, max_chars=120_000).strip()
+
+
+def save_base_company_context(content: str) -> dict[str, Any]:
+    cleaned = str(content or "").strip()
+    if not cleaned:
+        raise ValueError("Base company context cannot be empty.")
+    SETTINGS_DIR.mkdir(parents=True, exist_ok=True)
+    BASE_COMPANY_CONTEXT_PATH.write_text(cleaned + "\n", encoding="utf-8")
+    stat = BASE_COMPANY_CONTEXT_PATH.stat()
+    return {
+        "configured": True,
+        "path": str(BASE_COMPANY_CONTEXT_PATH),
+        "filename": BASE_COMPANY_CONTEXT_PATH.name,
+        "size": stat.st_size,
+        "updated_at": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(stat.st_mtime)),
+    }
+
+
+def base_company_context_status(include_content: bool = False) -> dict[str, Any]:
+    if not BASE_COMPANY_CONTEXT_PATH.exists():
+        return {
+            "configured": False,
+            "path": str(BASE_COMPANY_CONTEXT_PATH),
+            "filename": BASE_COMPANY_CONTEXT_PATH.name,
+            "size": 0,
+            "updated_at": "",
+            "content": "" if include_content else None,
+        }
+    stat = BASE_COMPANY_CONTEXT_PATH.stat()
+    content = get_base_company_context() if include_content else ""
+    return {
+        "configured": bool(content if include_content else stat.st_size),
+        "path": str(BASE_COMPANY_CONTEXT_PATH),
+        "filename": BASE_COMPANY_CONTEXT_PATH.name,
+        "size": stat.st_size,
+        "updated_at": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(stat.st_mtime)),
+        "content": content if include_content else None,
+    }
+
+
+def is_usable_profile_text(text: str) -> bool:
+    stripped = text.strip()
+    if not stripped:
+        return False
+    lowered = stripped.lower()
+    unusable_prefixes = (
+        "gemini enrichment failed",
+        "gemini enrichment skipped",
+        "gemini enrichment returned an empty response",
+    )
+    return not lowered.startswith(unusable_prefixes)
+
+
+def safe_read_profile(path: Path, max_chars: int = 250_000) -> str:
+    text = safe_read_text(path, max_chars=max_chars)
+    return text if is_usable_profile_text(text) else ""
+
+
+def resolve_project_file(raw_path: str) -> Path:
+    path = Path(raw_path)
+    if not path.is_absolute():
+        path = ROOT / path
+    resolved = path.resolve()
+    root = ROOT.resolve()
+    if os.path.commonpath([str(root), str(resolved)]) != str(root):
+        raise ValueError("Path is outside this project.")
+    if not resolved.exists() or not resolved.is_file():
+        raise FileNotFoundError("Profile not found.")
+    return resolved
+
+
+def fallback_profile_path(path: Path) -> Path:
+    if path.name == "final_integrated_company_profile_gemini_enriched.txt":
+        fallback = path.with_name("final_integrated_company_profile.txt")
+        if fallback.exists() and safe_read_profile(fallback):
+            return fallback
+    return path
+
+
+def find_final_profile(run_dir: str | Path | None) -> dict[str, str]:
+    if not run_dir:
+        return {"path": "", "text": ""}
+
+    base = Path(str(run_dir))
+    if not base.is_absolute():
+        base = ROOT / base
+    if not base.exists():
+        return {"path": str(base), "text": ""}
+
+    candidates = [
+        *sorted(base.glob("*_profile.md"), key=lambda path: path.stat().st_mtime, reverse=True),
+        *sorted(base.glob("*_profile.txt"), key=lambda path: path.stat().st_mtime, reverse=True),
+        base / "final_integrated_company_profile_gemini_enriched.txt",
+        base / "final_integrated_company_profile.txt",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            text = safe_read_profile(candidate)
+            if text:
+                return {"path": str(candidate), "text": text}
+    return {"path": str(base), "text": ""}
+
+
+def list_profiles() -> list[dict[str, Any]]:
+    profiles: list[dict[str, Any]] = []
+    if not RESEARCH_OUTPUT_DIR.exists():
+        return profiles
+
+    candidate_paths = [
+        *RESEARCH_OUTPUT_DIR.glob("*_profile.md"),
+        *RESEARCH_OUTPUT_DIR.glob("*_profile.txt"),
+        *RESEARCH_OUTPUT_DIR.glob("*/*_profile.md"),
+        *RESEARCH_OUTPUT_DIR.glob("*/*_profile.txt"),
+        *RESEARCH_OUTPUT_DIR.glob("*/final_integrated_company_profile*.txt"),
+    ]
+    for path in candidate_paths:
+        if not safe_read_profile(path, max_chars=4096):
+            continue
+        stat = path.stat()
+        profiles.append(
+            {
+                "name": path.stem if path.parent == RESEARCH_OUTPUT_DIR else path.parent.name,
+                "file": path.name,
+                "path": str(path),
+                "modified": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(stat.st_mtime)),
+                "size": stat.st_size,
+            }
+        )
+    return sorted(profiles, key=lambda item: item["modified"], reverse=True)[:40]
+
+
+def run_geo_job(job_id: str, query: str) -> None:
+    if current_job_status(job_id) == "canceled":
+        append_log(job_id, "Regional Prospecting was stopped before the pipeline started.")
+        return
+    update_job(job_id, status="running", started_at=now())
+    append_log(job_id, "Starting geo-based company finder and ranker.")
+    try:
+        from services.geo_search import run_pipeline as run_geo_pipeline
+        from services.geo_search import run_pipeline_streaming as run_geo_pipeline_streaming
+        from services.export_service import parse_geo_companies, parse_geo_companies_from_stages
+
+        stages: list[dict[str, Any]] = []
+        maps_sources: list[dict[str, Any]] = []
+        final_ranking = ""
+        fallback_notice = ""
+
+        for event in run_geo_pipeline_streaming(query):
+            if current_job_status(job_id) == "canceled":
+                append_log(job_id, "Regional Prospecting pipeline was stopped by user.")
+                return
+            stages.append(event)
+            step = str(event.get("step") or "")
+            step_names = {
+                "input_parsed": "Input parsed",
+                "maps_done": "Fetching maps",
+                "search_done": "Fetching internet",
+                "checker_done": "Verifying",
+                "url_verify_done": "Verifying URLs",
+                "judge_done": "Ranking"
+            }
+            display_name = step_names.get(step, step)
+            append_log(job_id, f"{display_name}...")
+            if step == "maps_done":
+                maps_sources = event.get("maps_sources") or []
+            elif step == "judge_done":
+                final_ranking = str(event.get("data") or "")
+            ranked_companies = parse_geo_companies(final_ranking)
+            fallback_companies = []
+            if final_ranking and not ranked_companies:
+                fallback_companies = parse_geo_companies_from_stages(stages)
+                if fallback_companies:
+                    fallback_notice = "Ranking was not available, so these discovered companies are shown unranked."
+            update_job(
+                job_id,
+                result={
+                    "result": final_ranking or str(event.get("data") or ""),
+                    "stages": stages,
+                    "maps_sources": maps_sources,
+                    "companies": ranked_companies or fallback_companies,
+                    "ranking_unavailable": bool(fallback_companies and not ranked_companies),
+                    "notice": fallback_notice,
+                },
+            )
+
+        if current_job_status(job_id) == "canceled":
+            append_log(job_id, "Regional Prospecting pipeline was stopped by user.")
+            return
+
+        if not final_ranking:
+            output = run_geo_pipeline(query)
+            if current_job_status(job_id) == "canceled":
+                append_log(job_id, "Regional Prospecting pipeline was stopped by user.")
+                return
+            final_ranking = str(output.get("result") or "")
+            maps_sources = output.get("maps_sources") or maps_sources
+
+        ranked_companies = parse_geo_companies(final_ranking)
+        fallback_companies = []
+        if final_ranking and not ranked_companies:
+            fallback_companies = parse_geo_companies_from_stages(stages)
+            if fallback_companies:
+                fallback_notice = "Ranking was not available, so these discovered companies are shown unranked."
+                append_log(job_id, fallback_notice)
+
+        update_job(
+            job_id,
+            status="completed",
+            finished_at=now(),
+            result={
+                "result": final_ranking,
+                "companies": ranked_companies or fallback_companies,
+                "maps_sources": maps_sources,
+                "stages": stages,
+                "ranking_unavailable": bool(fallback_companies and not ranked_companies),
+                "notice": fallback_notice,
+            },
+        )
+        append_log(job_id, "Geo ranking completed.")
+    except Exception as exc:
+        if current_job_status(job_id) == "canceled":
+            append_log(job_id, "Regional Prospecting pipeline was stopped by user.")
+            return
+        update_job(job_id, status="failed", finished_at=now(), error=str(exc))
+        append_log(job_id, f"Geo ranking failed: {type(exc).__name__}: {exc}")
+
+
+def run_company_research_job(job_id: str, payload: dict[str, Any]) -> None:
+    company = str(payload.get("company") or "").strip()
+    base_company_md = get_base_company_context()
+    company_md = str(payload.get("company_md") or "").strip()
+    if not base_company_md:
+        update_job(
+            job_id,
+            status="failed",
+            finished_at=now(),
+            returncode=1,
+            error="Base company context is required before running Company Research.",
+        )
+        append_log(job_id, "Missing base company context. Configure it in Settings before running Company Research.")
+        return
+    if not company_md:
+        company_md = base_company_md
+    quality_mode = str(payload.get("quality_mode") or "balanced").strip().lower()
+    default_prompts = 10 if quality_mode == "deep" else 8
+    default_results = 5 if quality_mode == "deep" else 4
+    is_azure = bool(os.environ.get("CONTAINER_APP_NAME") or os.environ.get("WEBSITE_SITE_NAME"))
+    default_parallel = 2 if is_azure else (4 if quality_mode == "deep" else 6)
+    max_parallel_default = 2 if is_azure else 6
+    max_parallel = clean_int(
+        os.environ.get("COMPANY_EXTRACTOR_MAX_PARALLEL_SEARCHES"),
+        max_parallel_default,
+        1,
+        6,
+    )
+    max_prompts = clean_int(payload.get("max_prompts"), default_prompts, 1, 12)
+    max_results = clean_int(payload.get("max_results_per_prompt"), default_results, 1, 10)
+    parallel_searches = clean_int(payload.get("parallel_searches"), default_parallel, 1, max_parallel)
+    job_output_dir = RESEARCH_OUTPUT_DIR / job_id
+    job_output_dir.mkdir(parents=True, exist_ok=True)
+    company_md_path = Path("company.md")
+    if company_md:
+        try:
+            company_md_path = job_output_dir / "company.md"
+            company_md_path.write_text(company_md + "\n", encoding="utf-8")
+        except Exception as exc:
+            update_job(job_id, status="failed", finished_at=now(), returncode=1, error=str(exc))
+            append_log(job_id, f"Could not write company.md: {type(exc).__name__}: {exc}")
+            return
+
+    command = [
+        sys.executable,
+        str(PIPELINE_SCRIPT),
+        "--company",
+        str(company_md_path),
+        "--client-company",
+        company,
+        "--questions",
+        "questionlist.md",
+        "--out-dir",
+        str(job_output_dir),
+        "--num-queries",
+        str(max_prompts),
+        "--results-per-query",
+        str(max_results),
+        "--min-delay",
+        "0",
+        "--max-delay",
+        "0",
+        "--parallel-searches",
+        str(parallel_searches),
+    ]
+
+    if current_job_status(job_id) == "canceled":
+        append_log(job_id, "Company research was stopped before the pipeline started.")
+        return
+
+    update_job(job_id, status="running", started_at=now(), command=command, run_dir=str(job_output_dir))
+    append_log(job_id, "Starting company information extraction pipeline.")
+    append_log(
+        job_id,
+        f"Research mode: {quality_mode or 'balanced'} "
+        f"({max_prompts} queries, {max_results} results/query, {parallel_searches} parallel searches)."
+    )
+    if company_md:
+        append_log(job_id, f"Using uploaded company.md: {company_md_path}")
+    else:
+        append_log(job_id, "Using default company.md from research folder.")
+    append_log(job_id, "Command: " + " ".join(command))
+
+    try:
+        process = subprocess.Popen(
+            command,
+            cwd=RESEARCH_DIR,
+            env=absorb_env(),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            bufsize=1,
+        )
+        update_job(job_id, pid=process.pid)
+
+        assert process.stdout is not None
+        for line in process.stdout:
+            append_log(job_id, line.rstrip())
+
+        returncode = process.wait()
+        if current_job_status(job_id) == "canceled":
+            update_job(job_id, finished_at=now(), returncode=returncode)
+            append_log(job_id, "Company research process was stopped by user.")
+            return
+
+        cached_job = get_cached_job_state(job_id)
+        run_dir = str(cached_job.get("run_dir") or "") if cached_job else ""
+        if not run_dir:
+            with JOBS_LOCK:
+                run_dir = str(JOBS.get(job_id, {}).get("run_dir") or "")
+        if not run_dir:
+            saved_job = db_get_interaction(job_id)
+            run_dir = str(saved_job.get("run_dir") or "") if saved_job else ""
+        if not run_dir:
+            run_dir = str(job_output_dir)
+
+        result = find_final_profile(run_dir)
+        profile_missing = returncode == 0 and not str(result.get("text") or "").strip()
+        if profile_missing:
+            append_log(job_id, f"No usable profile was found in: {run_dir}")
+        elif returncode == 0:
+            profile_path = str(result.get("path") or "")
+            append_log(job_id, f"Company profile ready: {profile_path or run_dir}")
+        update_job(
+            job_id,
+            status="completed" if returncode == 0 and not profile_missing else "failed",
+            finished_at=now(),
+            returncode=returncode,
+            result=result,
+            error=(
+                ""
+                if returncode == 0 and not profile_missing
+                else "Pipeline completed but no usable profile was generated."
+                if profile_missing
+                else f"Pipeline exited with code {returncode}."
+            ),
+        )
+    except Exception as exc:
+        if current_job_status(job_id) == "canceled":
+            update_job(job_id, finished_at=now(), returncode=1)
+            append_log(job_id, "Company research process was stopped by user.")
+            return
+        update_job(job_id, status="failed", finished_at=now(), returncode=1, error=str(exc))
+        append_log(job_id, f"Company research failed: {type(exc).__name__}: {exc}")
+
+
+# Initialize interactions database
+init_database()
+try:
+    db_prune_geo_history(20)
+except Exception as exc:
+    print(f"Geo history cleanup failed: {exc}")

services/export_service.py

@@ -0,0 +1,1317 @@
+from __future__ import annotations
+
+import json
+import re
+import zipfile
+from io import BytesIO
+from pathlib import Path
+from typing import Any
+from xml.sax.saxutils import escape as xml_escape
+
+
+# =====================================================================
+# General Markdown & Text Helpers
+# =====================================================================
+
+def clean_markdown_text(value: str) -> str:
+    value = re.sub(r"^\s{0,3}#{1,6}\s*", "", value)
+    value = re.sub(r"^\s*(?:[-*+]\s+|\d+[.)]\s+)", "", value)
+    value = value.replace("**", "").replace("__", "").replace("`", "")
+    return value.strip()
+
+
+def strip_inline_markdown(value: str) -> str:
+    text = str(value or "")
+    text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r"\1 (\2)", text)
+    text = text.replace("**", "").replace("__", "").replace("`", "")
+    return text.strip()
+
+
+# =====================================================================
+# Excel Generation Utilities
+# =====================================================================
+
+def split_geo_detail_fields(value: str) -> dict[str, str]:
+    details: dict[str, str] = {}
+    for part in re.split(r";\s*", value):
+        if not part.strip() or ":" not in part:
+            continue
+        key, detail = part.split(":", 1)
+        key = clean_markdown_text(key)
+        detail = clean_markdown_text(detail)
+        if key and detail:
+            details[key] = detail
+    return details
+
+
+def parse_geo_companies(text: str) -> list[dict[str, Any]]:
+    companies: list[dict[str, Any]] = []
+    current: dict[str, Any] | None = None
+    active_field = ""
+
+    title_patterns = [
+        re.compile(r"^\s*(?:#{1,6}\s*)?(?:\*\*)?\s*(?:Rank\s*)?#?\s*(\d+)[.)]\s*(.+?)(?:\*\*)?\s*$", re.I),
+        re.compile(r"^\s*(?:\*\*)?\s*Company\s+Name\s*:\s*(.+?)(?:\*\*)?\s*$", re.I),
+    ]
+
+    def finish_current() -> None:
+        if current and (current.get("company_name") or current.get("fields")):
+            details = current.get("fields", {}).get("All available details", "")
+            if details:
+                current["details"] = split_geo_detail_fields(details)
+            companies.append(current)
+
+    for raw_line in text.splitlines():
+        line = re.sub(r"^\s{0,3}#{1,6}\s*", "", raw_line)
+        line = line.replace("**", "").replace("__", "").replace("`", "").strip()
+        line = re.sub(r"^\s*[-*+]\s+", "", line).strip()
+        if not line or set(line) <= {"-", "=", "_"}:
+            continue
+        if line.lower().startswith(("here are ", "ranking logic", "summary", "why #1")):
+            active_field = ""
+            continue
+
+        if re.match(r"^[A-Za-z][A-Za-z0-9 /&().,'-]{1,64}\s*:\s*$", line):
+            active_field = ""
+            continue
+
+        title_match = None
+        for pattern in title_patterns:
+            title_match = pattern.match(line)
+            if title_match:
+                break
+
+        if title_match:
+            groups = title_match.groups()
+            if len(groups) == 2:
+                rank = groups[0]
+                name = groups[1]
+            else:
+                rank = str(len(companies) + 1)
+                name = groups[0]
+            name = re.sub(r"\s*\|\s*Match score:.*$", "", name, flags=re.I).strip()
+            
+            # Skip if matched title is actually an explanation summary row
+            explanation_keywords = [
+                "is ranked", "are ranked", "was ranked", "ranked highest", 
+                "ranked second", "ranked third", "ranked fourth", "ranked fifth",
+                "ranked last", "because it", "is second due to", "is third due to",
+                "is fourth due to"
+            ]
+            if any(kw in name.lower() for kw in explanation_keywords):
+                finish_current()
+                current = None
+                active_field = ""
+                continue
+                
+            # Skip if company is already added (deduplication)
+            clean_name = re.sub(r",?\s*Match score:.*$", "", name, flags=re.I).strip().lower()
+            existing_names = [c["company_name"].lower() for c in companies]
+            if clean_name in existing_names or any(clean_name in n or n in clean_name for n in existing_names):
+                finish_current()
+                current = None
+                active_field = ""
+                continue
+
+            finish_current()
+            current = {"rank": int(rank), "company_name": name, "fields": {}}
+            active_field = ""
+            score_match = re.search(r"Match score:\s*([^|]+)", line, re.I)
+            if score_match:
+                current["fields"]["Match score"] = score_match.group(1).strip()
+            continue
+
+        field_match = re.match(r"^([A-Za-z][A-Za-z0-9 /&().,'-]{1,64})\s*:\s*(.+)$", line)
+        if field_match:
+            if current is None:
+                current = {"rank": len(companies) + 1, "company_name": "", "fields": {}}
+            key = clean_markdown_text(field_match.group(1))
+            value = clean_markdown_text(field_match.group(2))
+            if key.lower() in {"business name", "company", "name"}:
+                if current.get("company_name") or current.get("fields"):
+                    finish_current()
+                    current = {"rank": len(companies) + 1, "company_name": "", "fields": {}}
+                current["company_name"] = value
+                active_field = ""
+                continue
+            current["fields"][key] = value
+            active_field = key
+            continue
+
+        if current is not None and active_field:
+            current["fields"][active_field] = f"{current['fields'].get(active_field, '')} {line}".strip()
+
+    finish_current()
+    return companies
+
+
+def parse_geo_companies_from_stages(stages: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    if not stages:
+        return []
+
+    preferred_steps = ["url_verify_done", "checker_done", "maps_done", "search_done"]
+    by_step = {str(stage.get("step") or ""): stage for stage in stages if isinstance(stage, dict)}
+
+    for step in preferred_steps:
+        stage = by_step.get(step)
+        if not stage:
+            continue
+        companies = parse_geo_companies(str(stage.get("data") or ""))
+        if companies:
+            for index, company in enumerate(companies, start=1):
+                company["rank"] = company.get("rank") or index
+                fields = company.setdefault("fields", {})
+                fields.setdefault("Ranking status", "Unranked - ranking AI did not return a usable ranked list.")
+            return companies
+    return []
+
+
+def detail_value(company: dict[str, Any], names: list[str]) -> str:
+    fields = company.get("fields") if isinstance(company.get("fields"), dict) else {}
+    details = company.get("details") if isinstance(company.get("details"), dict) else {}
+    lookup = {str(key).lower(): value for source in (fields, details) for key, value in source.items()}
+    for name in names:
+        value = fields.get(name) or details.get(name) or lookup.get(name.lower())
+        if value:
+            return str(value)
+    return ""
+
+
+def clean_excel_value(value: Any) -> str:
+    text = clean_markdown_text(str(value or ""))
+    text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r"\2", text)
+    text = re.sub(r"\s+Details:\s*$", "", text, flags=re.I)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def geo_export_tables(job: dict[str, Any]) -> dict[str, Any]:
+    result = job.get("result") if isinstance(job.get("result"), dict) else {}
+    companies = result.get("companies") if isinstance(result.get("companies"), list) else []
+    raw_ranking = str(result.get("result") or "")
+    if not companies and raw_ranking:
+        companies = parse_geo_companies(raw_ranking)
+    if not companies:
+        raise ValueError("No parsed company details are available for this Geo run.")
+
+    has_detailed_companies = any(company.get("fields") or company.get("details") for company in companies)
+    if has_detailed_companies:
+        richest_by_name: dict[str, dict[str, Any]] = {}
+        for company in companies:
+            name_key = str(company.get("company_name") or "").strip().lower()
+            detail_count = len(company.get("fields") or {}) + len(company.get("details") or {})
+            if not name_key or detail_count == 0:
+                continue
+            previous = richest_by_name.get(name_key)
+            previous_count = len(previous.get("fields") or {}) + len(previous.get("details") or {}) if previous else -1
+            if previous is None or detail_count > previous_count:
+                richest_by_name[name_key] = company
+        companies = sorted(richest_by_name.values(), key=lambda company: int(company.get("rank") or 9999))
+
+    def standardize_na(val: Any) -> str:
+        s = str(val or "").strip()
+        if not s:
+            return "N/A"
+        lower_s = s.lower()
+        if lower_s == "n/a" or lower_s == "not found":
+            return "N/A"
+        if "unresolvable" in lower_s or "dead link" in lower_s or "removed" in lower_s:
+            return "N/A"
+        if "not directly listed" in lower_s or "available" in lower_s:
+            return "N/A"
+        return s
+
+    def get_geo_contact(company: dict, want_type: str) -> str:
+        raw_phone = str(detail_value(company, ["Phone number", "Phone", "Contact"]) or "N/A")
+        raw_email = str(detail_value(company, ["Email address", "Email"]) or "N/A")
+        if raw_phone != "N/A" and raw_email == "N/A" and "@" in raw_phone:
+            email_pattern = r'([a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+)'
+            emails = re.findall(email_pattern, raw_phone)
+            if emails:
+                raw_email = ", ".join(emails)
+                for e in emails:
+                    raw_phone = raw_phone.replace(e, "")
+                raw_phone = re.sub(r',\s*', ' ', raw_phone)
+                raw_phone = re.sub(r'\s+', ' ', raw_phone).strip()
+                if not raw_phone or raw_phone.lower() == "not found" or raw_phone == ",":
+                    raw_phone = "N/A"
+        return standardize_na(raw_email if want_type == "email" else raw_phone)
+
+    preferred_columns = [
+        ("Rank", lambda company: company.get("rank", "")),
+        ("Company Name", lambda company: company.get("company_name", "")),
+        ("Key Reason", lambda company: detail_value(company, ["Key reason"])),
+        ("Website", lambda company: standardize_na(detail_value(company, ["Website", "Website URL"]))),
+        ("Address", lambda company: detail_value(company, ["Full address", "Address"])),
+        ("Category", lambda company: detail_value(company, ["Category", "Category / type", "Industry / sector", "Industry"])),
+        ("Phone", lambda company: get_geo_contact(company, "phone")),
+        ("Email", lambda company: get_geo_contact(company, "email")),
+        ("Location Label", lambda company: detail_value(company, ["Verification", "Location label", "Location"])),
+    ]
+    preferred_names = {name for name, _ in preferred_columns}
+
+    mapped_or_dropped_keys = {
+        "rank", "company_name", "key reason", "website", "website url", 
+        "full address", "address", "category", "category / type", 
+        "industry / sector", "industry", "google maps rating and review count", 
+        "google maps rating", "rating", "phone number", "phone", "contact", 
+        "email address", "email", "verification", "location label", "location", 
+        "legitimacy label", "legitimacy", "all available details"
+    }
+
+    extra_field_names: list[str] = []
+    for company in companies:
+        fields = company.get("fields") if isinstance(company.get("fields"), dict) else {}
+        details = company.get("details") if isinstance(company.get("details"), dict) else {}
+        for name in list(fields) + list(details):
+            if name.lower() not in mapped_or_dropped_keys and name not in extra_field_names:
+                extra_field_names.append(name)
+
+    headers = [name for name, _getter in preferred_columns] + extra_field_names
+    company_rows: list[list[Any]] = []
+    for company in companies:
+        fields = company.get("fields") if isinstance(company.get("fields"), dict) else {}
+        details = company.get("details") if isinstance(company.get("details"), dict) else {}
+        row = [clean_excel_value(getter(company)) for _name, getter in preferred_columns]
+        row.extend(clean_excel_value(fields.get(name) or details.get(name) or "") for name in extra_field_names)
+        company_rows.append(row)
+
+    source_rows = [
+        [clean_excel_value(source.get("title", "")), clean_excel_value(source.get("uri", "") or source.get("url", ""))]
+        for source in result.get("maps_sources") or []
+        if isinstance(source, dict)
+    ]
+    raw_rows = [
+        ["Query", clean_excel_value(job.get("title", ""))],
+        ["Job ID", job.get("id", "")],
+        ["Created", job.get("created_at", "")],
+        [],
+        ["Raw Ranking Output"],
+        [raw_ranking],
+    ]
+    return {
+        "headers": headers,
+        "company_rows": company_rows,
+        "source_rows": source_rows,
+        "raw_rows": raw_rows,
+    }
+
+
+def build_geo_excel(job: dict[str, Any]) -> BytesIO:
+    tables = geo_export_tables(job)
+    try:
+        from openpyxl import Workbook
+        from openpyxl.styles import Alignment, Font, PatternFill
+        from openpyxl.utils import get_column_letter
+    except ImportError:
+        return build_geo_excel_basic(tables)
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Companies"
+    header_fill = PatternFill("solid", fgColor="101820")
+    header_font = Font(color="FFFFFF", bold=True)
+
+    headers = tables["headers"]
+    ws.append(headers)
+    for cell in ws[1]:
+        cell.fill = header_fill
+        cell.font = header_font
+        cell.alignment = Alignment(vertical="center", wrap_text=True)
+
+    for row in tables["company_rows"]:
+        ws.append(row)
+
+    ws.freeze_panes = "A2"
+    ws.auto_filter.ref = ws.dimensions
+    for row in ws.iter_rows(min_row=2):
+        for cell in row:
+            cell.alignment = Alignment(vertical="top", wrap_text=True)
+
+    max_widths = {
+        "Company Name": 34,
+        "Key Reason": 60,
+        "Address": 52,
+        "All Available Details": 72,
+    }
+    for column_cells in ws.columns:
+        header = str(column_cells[0].value or "")
+        max_len = max(len(str(cell.value or "")) for cell in column_cells[: min(len(column_cells), 25)])
+        width = min(max(max_len + 2, 12), max_widths.get(header, 44))
+        ws.column_dimensions[get_column_letter(column_cells[0].column)].width = width
+
+    source_ws = wb.create_sheet("Sources")
+    source_ws.append(["Title", "URL"])
+    for cell in source_ws[1]:
+        cell.fill = header_fill
+        cell.font = header_font
+    for row in tables["source_rows"]:
+        source_ws.append(row)
+    source_ws.freeze_panes = "A2"
+    source_ws.column_dimensions["A"].width = 45
+    source_ws.column_dimensions["B"].width = 90
+
+    raw_ws = wb.create_sheet("Raw Ranking")
+    for row in tables["raw_rows"]:
+        raw_ws.append(row)
+    raw_ws["A6"].alignment = Alignment(vertical="top", wrap_text=True)
+    raw_ws.column_dimensions["A"].width = 24
+    raw_ws.column_dimensions["B"].width = 80
+    raw_ws.row_dimensions[6].height = 320
+    for cell in ("A1", "A2", "A3", "A5"):
+        raw_ws[cell].font = Font(bold=True)
+
+    output = BytesIO()
+    wb.save(output)
+    output.seek(0)
+    return output
+
+
+def xlsx_cell(value: Any) -> str:
+    clean_value = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", str(value or ""))
+    text = xml_escape(clean_value)
+    return f'<c t="inlineStr"><is><t xml:space="preserve">{text}</t></is></c>'
+
+
+def xlsx_sheet(rows: list[list[Any]]) -> str:
+    body: list[str] = []
+    for row_index, row in enumerate(rows, start=1):
+        cells = "".join(xlsx_cell(value) for value in row)
+        body.append(f'<row r="{row_index}">{cells}</row>')
+    return (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
+        '<sheetData>'
+        + "".join(body)
+        + "</sheetData></worksheet>"
+    )
+
+
+def build_geo_excel_basic(tables: dict[str, Any]) -> BytesIO:
+    sheets = [
+        ("Companies", [tables["headers"], *tables["company_rows"]]),
+        ("Sources", [["Title", "URL"], *tables["source_rows"]]),
+        ("Raw Ranking", tables["raw_rows"]),
+    ]
+    output = BytesIO()
+    with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr(
+            "[Content_Types].xml",
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+            '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
+            '<Default Extension="xml" ContentType="application/xml"/>'
+            '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>'
+            + "".join(
+                f'<Override PartName="/xl/worksheets/sheet{index}.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>'
+                for index in range(1, len(sheets) + 1)
+            )
+            + "</Types>",
+        )
+        zf.writestr(
+            "_rels/.rels",
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+            '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>'
+            "</Relationships>",
+        )
+        zf.writestr(
+            "xl/workbook.xml",
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" '
+            'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets>'
+            + "".join(
+                f'<sheet name="{xml_escape(name)}" sheetId="{index}" r:id="rId{index}"/>'
+                for index, (name, _rows) in enumerate(sheets, start=1)
+            )
+            + "</sheets></workbook>",
+        )
+        zf.writestr(
+            "xl/_rels/workbook.xml.rels",
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+            + "".join(
+                f'<Relationship Id="rId{index}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet{index}.xml"/>'
+                for index in range(1, len(sheets) + 1)
+            )
+            + "</Relationships>",
+        )
+        for index, (_name, rows) in enumerate(sheets, start=1):
+            zf.writestr(f"xl/worksheets/sheet{index}.xml", xlsx_sheet(rows))
+    output.seek(0)
+    return output
+
+
+# =====================================================================
+# PDF Generation Utilities (ReportLab)
+# =====================================================================
+
+def paragraph_text(value: Any) -> str:
+    text = xml_escape(str(value or ""))
+    return text.replace("\n", "<br/>")
+
+
+def profile_pdf_title(source_path: Path, profile_text: str = "") -> str:
+    for line in str(profile_text or "").splitlines():
+        match = re.match(r"^\s{0,3}#\s+(.+?)\s*$", line)
+        if match and "company profile" in match.group(1).lower():
+            return strip_inline_markdown(match.group(1).split(":", 1)[-1]).strip() or match.group(1).strip()
+    for line in str(profile_text or "").splitlines():
+        match = re.match(r"^\s{0,3}#\s+(.+?)\s*$", line)
+        if match:
+            return strip_inline_markdown(match.group(1)).strip()
+    name = source_path.parent.name or source_path.stem
+    return name.replace("_", " ").replace("-", " ").strip().title() or "Company Profile"
+
+
+def reportlab_inline_html(html: str) -> str:
+    try:
+        import warnings
+        from bs4 import BeautifulSoup, MarkupResemblesLocatorWarning, NavigableString
+    except ImportError as exc:
+        raise RuntimeError(f"PDF export requires beautifulsoup4: {exc}") from exc
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=MarkupResemblesLocatorWarning)
+        soup = BeautifulSoup(html or "", "html.parser")
+    for tag in list(soup.find_all(True)):
+        name = tag.name.lower()
+        if name in {"strong", "b"}:
+            tag.name = "b"
+        elif name in {"em", "i"}:
+            tag.name = "i"
+        elif name == "code":
+            tag.name = "font"
+            tag.attrs = {"face": "Courier"}
+        elif name == "br":
+            tag.attrs = {}
+        elif name == "a":
+            href = tag.get("href")
+            tag.attrs = {"href": href} if href else {}
+        elif name in {"span", "p"}:
+            tag.unwrap()
+        else:
+            tag.unwrap()
+
+    parts: list[str] = []
+    for child in soup.contents:
+        if isinstance(child, NavigableString):
+            parts.append(xml_escape(str(child)))
+        else:
+            parts.append(str(child))
+    return "".join(parts).strip()
+
+
+def markdown_inline_to_reportlab(text: str) -> str:
+    try:
+        import markdown
+    except ImportError as exc:
+        raise RuntimeError(f"PDF export requires markdown: {exc}") from exc
+
+    html = markdown.markdown(str(text or ""), extensions=["sane_lists"], output_format="html5")
+    html = re.sub(r"^\s*<p>|</p>\s*$", "", html.strip(), flags=re.I)
+    return reportlab_inline_html(html)
+
+
+def html_nodes_to_reportlab(nodes: Any) -> str:
+    return reportlab_inline_html("".join(str(node) for node in nodes))
+
+
+def strip_profile_line_prefix(line: str) -> str:
+    clean = strip_inline_markdown(line)
+    clean = re.sub(r"^\s{0,3}#{1,6}\s*", "", clean)
+    clean = re.sub(r"^\s*(?:[-*+]\s+|\d+[.)]\s+)", "", clean)
+    return clean.strip()
+
+
+def split_profile_field_line(line: str) -> dict[str, str] | None:
+    normalized = strip_profile_line_prefix(line)
+    if not normalized or normalized.startswith("|") or re.match(r"^https?://", normalized, flags=re.I):
+        return None
+    colon = normalized.find(":")
+    if colon <= 0 or colon > 70:
+        return None
+    label = normalized[:colon].strip()
+    if not re.match(r"^[A-Za-z][A-Za-z0-9 /&().,'-]{1,69}$", label):
+        return None
+    segments = [part.strip() for part in re.split(r"\s+\|\s+", normalized[colon + 1 :]) if part.strip()]
+    if not segments:
+        return None
+    return {"label": label, "value": segments[0], "meta": " | ".join(segments[1:])}
+
+
+def parse_profile_sections(text: str, fallback_title: str = "Company Profile") -> list[dict[str, Any]]:
+    sections: list[dict[str, Any]] = []
+    current: dict[str, Any] = {"title": fallback_title, "rows": [], "notes": []}
+
+    def push_current() -> None:
+        if current["rows"] or current["notes"]:
+            sections.append(current.copy())
+
+    for raw_line in str(text or "").splitlines():
+        trimmed = raw_line.strip()
+        if not trimmed:
+            continue
+        if set(trimmed) <= {"-", "=", "_"}:
+            continue
+        heading_match = re.match(r"^\s{0,3}#{1,6}\s+(.+)$", raw_line)
+        bold_heading_match = re.match(r"^\s*(?:[-*+]\s*)?\*\*#?\s*([^:*]{3,90})\s*\*\*\s*$", raw_line)
+        uppercase_heading = strip_profile_line_prefix(raw_line)
+        if heading_match or bold_heading_match or (uppercase_heading.isupper() and len(uppercase_heading) <= 90):
+            push_current()
+            title = heading_match.group(1) if heading_match else bold_heading_match.group(1) if bold_heading_match else uppercase_heading
+            current = {"title": strip_profile_line_prefix(title), "rows": [], "notes": []}
+            continue
+        field = split_profile_field_line(raw_line)
+        if field and field["value"]:
+            current["rows"].append(field)
+        else:
+            current["notes"].append(strip_profile_line_prefix(raw_line))
+
+    push_current()
+    return sections
+
+
+def normalize_profile_heading(value: str) -> str:
+    return strip_inline_markdown(value).strip().rstrip(":")
+
+
+def profile_bullet_content(raw_line: str) -> tuple[int, str] | None:
+    match = re.match(r"^(\s*)(?:[-*+]\s+|\d+[.)]\s+)(.+?)\s*$", raw_line)
+    if not match:
+        return None
+    return len(match.group(1).replace("\t", "    ")), match.group(2).strip()
+
+
+def split_structured_profile_field(content: str) -> dict[str, Any] | None:
+    cleaned = content.strip()
+    cleaned = re.sub(r"^\*\*(.+?)\*\*\s*:\s*", r"\1: ", cleaned)
+    cleaned = re.sub(r"^\*\*(.+?:)\*\*\s*", r"\1 ", cleaned)
+    match = re.match(r"^(.{2,72}?):\s*(.*)$", cleaned)
+    if not match:
+        return None
+    label = strip_inline_markdown(match.group(1)).strip()
+    value = match.group(2).strip()
+    if not label or re.search(r"[.!?]$", label):
+        return None
+    if not re.match(r"^[A-Za-z0-9][A-Za-z0-9 /&().,'+-]{1,72}$", label):
+        return None
+    return {"label": label, "value": value, "children": []}
+
+
+def parse_structured_profile(text: str, fallback_title: str) -> dict[str, Any] | None:
+    title = fallback_title
+    sections: list[dict[str, Any]] = []
+    current: dict[str, Any] | None = None
+    last_field: dict[str, Any] | None = None
+    saw_title = False
+
+    def push_section() -> None:
+        nonlocal current, last_field
+        if current and (current["fields"] or current["notes"]):
+            sections.append(current)
+        current = None
+        last_field = None
+
+    for raw_line in str(text or "").splitlines():
+        if not raw_line.strip() or set(raw_line.strip()) <= {"-", "=", "_"}:
+            continue
+
+        heading_match = re.match(r"^\s{0,3}(#{1,6})\s+(.+?)\s*$", raw_line)
+        if heading_match:
+            heading = normalize_profile_heading(heading_match.group(2))
+            if not saw_title:
+                title = heading or title
+                saw_title = True
+                continue
+            if heading.lower() == title.lower():
+                continue
+            push_section()
+            current = {"title": heading, "fields": [], "notes": []}
+            continue
+
+        bold_heading_match = re.match(r"^\s*(?:[-*+]\s*)?\*\*([^:*]{3,90})\*\*\s*$", raw_line)
+        if bold_heading_match:
+            push_section()
+            current = {"title": normalize_profile_heading(bold_heading_match.group(1)), "fields": [], "notes": []}
+            continue
+
+        if current is None:
+            current = {"title": title, "fields": [], "notes": []}
+
+        bullet = profile_bullet_content(raw_line)
+        if bullet:
+            indent, content = bullet
+            field = split_structured_profile_field(content)
+            if field and indent <= 3:
+                current["fields"].append(field)
+                last_field = field
+                continue
+            if indent > 3 and last_field is not None:
+                child_field = split_structured_profile_field(content)
+                if child_field and child_field.get("value"):
+                    last_field["children"].append(f"{child_field['label']}: {child_field['value']}")
+                else:
+                    last_field["children"].append(content)
+                continue
+            current["notes"].append(content)
+            continue
+
+        field = split_structured_profile_field(strip_profile_line_prefix(raw_line))
+        if field:
+            current["fields"].append(field)
+            last_field = field
+        elif last_field is not None and last_field.get("value"):
+            last_field["value"] = f"{last_field['value']} {raw_line.strip()}".strip()
+        else:
+            current["notes"].append(strip_profile_line_prefix(raw_line))
+
+    push_section()
+    field_count = sum(len(section["fields"]) for section in sections)
+    if field_count < 4:
+        return None
+    return {"title": title, "sections": sections}
+
+
+def build_profile_pdf(profile_text: str, source_path: Path) -> BytesIO:
+    try:
+        from reportlab.lib import colors
+        from reportlab.lib.enums import TA_CENTER, TA_LEFT
+        from reportlab.lib.pagesizes import A4
+        from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+        from reportlab.lib.units import inch
+        from reportlab.platypus import HRFlowable, KeepTogether, ListFlowable, ListItem, Paragraph, SimpleDocTemplate, Spacer, Table, TableStyle
+        import markdown
+        from bs4 import BeautifulSoup, NavigableString, Tag
+    except ImportError as exc:
+        raise RuntimeError(f"PDF export requires reportlab, markdown, and beautifulsoup4: {exc}") from exc
+
+    # ReportLab standard fonts (Helvetica) cannot render many Unicode symbols,
+    # causing black squares (■) in the PDF. Strip or replace them.
+    _UNICODE_REPLACEMENTS = {
+        "\u20b9": "INR ",   # ₹ Rupee sign
+        "\u20a8": "Rs ",    # ₨ Rupee sign variant
+        "\u00a3": "GBP ",   # £ Pound
+        "\u00a5": "JPY ",   # ¥ Yen
+        "\u20ac": "EUR ",   # € Euro
+        "\u2022": "-",      # • Bullet
+        "\u2013": "-",      # – En dash
+        "\u2014": "--",     # — Em dash
+        "\u2018": "'",      # ' Left single quote
+        "\u2019": "'",      # ' Right single quote
+        "\u201c": '"',      # " Left double quote
+        "\u201d": '"',      # " Right double quote
+        "\u2026": "...",    # … Ellipsis
+        "\u25a0": "",       # ■ Black square (already rendered glyph)
+        "\u25aa": "",       # ▪ Small black square
+    }
+    for char, replacement in _UNICODE_REPLACEMENTS.items():
+        profile_text = profile_text.replace(char, replacement)
+    # Fallback: strip any remaining non-ASCII characters that Helvetica can't render
+    import re as _re
+    profile_text = _re.sub(r'[^\x00-\x7F]+', lambda m: m.group(0) if all(ord(c) < 256 for c in m.group(0)) else '', profile_text)
+
+    title = profile_pdf_title(source_path, profile_text)
+    output = BytesIO()
+    doc = SimpleDocTemplate(
+        output,
+        pagesize=A4,
+        rightMargin=0.55 * inch,
+        leftMargin=0.55 * inch,
+        topMargin=0.5 * inch,
+        bottomMargin=0.55 * inch,
+        title=title,
+    )
+    styles = getSampleStyleSheet()
+    title_style = ParagraphStyle(
+        "ProspectTitle",
+        parent=styles["Title"],
+        alignment=TA_LEFT,
+        textColor=colors.HexColor("#101820"),
+        fontSize=19,
+        leading=23,
+        spaceAfter=6,
+    )
+    subtitle_style = ParagraphStyle(
+        "ProspectSubtitle",
+        parent=styles["Normal"],
+        alignment=TA_LEFT,
+        textColor=colors.HexColor("#607083"),
+        fontSize=9,
+        leading=12,
+        spaceAfter=10,
+    )
+    heading_styles = {
+        "h1": ParagraphStyle(
+            "ProspectH1",
+            parent=styles["Heading1"],
+            textColor=colors.HexColor("#101820"),
+            fontSize=17,
+            leading=22,
+            spaceBefore=14,
+            spaceAfter=8,
+        ),
+        "h2": ParagraphStyle(
+            "ProspectH2",
+            parent=styles["Heading2"],
+            textColor=colors.HexColor("#101820"),
+            fontSize=14,
+            leading=18,
+            spaceBefore=12,
+            spaceAfter=7,
+        ),
+        "h3": ParagraphStyle(
+            "ProspectH3",
+            parent=styles["Heading3"],
+            textColor=colors.HexColor("#101820"),
+            fontSize=12,
+            leading=15,
+            spaceBefore=9,
+            spaceAfter=5,
+        ),
+    }
+    body_style = ParagraphStyle(
+        "ProspectMarkdownBody",
+        parent=styles["BodyText"],
+        fontSize=9.4,
+        leading=13.2,
+        textColor=colors.HexColor("#101820"),
+        spaceAfter=7,
+    )
+    bullet_style = ParagraphStyle(
+        "ProspectMarkdownBullet",
+        parent=styles["BodyText"],
+        fontSize=9.2,
+        leading=12.8,
+        textColor=colors.HexColor("#101820"),
+        spaceAfter=3,
+    )
+    code_style = ParagraphStyle(
+        "ProspectMarkdownCode",
+        parent=body_style,
+        fontName="Courier",
+        fontSize=8,
+        leading=10.5,
+        backColor=colors.HexColor("#f4f6f8"),
+        borderColor=colors.HexColor("#d9e1e8"),
+        borderWidth=0.4,
+        borderPadding=6,
+    )
+    table_cell_style = ParagraphStyle(
+        "ProspectMarkdownTableCell",
+        parent=body_style,
+        fontSize=8.2,
+        leading=10.8,
+        spaceAfter=0,
+    )
+    table_header_style = ParagraphStyle(
+        "ProspectMarkdownTableHeader",
+        parent=table_cell_style,
+        fontName="Helvetica-Bold",
+        textColor=colors.HexColor("#101820"),
+    )
+    json_label_style = ParagraphStyle(
+        "ProspectJsonLabel",
+        parent=table_cell_style,
+        fontName="Helvetica-Bold",
+        textColor=colors.HexColor("#33445a"),
+        backColor=colors.HexColor("#f6f8fa"),
+    )
+    json_value_style = ParagraphStyle(
+        "ProspectJsonValue",
+        parent=table_cell_style,
+        fontSize=8.4,
+        leading=11.2,
+    )
+    small_style = ParagraphStyle(
+        "ProspectSmall",
+        parent=styles["Normal"],
+        fontSize=8,
+        leading=10.5,
+        textColor=colors.HexColor("#607083"),
+        alignment=TA_LEFT,
+    )
+    structured_section_style = ParagraphStyle(
+        "ProspectStructuredSection",
+        parent=styles["Heading2"],
+        textColor=colors.HexColor("#101820"),
+        fontSize=13,
+        leading=16,
+        spaceBefore=10,
+        spaceAfter=5,
+    )
+    structured_label_style = ParagraphStyle(
+        "ProspectStructuredLabel",
+        parent=styles["BodyText"],
+        fontName="Helvetica-Bold",
+        fontSize=8.1,
+        leading=10,
+        textColor=colors.HexColor("#344054"),
+        spaceAfter=0,
+    )
+    structured_value_style = ParagraphStyle(
+        "ProspectStructuredValue",
+        parent=styles["BodyText"],
+        fontSize=8.6,
+        leading=11.5,
+        textColor=colors.HexColor("#101820"),
+        spaceAfter=0,
+    )
+    structured_card_style = ParagraphStyle(
+        "ProspectStructuredCard",
+        parent=structured_value_style,
+        fontSize=8.4,
+        leading=11.2,
+    )
+    person_card_title_style = ParagraphStyle(
+        "ProspectPersonCardTitle",
+        parent=styles["BodyText"],
+        fontName="Helvetica-Bold",
+        fontSize=9.2,
+        leading=11.5,
+        textColor=colors.HexColor("#101820"),
+        spaceAfter=0,
+    )
+
+    story: list[Any] = [
+        Paragraph(paragraph_text(title), title_style),
+        Paragraph("ProspectIQ Company Intelligence Report", small_style),
+        Paragraph("<b>Source:</b> " + paragraph_text(source_path.name), subtitle_style),
+    ]
+
+    available_width = A4[0] - doc.leftMargin - doc.rightMargin
+
+    def profile_field_value_html(field: dict[str, Any]) -> str:
+        value_parts: list[str] = []
+        value = str(field.get("value") or "").strip()
+        if value:
+            value_parts.append(markdown_inline_to_reportlab(value))
+        for child in field.get("children") or []:
+            child_text = markdown_inline_to_reportlab(str(child))
+            if child_text:
+                value_parts.append("- " + child_text)
+        return "<br/>".join(value_parts) or "Not available"
+
+    def render_profile_fact_grid(fields: list[dict[str, Any]]) -> Table | None:
+        cells: list[Any] = []
+        for field in fields:
+            label = paragraph_text(field.get("label", ""))
+            value = profile_field_value_html(field)
+            cells.append(Paragraph(f"<b>{label}</b><br/>{value}", structured_card_style))
+        if not cells:
+            return None
+        rows: list[list[Any]] = []
+        for index in range(0, len(cells), 2):
+            row = cells[index : index + 2]
+            if len(row) == 1:
+                row.append(Paragraph("", structured_card_style))
+            rows.append(row)
+        table = Table(rows, colWidths=[available_width / 2 - 4, available_width / 2 - 4], hAlign="LEFT", splitByRow=True)
+        table.setStyle(
+            TableStyle(
+                [
+                    ("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#f8fafc")),
+                    ("BOX", (0, 0), (-1, -1), 0.35, colors.HexColor("#d9e1e8")),
+                    ("INNERGRID", (0, 0), (-1, -1), 0.25, colors.HexColor("#e6edf3")),
+                    ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                    ("LEFTPADDING", (0, 0), (-1, -1), 7),
+                    ("RIGHTPADDING", (0, 0), (-1, -1), 7),
+                    ("TOPPADDING", (0, 0), (-1, -1), 6),
+                    ("BOTTOMPADDING", (0, 0), (-1, -1), 6),
+                ]
+            )
+        )
+        return table
+
+    def render_profile_fields_table(fields: list[dict[str, Any]]) -> Table | None:
+        rows: list[list[Any]] = []
+        for field in fields:
+            rows.append(
+                [
+                    Paragraph(paragraph_text(field.get("label", "")), structured_label_style),
+                    Paragraph(profile_field_value_html(field), structured_value_style),
+                ]
+            )
+        if not rows:
+            return None
+        table = Table(rows, colWidths=[available_width * 0.24, available_width * 0.76], hAlign="LEFT", splitByRow=True)
+        table.setStyle(
+            TableStyle(
+                [
+                    ("BACKGROUND", (0, 0), (0, -1), colors.HexColor("#f6f8fa")),
+                    ("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#d9e1e8")),
+                    ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                    ("LEFTPADDING", (0, 0), (-1, -1), 6),
+                    ("RIGHTPADDING", (0, 0), (-1, -1), 6),
+                    ("TOPPADDING", (0, 0), (-1, -1), 5),
+                    ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                ]
+            )
+        )
+        return table
+
+    def split_decision_maker_fields(fields: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        general_fields: list[dict[str, Any]] = []
+        people: list[dict[str, Any]] = []
+        current: dict[str, Any] | None = None
+
+        for field in fields:
+            label = str(field.get("label") or "").strip()
+            if re.match(r"^Person\s+\d+\b", label, flags=re.I):
+                if current:
+                    people.append(current)
+                current = {"marker": field, "fields": []}
+                continue
+            if current is not None:
+                current["fields"].append(field)
+            else:
+                general_fields.append(field)
+
+        if current:
+            people.append(current)
+        return general_fields, people
+
+    def render_decision_maker_card(person: dict[str, Any]) -> KeepTogether | None:
+        marker = person.get("marker") if isinstance(person.get("marker"), dict) else {}
+        person_fields = person.get("fields") if isinstance(person.get("fields"), list) else []
+        marker_label = str(marker.get("label") or "Person").strip()
+        marker_value = strip_inline_markdown(str(marker.get("value") or "")).strip()
+        name_value = ""
+        title_value = ""
+        for field in person_fields:
+            label = str(field.get("label") or "").strip().lower()
+            if label == "name":
+                name_value = strip_inline_markdown(str(field.get("value") or "")).strip()
+            elif label == "title":
+                title_value = strip_inline_markdown(str(field.get("value") or "")).strip()
+
+        summary_parts = [part for part in (name_value, title_value) if part and part.lower() != "not available"]
+        if not summary_parts and marker_value and marker_value.lower() != "not available":
+            summary_parts.append(marker_value)
+        heading = marker_label + (f" - {' | '.join(summary_parts)}" if summary_parts else "")
+
+        rows: list[list[Any]] = [[Paragraph(paragraph_text(heading), person_card_title_style), Paragraph("", person_card_title_style)]]
+        for field in person_fields:
+            rows.append(
+                [
+                    Paragraph(paragraph_text(field.get("label", "")), structured_label_style),
+                    Paragraph(profile_field_value_html(field), structured_value_style),
+                ]
+            )
+        if len(rows) == 1 and marker_value:
+            rows.append(
+                [
+                    Paragraph("Status", structured_label_style),
+                    Paragraph(markdown_inline_to_reportlab(marker_value), structured_value_style),
+                ]
+            )
+        if len(rows) == 1:
+            return None
+
+        table = Table(rows, colWidths=[available_width * 0.24, available_width * 0.76], hAlign="LEFT", splitByRow=True)
+        table.setStyle(
+            TableStyle(
+                [
+                    ("SPAN", (0, 0), (-1, 0)),
+                    ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#eef3f8")),
+                    ("BACKGROUND", (0, 1), (0, -1), colors.HexColor("#f8fafc")),
+                    ("BOX", (0, 0), (-1, -1), 0.45, colors.HexColor("#cdd8e3")),
+                    ("INNERGRID", (0, 1), (-1, -1), 0.25, colors.HexColor("#d9e1e8")),
+                    ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                    ("LEFTPADDING", (0, 0), (-1, -1), 7),
+                    ("RIGHTPADDING", (0, 0), (-1, -1), 7),
+                    ("TOPPADDING", (0, 0), (-1, -1), 5),
+                    ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                ]
+            )
+        )
+        return KeepTogether([table, Spacer(1, 7)])
+
+    def is_short_profile_field(field: dict[str, Any]) -> bool:
+        return not field.get("children") and len(strip_inline_markdown(str(field.get("value") or ""))) <= 95
+
+    structured_profile = parse_structured_profile(profile_text, title)
+    if structured_profile:
+        for section in structured_profile["sections"]:
+            section_title = str(section.get("title") or "").strip()
+            if not section_title or section_title.lower() == title.lower():
+                continue
+            story.append(Paragraph(paragraph_text(section_title), structured_section_style))
+            story.append(HRFlowable(width="100%", thickness=0.35, color=colors.HexColor("#d9e1e8"), spaceAfter=6))
+
+            notes = [note for note in section.get("notes", []) if note]
+            for note in notes:
+                story.append(Paragraph(markdown_inline_to_reportlab(note), body_style))
+
+            fields = list(section.get("fields") or [])
+            if section_title.lower() == "company basics":
+                short_fields = [field for field in fields if is_short_profile_field(field)]
+                long_fields = [field for field in fields if not is_short_profile_field(field)]
+                grid = render_profile_fact_grid(short_fields)
+                if grid:
+                    story.append(grid)
+                    story.append(Spacer(1, 8))
+                table = render_profile_fields_table(long_fields)
+                if table:
+                    story.append(table)
+                    story.append(Spacer(1, 8))
+            elif section_title.lower() == "decision makers":
+                general_fields, people = split_decision_maker_fields(fields)
+                table = render_profile_fields_table(general_fields)
+                if table:
+                    story.append(table)
+                    story.append(Spacer(1, 8))
+                for person in people:
+                    card = render_decision_maker_card(person)
+                    if card:
+                        story.append(card)
+            else:
+                table = render_profile_fields_table(fields)
+                if table:
+                    story.append(table)
+                    story.append(Spacer(1, 8))
+
+        story.extend([Spacer(1, 10), Paragraph("Generated by ProspectIQ. Company Research formatting optimized for PDF readability.", small_style)])
+        doc.build(story)
+        output.seek(0)
+        return output
+
+    html = markdown.markdown(
+        str(profile_text or ""),
+        extensions=["extra", "sane_lists", "nl2br"],
+        output_format="html5",
+    )
+    soup = BeautifulSoup(html, "html.parser")
+
+    def element_text(element: Tag) -> str:
+        nested_lists = element.find_all(["ul", "ol"], recursive=False)
+        for nested in nested_lists:
+            nested.extract()
+        return html_nodes_to_reportlab(element.contents)
+
+    def render_list(list_element: Tag, level: int = 0) -> ListFlowable:
+        items: list[Any] = []
+        for li in list_element.find_all("li", recursive=False):
+            nested_lists = [child for child in li.children if isinstance(child, Tag) and child.name in {"ul", "ol"}]
+            content_nodes = [child for child in li.contents if not (isinstance(child, Tag) and child.name in {"ul", "ol"})]
+            content = html_nodes_to_reportlab(content_nodes) or " "
+            flowables: list[Any] = [Paragraph(content, bullet_style)]
+            for nested in nested_lists:
+                flowables.append(render_list(nested, level + 1))
+            items.append(ListItem(flowables, leftIndent=level * 10))
+        return ListFlowable(
+            items,
+            bulletType="1" if list_element.name == "ol" else "bullet",
+            leftIndent=18 + level * 12,
+            bulletFontName="Helvetica",
+            bulletFontSize=7,
+            bulletOffsetY=1,
+            spaceBefore=2,
+            spaceAfter=6 if level == 0 else 2,
+        )
+
+    def render_table(table_element: Tag) -> Table:
+        rows: list[list[Any]] = []
+        for tr in table_element.find_all("tr"):
+            cells = tr.find_all(["th", "td"], recursive=False)
+            if not cells:
+                continue
+            row: list[Any] = []
+            for cell in cells:
+                style = table_header_style if cell.name == "th" else table_cell_style
+                row.append(Paragraph(html_nodes_to_reportlab(cell.contents), style))
+            rows.append(row)
+        if not rows:
+            rows = [[Paragraph("", table_cell_style)]]
+        column_count = max(len(row) for row in rows)
+        for row in rows:
+            while len(row) < column_count:
+                row.append(Paragraph("", table_cell_style))
+        available_width = A4[0] - doc.leftMargin - doc.rightMargin
+        table = Table(rows, colWidths=[available_width / column_count] * column_count, hAlign="LEFT", splitByRow=True)
+        table.setStyle(
+            TableStyle(
+                [
+                    ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#f0f3f6")),
+                    ("GRID", (0, 0), (-1, -1), 0.35, colors.HexColor("#d9e1e8")),
+                    ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                    ("LEFTPADDING", (0, 0), (-1, -1), 5),
+                    ("RIGHTPADDING", (0, 0), (-1, -1), 5),
+                    ("TOPPADDING", (0, 0), (-1, -1), 5),
+                    ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                ]
+            )
+        )
+        return table
+
+    def humanize_json_key(value: Any) -> str:
+        text = str(value or "").strip()
+        text = re.sub(r"[_-]+", " ", text)
+        text = re.sub(r"\s+", " ", text)
+        return text[:1].upper() + text[1:] if text else "Value"
+
+    def json_scalar(value: Any) -> str:
+        if value is None:
+            return ""
+        if isinstance(value, bool):
+            return "Yes" if value else "No"
+        if isinstance(value, (int, float)):
+            return str(value)
+        return str(value)
+
+    def json_flowables(value: Any, title_text: str = "") -> list[Any]:
+        flowables: list[Any] = []
+        available_width = A4[0] - doc.leftMargin - doc.rightMargin
+
+        if title_text:
+            flowables.append(Paragraph(paragraph_text(humanize_json_key(title_text)), heading_styles["h3"]))
+
+        if isinstance(value, dict):
+            simple_rows: list[list[Any]] = []
+            complex_items: list[tuple[str, Any]] = []
+            for key, item in value.items():
+                if isinstance(item, (dict, list)):
+                    complex_items.append((str(key), item))
+                else:
+                    simple_rows.append(
+                        [
+                            Paragraph(paragraph_text(humanize_json_key(key)), json_label_style),
+                            Paragraph(markdown_inline_to_reportlab(json_scalar(item)), json_value_style),
+                        ]
+                    )
+            if simple_rows:
+                table = Table(simple_rows, colWidths=[available_width * 0.28, available_width * 0.72], hAlign="LEFT", splitByRow=True)
+                table.setStyle(
+                    TableStyle(
+                        [
+                            ("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#d9e1e8")),
+                            ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                            ("LEFTPADDING", (0, 0), (-1, -1), 6),
+                            ("RIGHTPADDING", (0, 0), (-1, -1), 6),
+                            ("TOPPADDING", (0, 0), (-1, -1), 5),
+                            ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                        ]
+                    )
+                )
+                flowables.extend([table, Spacer(1, 8)])
+            for key, item in complex_items:
+                flowables.extend(json_flowables(item, str(key)))
+            return flowables
+
+        if isinstance(value, list):
+            dict_items = [item for item in value if isinstance(item, dict)]
+            if dict_items and len(dict_items) == len(value):
+                keys: list[str] = []
+                for item in dict_items:
+                    for key in item.keys():
+                        if key not in keys and not isinstance(item.get(key), (dict, list)):
+                            keys.append(str(key))
+                if keys:
+                    rows: list[list[Any]] = [
+                        [Paragraph(paragraph_text(humanize_json_key(key)), table_header_style) for key in keys]
+                    ]
+                    for item in dict_items:
+                        rows.append(
+                            [
+                                Paragraph(markdown_inline_to_reportlab(json_scalar(item.get(key))), json_value_style)
+                                for key in keys
+                            ]
+                        )
+                    table = Table(rows, colWidths=[available_width / len(keys)] * len(keys), hAlign="LEFT", splitByRow=True)
+                    table.setStyle(
+                        TableStyle(
+                            [
+                                ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#f0f3f6")),
+                                ("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#d9e1e8")),
+                                ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                                ("LEFTPADDING", (0, 0), (-1, -1), 5),
+                                ("RIGHTPADDING", (0, 0), (-1, -1), 5),
+                                ("TOPPADDING", (0, 0), (-1, -1), 5),
+                                ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                            ]
+                        )
+                    )
+                    flowables.extend([table, Spacer(1, 8)])
+                    for index, item in enumerate(dict_items, start=1):
+                        nested = {key: nested_value for key, nested_value in item.items() if isinstance(nested_value, (dict, list))}
+                        if nested:
+                            flowables.extend(json_flowables(nested, f"Item {index} details"))
+                    return flowables
+
+            list_items = [
+                ListItem([Paragraph(markdown_inline_to_reportlab(json_scalar(item)), bullet_style)])
+                for item in value
+                if not isinstance(item, (dict, list))
+            ]
+            if list_items:
+                flowables.append(ListFlowable(list_items, bulletType="bullet", leftIndent=18, bulletFontSize=7, spaceAfter=8))
+            for index, item in enumerate(value, start=1):
+                if isinstance(item, (dict, list)):
+                    flowables.extend(json_flowables(item, f"Item {index}"))
+            return flowables
+
+        text = json_scalar(value)
+        if text:
+            flowables.append(Paragraph(markdown_inline_to_reportlab(text), body_style))
+        return flowables
+
+    def render_code_block(raw_text: str) -> list[Any]:
+        text = raw_text.strip()
+        json_text = re.sub(r"^\s*json\s+", "", text, flags=re.I | re.S).strip()
+        try:
+            parsed = json.loads(json_text)
+        except (TypeError, json.JSONDecodeError):
+            return [Paragraph(paragraph_text(text), code_style), Spacer(1, 8)]
+        return [*json_flowables(parsed), Spacer(1, 4)]
+
+    for child in soup.contents:
+        if isinstance(child, NavigableString):
+            if child.strip():
+                story.append(Paragraph(markdown_inline_to_reportlab(str(child)), body_style))
+            continue
+        if not isinstance(child, Tag):
+            continue
+
+        tag_name = child.name.lower()
+        if tag_name in heading_styles:
+            story.append(Paragraph(html_nodes_to_reportlab(child.contents), heading_styles[tag_name]))
+            if tag_name == "h1":
+                story.append(HRFlowable(width="100%", thickness=0.4, color=colors.HexColor("#d9e1e8"), spaceAfter=4))
+        elif tag_name in {"h4", "h5", "h6"}:
+            story.append(Paragraph(html_nodes_to_reportlab(child.contents), heading_styles["h3"]))
+        elif tag_name == "p":
+            text = html_nodes_to_reportlab(child.contents)
+            if text:
+                story.append(Paragraph(text, body_style))
+        elif tag_name in {"ul", "ol"}:
+            story.append(render_list(child))
+        elif tag_name == "hr":
+            story.append(Spacer(1, 7))
+            story.append(HRFlowable(width="100%", thickness=0.45, color=colors.HexColor("#d9e1e8"), spaceAfter=7))
+        elif tag_name == "table":
+            story.append(render_table(child))
+            story.append(Spacer(1, 8))
+        elif tag_name == "pre":
+            story.extend(render_code_block(child.get_text()))
+        elif tag_name == "blockquote":
+            text = html_nodes_to_reportlab(child.contents)
+            if text:
+                quote_style = ParagraphStyle(
+                    "ProspectQuote",
+                    parent=body_style,
+                    leftIndent=14,
+                    borderColor=colors.HexColor("#d9e1e8"),
+                    borderWidth=0.5,
+                    borderPadding=7,
+                    textColor=colors.HexColor("#33445a"),
+                )
+                story.append(Paragraph(text, quote_style))
+        else:
+            text = html_nodes_to_reportlab(child.contents)
+            if text:
+                story.append(Paragraph(text, body_style))
+
+    story.extend([Spacer(1, 18), Paragraph("Generated by ProspectIQ. Markdown formatting preserved from the selected profile file.", small_style)])
+    doc.build(story)
+    output.seek(0)
+    return output

services/geo_search.py

@@ -0,0 +1,811 @@
+"""
+finale.py — Multi-AI Company Prospecting Pipeline
+
+Pipeline:
+  1. Detect input type (text vs coordinates)
+  2. If coordinates → Nominatim reverse geocode → location text
+  3. Parallel execution:
+     a. Google Search AI  (separate API key) — finds companies, employees, websites
+     b. Google Maps AI    (separate API key) — finds businesses near location
+  4. Combine results from both
+  5. Checker AI (separate API key) — validates, deduplicates, verifies accuracy
+  6. Judge/Ranking AI (separate API key) — ranks companies based on user query
+"""
+"""An industry ("automotive manufacturers")
+A service ("CNC machining companies")
+A location ("Hamilton, Ontario")
+Or coordinates ("43.2557,-79.8711"""
+
+import re
+import requests
+import concurrent.futures
+from google import genai
+from google.genai import types
+
+from services.ai_service import with_gemini_key_fallback
+
+
+#====================================================
+#  API KEYS — Use separate keys for each AI agent
+#====================================================
+#====================================================
+#  SYSTEM PROMPTS    
+#====================================================
+SEARCH_SYSTEM_PROMPT = """You are a company research analyst. Find legitimate, verified companies matching the user's query and location.
+
+For each company return:
+- Company name
+- Official website URL (confirmed live — never guess; write "Website: Not found" if unconfirmed)
+- Industry / sector
+- Services or products
+- Employee count: search LinkedIn, Crunchbase, or company site; classify as Micro(1-10), Small(11-50), Medium(51-500), Large(501-5000), Enterprise(5000+); include numeric estimate (e.g. "~250 — Medium"); write "Not available" if not found
+- Phone number (if available)
+- Email address (if available)
+- Year founded (if available)
+- Brief description
+
+LINKEDIN (mandatory for every company — search "company name site:linkedin.com/company"):
+- LinkedIn URL (live URL only, never guessed)
+- Headcount (as shown on LinkedIn)
+- Headquarters, Founded year, Industry, Specialties, Followers
+- LinkedIn About (verbatim, do not paraphrase)
+- Write "LinkedIn: Not found" if the page cannot be found
+
+Rules:
+- Only include currently operational companies with a verifiable online presence.
+- Never fabricate data; write "Not available" for missing fields.
+- Employee count is mandatory — always search for it.
+- Never construct or guess URLs; only include URLs found live in search results or credible sources (LinkedIn, Crunchbase, Maps listing).
+- Return consistent structured output for every entry."""
+
+MAPS_SYSTEM_PROMPT = """You are a geographic business discovery specialist using Google Maps data.
+
+Find real businesses near the specified location that match the user's query. For each business return:
+- Business name
+- Full address
+- Category / type
+- Google Maps rating and review count (if available)
+- Phone number (if available)
+- Email address (if available)
+- Website URL (if available)
+
+Rules:
+- Only include physically existing businesses near the location.
+- Do NOT include employee count — that is not your role.
+- Never fabricate addresses or ratings; write "Not available" for missing data.
+- Prioritize businesses relevant to the query.
+- Return consistent structured output for every entry."""
+
+CHECKER_SYSTEM_PROMPT = """You are a data verification and legitimacy specialist.
+
+You receive combined results from Google Search and Google Maps. Your tasks:
+
+1. CROSS-VERIFY: If the same company appears in both sources, merge into one entry (prefer most detailed/accurate data).
+2. VALIDATE URLs (critical): Actively resolve every website URL. Keep it if confirmed live and belonging to the company. If the domain doesn't exist, errors, or redirects elsewhere → replace with "Website: Not found (unresolvable domain)". Never keep guessed URLs; never invent replacements.
+3. VALIDATE CONSISTENCY: Flag logical inconsistencies (e.g., 10,000 employees listed as a tiny local shop).
+4. DEDUPLICATE: Consolidate duplicate entries into one comprehensive record.
+5. REMOVE IRRELEVANT: Remove entries clearly unrelated to the user's query. Do not aggressively remove companies just because their HQ is in a different city if they might have a presence in the queried location. Let the ranking AI score them lower instead.
+6. FLAG UNCERTAINTIES: Mark unverifiable data with [UNVERIFIED].
+7. LOCATION VERIFICATION (every entry): Cross-check address against website, Maps listing, or public records.
+   - Confirmed at queried location → [LOCATION VERIFIED ✓]
+   - Address doesn't match or unconfirmable → [LOCATION MISMATCH ✗] + explain
+   - Insufficient data → [LOCATION UNVERIFIED]
+8. LEGITIMACY VERIFICATION (every entry): Check for working website, consistent name across sources, verifiable registration, real contact details.
+   - Passes checks → [LEGITIMATE ✓]
+   - Signs of fabrication or not found in credible sources → [LEGITIMACY QUESTIONABLE ✗] + reasons
+   - Inconclusive → [LEGITIMACY UNVERIFIED]
+
+Rules:
+- Do NOT add new companies or data not present in the input.
+- Do NOT remove entries just for limited info — only remove duplicates and irrelevant ones.
+- Every entry MUST have both a Location Verification status and a Legitimacy status.
+- End with a brief summary of corrections, removals, flags, and URL issues."""
+
+JUDGE_SYSTEM_PROMPT = """You are a business ranking analyst.
+
+Rank the verified companies from most to least relevant to the user's query using these criteria (in order):
+1. RELEVANCE — services/products match the query
+2. CREDIBILITY — verified website, established presence, good ratings
+3. COMPLETENESS — amount of verified info available
+4. LOCATION FIT — proximity/match to the user's specified area
+5. SCALE — size appropriate for the user's likely needs
+
+For each company, you MUST output the details in the following exact format:
+
+Rank [Rank Number]. [Company Name]
+Key reason: [Reason]
+Category: [Category / Industry, e.g. AI Services]
+Full address: [Full street address as provided, or N/A]
+Phone number: [Phone number as provided, or N/A if missing]
+Website: [Website URL, or N/A if missing or dead link]
+Email: [Email address as provided, or N/A if missing]
+Rating: [Google Maps rating or N/A]
+Services or products: [Services/products as provided, or N/A]
+Verification: [Location label, e.g. LOCATION VERIFIED ✓ or LOCATION MISMATCH ✖ or LOCATION UNVERIFIED]
+
+Rules:
+- Be objective; do NOT invent information — use only what was provided in the checked results.
+- Do NOT output any summary or explanation paragraphs at the end of the ranking list. ONLY output the ranked company blocks.
+- For companies clearly outside the queried location (e.g., Bengaluru instead of Chennai), rank them at the very bottom and state "Location mismatch" in the Key reason.
+- For Website, Phone number, and Email: If the exact valid value is not found, or if it is a dead link, strictly output "N/A". Do not output descriptions like "Not directly listed".
+- Preserve ALL available details from the checked results for each company, especially address, phone, email, and services."""
+
+
+#====================================================
+#  STEP 1: INPUT DETECTION
+#====================================================
+def detect_input_type(user_input: str) -> dict:
+    """
+    Detect whether the user input contains coordinates or is plain text.
+    Returns a dict with 'type' ('coordinates' or 'text') and parsed values.
+    """
+    # Pattern: lat, lon (e.g., "12.225284, 79.074699" or "12.225284 79.074699")
+    coord_pattern = r'[-+]?\d{1,3}\.\d+[\s,]+[-+]?\d{1,3}\.\d+'
+    match = re.search(coord_pattern, user_input)
+
+    if match:
+        coord_str = match.group()
+        parts = re.split(r'[\s,]+', coord_str)
+        lat, lon = float(parts[0]), float(parts[1])
+
+        # Validate coordinate ranges
+        if -90 <= lat <= 90 and -180 <= lon <= 180:
+            # Extract the query part (everything except the coordinates)
+            query_text = user_input.replace(match.group(), '').strip()
+            query_text = re.sub(r'\s+', ' ', query_text).strip(' ,')
+
+            return {
+                'type': 'coordinates',
+                'latitude': lat,
+                'longitude': lon,
+                'query_text': query_text if query_text else None,
+                'raw_input': user_input
+            }
+
+    return {
+        'type': 'text',
+        'query_text': user_input,
+        'latitude': None,
+        'longitude': None,
+        'raw_input': user_input
+    }
+
+
+#====================================================
+#  STEP 2: NOMINATIM REVERSE GEOCODING
+#====================================================
+def nominatim_reverse_geocode(lat: float, lon: float) -> dict:
+    """
+    Convert coordinates to a human-readable location using OpenStreetMap Nominatim.
+    """
+    url = "https://nominatim.openstreetmap.org/reverse"
+    params = {
+        "lat": lat,
+        "lon": lon,
+        "format": "jsonv2",
+        "addressdetails": 1,
+        "zoom": 18
+    }
+    headers = {
+        "User-Agent": "prospect_finder_app/1.0"
+    }
+
+    try:
+        response = requests.get(url, params=params, headers=headers, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        address = data.get("address", {})
+        return {
+            "display_name": data.get("display_name", "Unknown location"),
+            "city": address.get("city", address.get("town", address.get("village", ""))),
+            "state": address.get("state", ""),
+            "country": address.get("country", ""),
+            "postcode": address.get("postcode", ""),
+            "full_address": address
+        }
+    except Exception as e:
+        print(f"[Nominatim Error] {e}")
+        return {
+            "display_name": f"Location at {lat}, {lon}",
+            "city": "", "state": "", "country": "",
+            "postcode": "", "full_address": {}
+        }
+
+
+#====================================================
+#  STEP 3a: GOOGLE SEARCH AI
+#====================================================
+def run_google_search_ai(query: str, location_context: str) -> str:
+    """
+    Use Gemini with Google Search grounding to find company information.
+    """
+    search_prompt = f"""User Query: {query}
+Location Context: {location_context}
+
+Search for legitimate companies and businesses that match the above query in the specified location. 
+Provide detailed information for each company found."""
+
+    try:
+        def request_search(api_key: str):
+            client = genai.Client(api_key=api_key)
+            return client.models.generate_content(
+                model="gemini-2.5-flash",
+                contents=search_prompt,
+                config=types.GenerateContentConfig(
+                    system_instruction=SEARCH_SYSTEM_PROMPT,
+                    tools=[types.Tool(google_search=types.GoogleSearch())],
+                    service_tier=types.ServiceTier.PRIORITY,
+                ),
+            )
+
+        response = with_gemini_key_fallback((), request_search)
+
+        result_text = response.text or ""
+
+        # Extract grounding sources
+        sources = []
+        if response.candidates and response.candidates[0].grounding_metadata:
+            grounding = response.candidates[0].grounding_metadata
+            if grounding.grounding_chunks:
+                for chunk in grounding.grounding_chunks:
+                    if hasattr(chunk, 'web') and chunk.web:
+                        sources.append(f"- [{chunk.web.title}]({chunk.web.uri})")
+
+        if sources:
+            result_text += "\n\n### Google Search Sources:\n" + "\n".join(sources)
+
+        return result_text
+
+    except Exception as gemini_err:
+        # --- Claude Web Search Fallback ---
+        import os
+        import anthropic
+        claude_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+        if not claude_key:
+            return f"[Google Search AI Error] {gemini_err}"
+            
+        client = anthropic.Anthropic(api_key=claude_key)
+        
+        messages = [{"role": "user", "content": search_prompt}]
+        all_sources = []
+        max_continuations = 5
+        continuation_count = 0
+        full_response = ""
+        
+        TOOLS = [{
+            "type": "web_search_20250305",
+            "name": "web_search",
+            "max_uses": 5
+        }]
+        
+        while True:
+            try:
+                message = client.messages.create(
+                    model="claude-haiku-4-5",
+                    max_tokens=4096,
+                    system=SEARCH_SYSTEM_PROMPT,
+                    messages=messages,
+                    tools=TOOLS,
+                )
+            except Exception as claude_err:
+                return f"[Claude Search AI Error] {claude_err} (Gemini error: {gemini_err})"
+                
+            for block in message.content:
+                if block.type == "text":
+                    full_response += block.text
+                    if hasattr(block, "citations") and block.citations:
+                        for citation in block.citations:
+                            if getattr(citation, "type", "") == "web_search_result_location":
+                                source = f"- [{getattr(citation, 'title', 'source')}]({getattr(citation, 'url', '')})"
+                                if source not in all_sources:
+                                    all_sources.append(source)
+                                    
+            stop_reason = message.stop_reason
+            
+            if stop_reason == "end_turn":
+                break
+            elif stop_reason == "max_tokens":
+                continuation_count += 1
+                if continuation_count >= max_continuations:
+                    break
+                messages.append({"role": "assistant", "content": message.content})
+                messages.append({
+                    "role": "user",
+                    "content": "Your previous response was cut off. Please continue exactly from where you left off.",
+                })
+            elif stop_reason == "pause_turn":
+                continuation_count += 1
+                if continuation_count >= max_continuations:
+                    break
+                messages.append({"role": "assistant", "content": message.content})
+            elif stop_reason == "refusal":
+                full_response += "\n\n[Refusal: Claude declined to respond]"
+                break
+            else:
+                break
+                
+        if all_sources:
+            full_response += "\n\n### Claude Web Search Sources:\n" + "\n".join(all_sources)
+            
+        return full_response
+
+
+#====================================================
+#  STEP 3b: GOOGLE MAPS AI
+#====================================================
+def run_google_maps_ai(query: str, lat: float, lon: float, location_context: str) -> str:
+    """
+    Use Gemini with Google Maps grounding to find businesses near coordinates.
+    """
+    maps_prompt = f"""User Query: {query}
+Location: {location_context}
+Coordinates: Latitude {lat}, Longitude {lon}
+
+Find businesses and companies near these coordinates that match the user's query.
+Provide detailed location-based information for each business found."""
+
+    try:
+        config = types.GenerateContentConfig(
+            system_instruction=MAPS_SYSTEM_PROMPT,
+            service_tier=types.ServiceTier.PRIORITY,
+            tools=[types.Tool(google_maps=types.GoogleMaps())],
+            tool_config=types.ToolConfig(
+                retrieval_config=types.RetrievalConfig(
+                    lat_lng=types.LatLng(latitude=lat, longitude=lon)
+                )
+            ),
+        )
+
+        def request_maps(api_key: str):
+            client = genai.Client(api_key=api_key)
+            return client.models.generate_content(
+                model="gemini-2.5-flash",
+                contents=maps_prompt,
+                config=config,
+            )
+
+        response = with_gemini_key_fallback((), request_maps)
+
+        result_text = response.text or ""
+
+        # Extract grounding sources from Maps
+        sources = []
+        if response.candidates and response.candidates[0].grounding_metadata:
+            grounding = response.candidates[0].grounding_metadata
+            if grounding.grounding_chunks:
+                for chunk in grounding.grounding_chunks:
+                    if hasattr(chunk, 'maps') and chunk.maps:
+                        sources.append(f"- [{chunk.maps.title}]({chunk.maps.uri})")
+                    elif hasattr(chunk, 'web') and chunk.web:
+                        sources.append(f"- [{chunk.web.title}]({chunk.web.uri})")
+
+        if sources:
+            result_text += "\n\n### Google Maps Sources:\n" + "\n".join(sources)
+
+        return result_text
+
+    except Exception as e:
+        return "Limit reached try after 5 minutes please contact admin"
+
+
+#====================================================
+#  STEP 4: COMBINE RESULTS
+#====================================================
+def combine_results(search_result: str, maps_result: str) -> str:
+    """
+    Combine the results from Google Search AI and Google Maps AI into a single text block.
+    """
+    combined = f"""
+================================================================================
+                         GOOGLE SEARCH AI RESULTS
+================================================================================
+{search_result}
+
+================================================================================
+                         GOOGLE MAPS AI RESULTS
+================================================================================
+{maps_result}
+"""
+    return combined.strip()
+
+
+#====================================================
+#  STEP 5: CHECKER AI
+#====================================================
+def run_checker_ai(combined_results: str, user_query: str) -> str:
+    """
+    Validate, cross-reference, and deduplicate the combined results.
+    """
+    checker_prompt = f"""User Query: {user_query}
+
+Verify, cross-reference, and clean the results below. For EVERY company apply:
+A) Location label: [LOCATION VERIFIED ✓], [LOCATION MISMATCH ✗], or [LOCATION UNVERIFIED]
+B) Legitimacy label: [LEGITIMATE ✓], [LEGITIMACY QUESTIONABLE ✗] (with reasons), or [LEGITIMACY UNVERIFIED]
+
+--- COMBINED RESULTS ---
+{combined_results}
+--- END ---
+
+Output the cleaned results. Every entry must have both labels."""
+
+    try:
+        def request_checker(api_key: str):
+            client = genai.Client(api_key=api_key)
+            return client.models.generate_content(
+                model="gemini-2.5-flash",
+                contents=checker_prompt,
+                config=types.GenerateContentConfig(
+                    system_instruction=CHECKER_SYSTEM_PROMPT,
+                    tools=[types.Tool(google_search=types.GoogleSearch())],
+                    service_tier=types.ServiceTier.PRIORITY,
+                ),
+            )
+
+        response = with_gemini_key_fallback((), request_checker)
+        return response.text or "[Checker AI returned no output]"
+
+    except Exception as gemini_err:
+        # --- Claude Web Search Fallback ---
+        import os
+        import anthropic
+        claude_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+        if not claude_key:
+            return f"[Checker AI Error] {gemini_err}"
+            
+        client = anthropic.Anthropic(api_key=claude_key)
+        
+        messages = [{"role": "user", "content": checker_prompt}]
+        all_sources = []
+        max_continuations = 5
+        continuation_count = 0
+        full_response = ""
+        
+        TOOLS = [{
+            "type": "web_search_20250305",
+            "name": "web_search",
+            "max_uses": 5
+        }]
+        
+        while True:
+            try:
+                message = client.messages.create(
+                    model="claude-haiku-4-5",
+                    max_tokens=4096,
+                    system=CHECKER_SYSTEM_PROMPT,
+                    messages=messages,
+                    tools=TOOLS,
+                )
+            except Exception as claude_err:
+                return f"[Claude Checker AI Error] {claude_err} (Gemini error: {gemini_err})"
+                
+            for block in message.content:
+                if block.type == "text":
+                    full_response += block.text
+                    if hasattr(block, "citations") and block.citations:
+                        for citation in block.citations:
+                            if getattr(citation, "type", "") == "web_search_result_location":
+                                source = f"- [{getattr(citation, 'title', 'source')}]({getattr(citation, 'url', '')})"
+                                if source not in all_sources:
+                                    all_sources.append(source)
+                                    
+            stop_reason = message.stop_reason
+            
+            if stop_reason == "end_turn":
+                break
+            elif stop_reason == "max_tokens":
+                continuation_count += 1
+                if continuation_count >= max_continuations:
+                    break
+                messages.append({"role": "assistant", "content": message.content})
+                messages.append({
+                    "role": "user",
+                    "content": "Your previous response was cut off. Please continue exactly from where you left off.",
+                })
+            elif stop_reason == "pause_turn":
+                continuation_count += 1
+                if continuation_count >= max_continuations:
+                    break
+                messages.append({"role": "assistant", "content": message.content})
+            elif stop_reason == "refusal":
+                full_response += "\n\n[Refusal: Claude declined to respond]"
+                break
+            else:
+                break
+                
+        if all_sources:
+            full_response += "\n\n### Claude Checker Sources:\n" + "\n".join(all_sources)
+            
+        return full_response
+
+
+#====================================================
+#  STEP 5.5: URL VERIFICATION (Hard Check)
+#====================================================
+def url_exists(url: str) -> bool:
+    """
+    Check if a URL is live by sending a HEAD request.
+    Returns True if status < 400, False otherwise.
+    """
+    try:
+        response = requests.head(url, allow_redirects=True, timeout=5)
+        return response.status_code < 400
+    except requests.RequestException:
+        return False
+
+
+def verify_urls_in_text(text: str) -> str:
+    """
+    Find all URLs in the text using regex, verify each one with url_exists(),
+    and replace dead URLs with a removal notice.
+    Returns the cleaned text.
+    """
+    # Match http/https URLs (exclude trailing backticks, markdown chars, punctuation)
+    url_pattern = r'https?://[^\s\)\]\"\'\>\`\,\;]+'
+    urls_found = re.findall(url_pattern, text)
+
+    # Deduplicate while preserving order
+    unique_urls = list(dict.fromkeys(urls_found))
+
+    if not unique_urls:
+        return text
+
+    print(f"\n[URL Verifier] Checking {len(unique_urls)} unique URLs...")
+
+    # Check URLs in parallel for speed
+    dead_urls = []
+    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
+        future_to_url = {executor.submit(url_exists, url): url for url in unique_urls}
+        for future in concurrent.futures.as_completed(future_to_url):
+            url = future_to_url[future]
+            is_live = future.result()
+            status = "✓ Live" if is_live else "✗ Dead"
+            print(f"  {status}: {url}")
+            if not is_live:
+                dead_urls.append(url)
+
+    # Replace dead URLs in the text
+    cleaned_text = text
+    for dead_url in dead_urls:
+        cleaned_text = cleaned_text.replace(dead_url, "[URL removed — unresolvable/dead link]")
+
+    if dead_urls:
+        print(f"[URL Verifier] Removed {len(dead_urls)} dead URL(s).")
+    else:
+        print(f"[URL Verifier] All URLs are live. ✓")
+
+    return cleaned_text
+
+
+#====================================================
+#  STEP 6: JUDGE / RANKING AI
+#====================================================
+def run_judge_ai(checked_results: str, user_query: str) -> str:
+    """
+    Rank the verified companies based on relevance to the user's query.
+    """
+    judge_prompt = f"""User Query: {user_query}
+
+Rank the verified companies below from most to least relevant.
+
+--- VERIFIED RESULTS ---
+{checked_results}
+--- END ---"""
+
+    try:
+        def request_judge(api_key: str):
+            client = genai.Client(api_key=api_key)
+            return client.models.generate_content(
+                model="gemini-2.5-flash-lite",
+                contents=judge_prompt,
+                config=types.GenerateContentConfig(
+                    system_instruction=JUDGE_SYSTEM_PROMPT,
+                    service_tier=types.ServiceTier.PRIORITY,
+                ),
+            )
+
+        response = with_gemini_key_fallback((), request_judge)
+        return response.text or "[Judge AI returned no output]"
+
+    except Exception as gemini_err:
+        import os
+        import anthropic
+        claude_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+        if not claude_key:
+            return f"[Judge AI Error] {gemini_err}"
+            
+        try:
+            client = anthropic.Anthropic(api_key=claude_key)
+            
+            full_response = ""
+            current_messages = [
+                {"role": "user", "content": judge_prompt}
+            ]
+            max_continuations = 3
+            
+            for _ in range(max_continuations + 1):
+                message = client.messages.create(
+                    model="claude-haiku-4-5",
+                    max_tokens=4096,
+                    system=JUDGE_SYSTEM_PROMPT,
+                    messages=current_messages,
+                )
+                
+                for block in message.content:
+                    if block.type == "text":
+                        full_response += block.text
+                
+                if message.stop_reason != "max_tokens":
+                    break
+                    
+                current_messages.append({"role": "assistant", "content": message.content})
+                current_messages.append({
+                    "role": "user",
+                    "content": "Your response was cut off. Continue exactly from where you stopped."
+                })
+                    
+            return full_response or "[Judge AI returned no output]"
+        except Exception as claude_err:
+            return f"[Claude Judge AI Error] {claude_err} (Gemini error: {gemini_err})"
+
+
+#====================================================
+#  MAIN PIPELINE
+#====================================================
+def run_pipeline(user_input: str) -> dict:
+    """
+    Execute the full multi-AI company prospecting pipeline.
+    Returns a dict with 'result' (final ranking text) and 'maps_sources' (list of dicts).
+    """
+    # === Step 1: Detect input type ===
+    parsed = detect_input_type(user_input)
+
+    lat = parsed['latitude']
+    lon = parsed['longitude']
+    location_context = ""
+
+    # === Step 2: Geocode if coordinates ===
+    if parsed['type'] == 'coordinates':
+        geo_data = nominatim_reverse_geocode(lat, lon)
+        location_context = geo_data['display_name']
+        query = parsed['query_text'] if parsed['query_text'] else f"companies near {location_context}"
+    else:
+        query = parsed['query_text']
+        location_context = query
+        lat = 0.0
+        lon = 0.0
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
+        search_future = executor.submit(run_google_search_ai, query, location_context)
+        maps_future = executor.submit(run_google_maps_ai, query, lat, lon, location_context)
+        search_result = search_future.result()
+        maps_result = maps_future.result()
+
+    if maps_result == "Limit reached try after 5 minutes please contact admin":
+        return {
+            'result': maps_result,
+            'maps_sources': []
+        }
+        
+    # === Step 4: Combine results ===
+    combined = combine_results(search_result, maps_result)
+
+    # === Step 5: Checker AI ===
+    checked = run_checker_ai(combined, user_input)
+
+    # === Step 5.5: URL Verification ===
+    checked = verify_urls_in_text(checked)
+
+    # === Step 6: Judge / Ranking AI ===
+    final_ranking = run_judge_ai(checked, user_input)
+
+    # === Collect Maps sources from the maps_result section ===
+    maps_sources = []
+    for line in maps_result.splitlines():
+        line = line.strip()
+        # Match markdown links like: - [Title](uri)
+        link_match = re.match(r'^-\s*\[(.+?)\]\((.+?)\)', line)
+        if link_match:
+            maps_sources.append({
+                'title': link_match.group(1),
+                'uri': link_match.group(2)
+            })
+
+    return {
+        'result': final_ranking,
+        'maps_sources': maps_sources
+    }
+
+
+#====================================================
+#  STREAMING PIPELINE (yields intermediate results)
+#====================================================
+def run_pipeline_streaming(user_input: str):
+    """
+    Generator version of run_pipeline().
+    Yields JSON-serializable dicts at each pipeline stage so the caller
+    can stream intermediate results to the frontend via SSE.
+    """
+    # === Step 1: Detect input type ===
+    parsed = detect_input_type(user_input)
+    lat = parsed['latitude']
+    lon = parsed['longitude']
+    location_context = ""
+
+    if parsed['type'] == 'coordinates':
+        geo_data = nominatim_reverse_geocode(lat, lon)
+        location_context = geo_data['display_name']
+        query = parsed['query_text'] if parsed['query_text'] else f"companies near {location_context}"
+    else:
+        query = parsed['query_text']
+        location_context = query
+        lat = 0.0
+        lon = 0.0
+
+    yield {"step": "input_parsed", "data": {"input_type": parsed['type'], "query": query, "location_context": location_context}}
+
+    # === Step 2 & 3: Parallel Search + Maps (yield as each completes) ===
+    search_result = ""
+    maps_result = ""
+    with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
+        future_to_name = {
+            executor.submit(run_google_search_ai, query, location_context): "search",
+            executor.submit(run_google_maps_ai, query, lat, lon, location_context): "maps",
+        }
+        for future in concurrent.futures.as_completed(future_to_name):
+            name = future_to_name[future]
+            result = future.result()
+            if name == "search":
+                search_result = result
+                yield {"step": "search_done", "data": search_result}
+            else:
+                maps_result = result
+                if maps_result == "Limit reached try after 5 minutes please contact admin":
+                    yield {"step": "maps_done", "data": maps_result, "maps_sources": []}
+                    yield {"step": "judge_done", "data": maps_result}
+                    return
+                # Extract maps sources from markdown links
+                maps_sources = []
+                for line in maps_result.splitlines():
+                    line_s = line.strip()
+                    link_match = re.match(r'^-\s*\[(.+?)\]\((.+?)\)', line_s)
+                    if link_match:
+                        maps_sources.append({'title': link_match.group(1), 'uri': link_match.group(2)})
+                yield {"step": "maps_done", "data": maps_result, "maps_sources": maps_sources}
+
+    # === Step 4: Combine + Checker AI ===
+    combined = combine_results(search_result, maps_result)
+    checked = run_checker_ai(combined, user_input)
+    yield {"step": "checker_done", "data": checked}
+
+    # === Step 4.5: URL Verification ===
+    checked = verify_urls_in_text(checked)
+    yield {"step": "url_verify_done", "data": checked}
+
+    # === Step 5: Judge / Ranking AI ===
+    final_ranking = run_judge_ai(checked, user_input)
+    yield {"step": "judge_done", "data": final_ranking}
+
+
+#====================================================
+#  ENTRY POINT
+#====================================================
+if __name__ == "__main__":
+    user_input = input("Your query: ").strip()
+
+    if not user_input:
+        print("No input provided. Exiting.")
+    else:
+        output = run_pipeline(user_input)
+
+        print(output['result'])
+
+        if output['maps_sources']:
+            print("\n" + "-" * 40)
+            print("Sources (Google Maps):")
+            for src in output['maps_sources']:
+                print(f"  - [{src['title']}]({src['uri']})")
+
+
+
+

services/ocr.py

@@ -0,0 +1,180 @@
+import json
+import os
+from typing import Any
+
+from google import genai
+from google.genai import types
+
+from services.ai_service import gemini_keys, with_gemini_key_fallback
+
+
+OCR_MODEL = "gemini-2.5-flash"
+DEFAULT_OCR_API_KEY = ""
+
+SYSTEM_PROMPT = """
+You are a precise business card data extraction assistant.
+
+Extract all available information from the business card image and return ONLY a valid JSON object.
+
+Use the following schema exactly:
+
+{
+  "person": {
+    "first_name": "",
+    "last_name": "",
+    "job_title": "",
+    "email": "",
+    "phone": {
+      "mobile": "",
+      "office": "",
+      "extension": ""
+    },
+    "social": {
+      "linkedin": ""
+    }
+  },
+  "company": {
+    "company_name": "",
+    "website": "",
+    "address": {
+      "full_address": "",
+      "street": "",
+      "city": "",
+      "state_province": "",
+      "postal_code": "",
+      "country": ""
+    }
+  },
+  "metadata": {
+    "confidence_score": 0.0,
+    "unparsed_text": "",
+    "card_language": ""
+  }
+}
+
+Rules:
+1. Return ONLY valid JSON.
+2. Do NOT wrap the response in markdown or code fences.
+3. Do NOT include explanations or commentary.
+4. If a field is missing, use an empty string "".
+5. confidence_score must be between 0 and 1.
+6. Put any text that cannot be mapped to a field into metadata.unparsed_text.
+7. Infer card_language using ISO language codes such as "en", "fr", "de", "es", etc.
+8. Extract LinkedIn URLs if present.
+9. Separate mobile, office, and extension numbers when possible.
+10. Preserve all extracted values exactly as written on the card.
+"""
+
+
+def _get_api_key() -> str:
+    keys = gemini_keys()
+    return keys[0] if keys else DEFAULT_OCR_API_KEY
+
+
+def _parse_json_response(text: str) -> dict[str, Any]:
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        cleaned = cleaned.strip("`")
+        if cleaned.lower().startswith("json"):
+            cleaned = cleaned[4:].strip()
+    return json.loads(cleaned)
+
+
+def extract_business_card(image_bytes: bytes, mime_type: str) -> dict[str, Any]:
+    """
+    Extract structured business-card data from uploaded image bytes.
+    """
+    if not image_bytes:
+        raise ValueError("No image bytes provided.")
+
+    api_key = _get_api_key()
+    if not api_key:
+        raise RuntimeError("Set GEMINI_API_KEY_prime_1, GEMINI_API_KEY_prime_2, or GEMINI_API_KEY_prime_3 before using OCR.")
+
+    def call_ocr(key: str):
+        client = genai.Client(api_key=key)
+        return client.models.generate_content(
+            model=OCR_MODEL,
+            contents=[
+                types.Part.from_bytes(data=image_bytes, mime_type=mime_type),
+                SYSTEM_PROMPT,
+            ],
+            config=types.GenerateContentConfig(service_tier=types.ServiceTier.STANDARD),
+        )
+
+    response_text = ""
+    try:
+        response = with_gemini_key_fallback((), call_ocr)
+        response_text = response.text or ""
+    except Exception as gemini_err:
+        import os
+        import base64
+        import anthropic
+        
+        claude_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+        if not claude_key:
+            raise RuntimeError(f"Gemini OCR failed and ANTHROPIC_API_KEY is not configured. Gemini Error: {gemini_err}")
+            
+        client = anthropic.Anthropic(api_key=claude_key)
+        
+        image_data = base64.standard_b64encode(image_bytes).decode("utf-8")
+        image_block = {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": mime_type,
+                "data": image_data,
+            },
+        }
+        
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    image_block,
+                    {"type": "text", "text": "Extract all available information from the business card image and return ONLY a valid JSON object."},
+                ],
+            }
+        ]
+
+        full_response = ""
+        max_continuations = 5
+        continuation_count = 0
+
+        while True:
+            claude_response = client.messages.create(
+                model="claude-haiku-4-5",
+                max_tokens=4096,
+                system=SYSTEM_PROMPT,
+                messages=messages,
+            )
+
+            for block in claude_response.content:
+                if block.type == "text":
+                    full_response += block.text
+
+            stop_reason = claude_response.stop_reason
+
+            if stop_reason == "end_turn":
+                break
+            elif stop_reason == "max_tokens":
+                continuation_count += 1
+                if continuation_count >= max_continuations:
+                    break
+                messages.append({"role": "assistant", "content": claude_response.content})
+                messages.append({
+                    "role": "user",
+                    "content": "Your previous response was cut off. Please continue exactly from where you left off. Do not include markdown or explanations, just the JSON.",
+                })
+            elif stop_reason == "refusal":
+                raise ValueError("Claude refused to analyze this image due to content policy.")
+            else:
+                break
+                
+        response_text = full_response
+
+    try:
+        return _parse_json_response(response_text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"OCR returned invalid JSON: {response_text}") from exc
+

services/rag_service.py

@@ -0,0 +1,975 @@
+"""
+RAG Service for the Learning Section.
+
+Provides document upload, indexing (ChromaDB + Gemini embeddings),
+and retrieval-augmented generation via Gemini 2.5 Flash.
+Each collection is isolated by UUID; each document is tracked by UUID
+so uploads/deletes don't corrupt the vector store.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+BASE_DIR = Path(__file__).resolve().parent.parent
+LEARNING_DATA_DIR = BASE_DIR / "learning_data"
+UPLOADS_DIR = LEARNING_DATA_DIR / "uploads"
+CONVERTED_DIR = LEARNING_DATA_DIR / "converted"
+METADATA_FILE = LEARNING_DATA_DIR / "collections_meta.json"
+
+for _d in (LEARNING_DATA_DIR, UPLOADS_DIR, CONVERTED_DIR):
+    _d.mkdir(parents=True, exist_ok=True)
+
+ALLOWED_EXTENSIONS = {".pdf", ".docx", ".pptx", ".ppt", ".doc", ".xlsx", ".xls"}
+
+def is_supabase_active() -> bool:
+    from db import pg_pool
+    return pg_pool is not None or (os.environ.get("SUPABASE_DB_HOST") is not None and os.environ.get("SUPABASE_DB_PASSWORD") is not None)
+
+def get_supabase_client():
+    url = os.environ.get("SUPABASE_URL")
+    key = os.environ.get("SUPABASE_KEY")
+    if url and key:
+        try:
+            from supabase import create_client
+            return create_client(url, key)
+        except ImportError:
+            print("Warning: supabase python package is not installed. Cloud storage sync disabled.")
+            return None
+        except Exception as e:
+            print(f"Error creating Supabase client: {e}")
+    return None
+
+# ---------------------------------------------------------------------------
+# API key helpers
+# ---------------------------------------------------------------------------
+def get_all_gemini_api_keys() -> list[str]:
+    keys = []
+    for name in ("GEMINI_API_KEY_prime_1", "GEMINI_API_KEY_prime_2", "GEMINI_API_KEY_prime_3"):
+        key = os.environ.get(name, "").strip()
+        if key:
+            keys.append(key)
+    return keys
+
+def get_gemini_api_key() -> str:
+    keys = get_all_gemini_api_keys()
+    return keys[0] if keys else ""
+
+def get_embedding_model(api_key: str = None):
+    from langchain_google_genai import GoogleGenerativeAIEmbeddings
+    if api_key is None:
+        api_key = get_gemini_api_key()
+    return GoogleGenerativeAIEmbeddings(
+        model="gemini-embedding-2-preview",
+        google_api_key=api_key,
+    )
+
+def get_llm(api_key: str = None):
+    from langchain_google_genai import ChatGoogleGenerativeAI
+    if api_key is None:
+        api_key = get_gemini_api_key()
+    return ChatGoogleGenerativeAI(
+        model="gemini-2.5-flash",
+        temperature=0.7,
+        google_api_key=api_key,
+        max_retries=0,
+        model_kwargs={"service_tier": "standard"},
+    )
+
+# ---------------------------------------------------------------------------
+# Metadata (JSON file) management
+# ---------------------------------------------------------------------------
+def load_metadata() -> dict:
+    if METADATA_FILE.exists():
+        with open(METADATA_FILE, "r", encoding="utf-8") as f:
+            return json.load(f)
+    return {"collections": {}}
+
+def save_metadata(meta: dict) -> None:
+    with open(METADATA_FILE, "w", encoding="utf-8") as f:
+        json.dump(meta, f, indent=2, default=str)
+
+# ---------------------------------------------------------------------------
+# Collection CRUD
+# ---------------------------------------------------------------------------
+def create_collection(name: str, user_id: str = '', visibility: str = 'private') -> dict:
+    collection_id = str(uuid.uuid4())
+    if is_supabase_active():
+        from db import get_db_connection
+        created_at = datetime.now().isoformat()
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "INSERT INTO rag_collections (id, name, user_id, visibility, created_at) VALUES (?, ?, ?, ?, ?)",
+                    (collection_id, name, user_id, visibility, created_at)
+                )
+        (UPLOADS_DIR / collection_id).mkdir(parents=True, exist_ok=True)
+        return {
+            "id": collection_id,
+            "name": name,
+            "user_id": user_id,
+            "visibility": visibility,
+            "created_at": created_at,
+        }
+    else:
+        meta = load_metadata()
+        meta["collections"][collection_id] = {
+            "name": name,
+            "user_id": user_id,
+            "visibility": visibility,
+            "created_at": datetime.now().isoformat(),
+            "documents": {},
+        }
+        save_metadata(meta)
+        (UPLOADS_DIR / collection_id).mkdir(parents=True, exist_ok=True)
+        return {
+            "id": collection_id,
+            "name": name,
+            "user_id": user_id,
+            "visibility": visibility,
+            "created_at": meta["collections"][collection_id]["created_at"],
+        }
+
+def rename_collection(collection_id: str, new_name: str) -> dict:
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("UPDATE rag_collections SET name = ? WHERE id = ?", (new_name, collection_id))
+        return {"id": collection_id, "name": new_name}
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        meta["collections"][collection_id]["name"] = new_name
+        save_metadata(meta)
+        return {"id": collection_id, "name": new_name}
+
+def list_collections(user_id: str = '', user_role: str = '') -> list[dict]:
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("""
+                    SELECT rc.*, COUNT(rd.id) as doc_count
+                    FROM rag_collections rc
+                    LEFT JOIN rag_documents rd ON rc.id = rd.collection_id
+                    GROUP BY rc.id, rc.created_at, rc.name, rc.user_id, rc.visibility
+                """)
+                rows = cursor.fetchall()
+        result = []
+        for r in rows:
+            entry = {
+                "id": r["id"],
+                "name": r["name"],
+                "created_at": str(r["created_at"]),
+                "document_count": r["doc_count"],
+                "user_id": r.get("user_id", ""),
+                "visibility": r.get("visibility", "private"),
+            }
+            if user_role in ('Admin', 'Super Admin'):
+                result.append(entry)
+            else:
+                owner = r.get("user_id", "")
+                vis = r.get("visibility", "private")
+                if not owner or owner == user_id or vis == 'public':
+                    result.append(entry)
+        result.sort(key=lambda x: x["created_at"], reverse=True)
+        return result
+    else:
+        meta = load_metadata()
+        result = []
+        for cid, cdata in meta["collections"].items():
+            entry = {
+                "id": cid,
+                "name": cdata["name"],
+                "created_at": cdata["created_at"],
+                "document_count": len(cdata.get("documents", {})),
+                "user_id": cdata.get("user_id", ""),
+                "visibility": cdata.get("visibility", "private"),
+            }
+            if user_role in ('Admin', 'Super Admin'):
+                result.append(entry)
+            else:
+                owner = cdata.get("user_id", "")
+                vis = cdata.get("visibility", "private")
+                if not owner or owner == user_id or vis == 'public':
+                    result.append(entry)
+        result.sort(key=lambda x: x["created_at"], reverse=True)
+        return result
+
+def delete_collection(collection_id: str) -> None:
+    # Pinecone deletion
+    try:
+        from pinecone import Pinecone
+        pc = Pinecone(api_key=os.environ.get("PINECONE_API_KEY"))
+        index = pc.Index("maple-prospect")
+        index.delete(delete_all=True, namespace=f"col_{collection_id[:8]}")
+    except Exception as exc:
+        print(f"Warning: Pinecone cleanup for collection {collection_id}: {exc}")
+
+    if is_supabase_active():
+        from db import get_db_connection
+        supabase = get_supabase_client()
+        if supabase:
+            try:
+                # Retrieve files from DB to remove from storage
+                with get_db_connection() as conn:
+                    with conn.cursor() as cursor:
+                        cursor.execute("SELECT upload_path FROM rag_documents WHERE collection_id = ?", (collection_id,))
+                        doc_rows = cursor.fetchall()
+                paths_to_delete = [d["upload_path"] for d in doc_rows if d.get("upload_path")]
+                if paths_to_delete:
+                    supabase.storage.from_("learning-playbook").remove(paths_to_delete)
+            except Exception as exc:
+                print(f"Warning: Supabase Storage cleanup for collection {collection_id}: {exc}")
+
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("DELETE FROM rag_collections WHERE id = ?", (collection_id,))
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        # Remove uploaded files
+        for d in (UPLOADS_DIR / collection_id, CONVERTED_DIR / collection_id):
+            if d.exists():
+                shutil.rmtree(d, ignore_errors=True)
+        del meta["collections"][collection_id]
+        save_metadata(meta)
+
+def list_documents(collection_id: str) -> list[dict]:
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT * FROM rag_documents WHERE collection_id = ? ORDER BY uploaded_at DESC", (collection_id,))
+                rows = cursor.fetchall()
+        return [
+            {
+                "id": r["id"],
+                "filename": r["filename"],
+                "original_type": r["original_type"],
+                "pages": r.get("pages", 0),
+                "chunks": r.get("chunks", 0),
+                "uploaded_at": str(r["uploaded_at"]),
+            }
+            for r in rows
+        ]
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        docs = meta["collections"][collection_id].get("documents", {})
+        return [
+            {
+                "id": did,
+                "filename": dd["filename"],
+                "original_type": dd["original_type"],
+                "pages": dd.get("pages", 0),
+                "chunks": dd.get("chunks", 0),
+                "uploaded_at": dd["uploaded_at"],
+            }
+            for did, dd in docs.items()
+        ]
+
+# ---------------------------------------------------------------------------
+# File-type detection & conversion helpers
+# ---------------------------------------------------------------------------
+def detect_file_type(filename: str) -> str | None:
+    ext = Path(filename).suffix.lower()
+    if ext == ".pdf":
+        return "pdf"
+    if ext in (".docx", ".doc"):
+        return "docx"
+    if ext in (".pptx", ".ppt"):
+        return "pptx"
+    if ext in (".xlsx", ".xls"):
+        return "xlsx"
+    return None
+
+def find_soffice() -> str | None:
+    if shutil.which("soffice"):
+        return "soffice"
+    for p in (
+        r"C:\Program Files\LibreOffice\program\soffice.exe",
+        r"C:\Program Files (x86)\LibreOffice\program\soffice.exe",
+        "/usr/bin/soffice",
+        "/usr/local/bin/soffice",
+    ):
+        if Path(p).exists():
+            return p
+    return None
+
+def convert_to_pdf(input_path: Path, output_dir: Path) -> Path:
+    soffice = find_soffice()
+    if not soffice:
+        raise RuntimeError(
+            "LibreOffice is not installed. Install it to convert DOCX/PPT files. "
+            "Download: https://www.libreoffice.org/download/"
+        )
+    output_dir.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        [soffice, "--headless", "--convert-to", "pdf", str(input_path), "--outdir", str(output_dir)],
+        check=True,
+        capture_output=True,
+        timeout=120,
+    )
+    pdf_path = output_dir / (input_path.stem + ".pdf")
+    if not pdf_path.exists():
+        raise RuntimeError(f"Conversion failed – PDF not found at {pdf_path}")
+    return pdf_path
+
+# ---------------------------------------------------------------------------
+# Document add / delete
+# ---------------------------------------------------------------------------
+def add_document(collection_id: str, file_storage) -> dict:
+    """Save, optionally convert, chunk, embed and store a document."""
+    filename = file_storage.filename
+    file_type = detect_file_type(filename)
+    if not file_type:
+        raise ValueError("Unsupported file type. Allowed: PDF, DOCX, PPT/PPTX, XLSX/XLS")
+
+    doc_id = str(uuid.uuid4())
+
+    # Persist raw upload
+    upload_dir = UPLOADS_DIR / collection_id
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    safe_name = f"{doc_id}_{filename}"
+    upload_path = upload_dir / safe_name
+    file_storage.save(str(upload_path))
+
+    if is_supabase_active():
+        storage_path = f"uploads/{collection_id}/{safe_name}"
+        supabase = get_supabase_client()
+        if supabase:
+            try:
+                import mimetypes
+                mime_type, _ = mimetypes.guess_type(filename)
+                if not mime_type:
+                    mime_type = "application/octet-stream"
+                with open(upload_path, "rb") as f:
+                    supabase.storage.from_("learning-playbook").upload(
+                        path=storage_path,
+                        file=f,
+                        file_options={"content-type": mime_type, "x-upsert": "true"}
+                    )
+            except Exception as exc:
+                print(f"Warning: Supabase Storage upload failed, relying on local: {exc}")
+
+        from db import get_db_connection
+        created_at = datetime.now().isoformat()
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "INSERT INTO rag_documents (id, collection_id, filename, original_type, pages, chunks, uploaded_at, upload_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (doc_id, collection_id, filename, file_type, 0, 0, created_at, storage_path)
+                )
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        meta["collections"][collection_id]["documents"][doc_id] = {
+            "filename": filename,
+            "original_type": file_type,
+            "pages": 0,
+            "chunks": 0,
+            "uploaded_at": datetime.now().isoformat(),
+            "upload_path": str(upload_path),
+        }
+        save_metadata(meta)
+
+    # Trigger background processing task
+    from tasks import process_document_task
+    task = process_document_task.delay(collection_id, doc_id, filename, file_type, str(upload_path))
+
+    return {
+        "id": doc_id,
+        "filename": filename,
+        "original_type": file_type,
+        "task_id": task.id,
+        "status": "processing"
+    }
+
+# ---------------------------------------------------------------------------
+# Shared text → ChromaDB indexer (used by video/url sources)
+# ---------------------------------------------------------------------------
+def _index_text_as_document(
+    collection_id: str,
+    doc_id: str,
+    text: str,
+    source_name: str,
+    source_type: str,
+) -> dict:
+    """Chunk raw text and index it into Pinecone under *doc_id*."""
+    from langchain_core.documents import Document as LCDocument
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=1000,
+        chunk_overlap=300,
+        length_function=len,
+        add_start_index=True,
+    )
+    chunks = splitter.create_documents(
+        [text],
+        metadatas=[{"doc_id": doc_id, "filename": source_name, "page": 0}],
+    )
+
+    if chunks:
+        from langchain_pinecone import PineconeVectorStore
+        keys = get_all_gemini_api_keys()
+        if not keys:
+            raise ValueError("Limit reached try after 5 minutes please contact admin")
+
+        success = False
+        last_err = None
+        for key in keys:
+            try:
+                embedding_model = get_embedding_model(key)
+                PineconeVectorStore.from_documents(
+                    chunks,
+                    embedding_model,
+                    index_name="maple-prospect",
+                    namespace=f"col_{collection_id[:8]}"
+                )
+                success = True
+                break
+            except Exception as e:
+                last_err = e
+                continue
+
+        if not success:
+            raise ValueError("Limit reached try after 5 minutes please contact admin")
+
+    return {"chunks": len(chunks)}
+
+# ---------------------------------------------------------------------------
+# YouTube URL → transcript → index
+# ---------------------------------------------------------------------------
+def _extract_youtube_video_id(url: str) -> str | None:
+    from urllib.parse import urlparse, parse_qs
+    parsed = urlparse(url)
+    if parsed.hostname in ("www.youtube.com", "youtube.com"):
+        return parse_qs(parsed.query).get("v", [None])[0]
+    if parsed.hostname == "youtu.be":
+        return parsed.path.lstrip("/")
+    return None
+
+def add_youtube_url(collection_id: str, url: str) -> dict:
+    """Fetch YouTube transcript via Google Gemini and index it into the collection."""
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT id FROM rag_collections WHERE id = ?", (collection_id,))
+                if not cursor.fetchone():
+                    raise ValueError("Collection not found")
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+
+    video_id = _extract_youtube_video_id(url)
+    if not video_id:
+        raise ValueError("Invalid YouTube URL. Supported formats: youtube.com/watch?v=... or youtu.be/...")
+
+    doc_id = str(uuid.uuid4())
+    source_name = f"youtube_{video_id}.txt"
+
+    if is_supabase_active():
+        from db import get_db_connection
+        created_at = datetime.now().isoformat()
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "INSERT INTO rag_documents (id, collection_id, filename, original_type, pages, chunks, uploaded_at, upload_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (doc_id, collection_id, source_name, "youtube", 0, 0, created_at, None)
+                )
+    else:
+        meta = load_metadata()
+        meta["collections"][collection_id]["documents"][doc_id] = {
+            "filename": source_name,
+            "original_type": "youtube",
+            "pages": 0,
+            "chunks": 0,
+            "uploaded_at": datetime.now().isoformat(),
+            "upload_path": None,
+        }
+        save_metadata(meta)
+
+    from tasks import process_youtube_task
+    task = process_youtube_task.delay(collection_id, doc_id, url, video_id, source_name)
+
+    return {
+        "id": doc_id,
+        "filename": source_name,
+        "original_type": "youtube",
+        "source_url": url,
+        "task_id": task.id,
+        "status": "processing"
+    }
+
+# ---------------------------------------------------------------------------
+# Local MP4 video → upload to Gemini → transcribe → index
+# ---------------------------------------------------------------------------
+def add_video_file(collection_id: str, file_storage) -> dict:
+    """Upload an MP4, transcribe with Google Gemini, and index."""
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT id FROM rag_collections WHERE id = ?", (collection_id,))
+                if not cursor.fetchone():
+                    raise ValueError("Collection not found")
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+
+    filename = file_storage.filename
+    if not filename.lower().endswith(".mp4"):
+        raise ValueError("Only .mp4 video files are supported.")
+
+    doc_id = str(uuid.uuid4())
+
+    # Save uploaded MP4
+    upload_dir = UPLOADS_DIR / collection_id
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    mp4_path = upload_dir / f"{doc_id}_{filename}"
+    file_storage.save(str(mp4_path))
+
+    if is_supabase_active():
+        storage_path = f"uploads/{collection_id}/{doc_id}_{filename}"
+        supabase = get_supabase_client()
+        if supabase:
+            try:
+                import mimetypes
+                mime_type, _ = mimetypes.guess_type(filename)
+                if not mime_type:
+                    mime_type = "video/mp4"
+                with open(mp4_path, "rb") as f:
+                    supabase.storage.from_("learning-playbook").upload(
+                        path=storage_path,
+                        file=f,
+                        file_options={"content-type": mime_type, "x-upsert": "true"}
+                    )
+            except Exception as exc:
+                print(f"Warning: Supabase Storage upload failed, relying on local: {exc}")
+
+        from db import get_db_connection
+        created_at = datetime.now().isoformat()
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "INSERT INTO rag_documents (id, collection_id, filename, original_type, pages, chunks, uploaded_at, upload_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (doc_id, collection_id, filename, "mp4", 0, 0, created_at, storage_path)
+                )
+    else:
+        meta = load_metadata()
+        meta["collections"][collection_id]["documents"][doc_id] = {
+            "filename": filename,
+            "original_type": "mp4",
+            "pages": 0,
+            "chunks": 0,
+            "uploaded_at": datetime.now().isoformat(),
+            "upload_path": str(mp4_path),
+        }
+        save_metadata(meta)
+
+    from tasks import process_video_task
+    task = process_video_task.delay(collection_id, doc_id, filename, str(mp4_path))
+
+    return {
+        "id": doc_id,
+        "filename": filename,
+        "original_type": "mp4",
+        "task_id": task.id,
+        "status": "processing"
+    }
+
+def delete_document(collection_id: str, doc_id: str) -> None:
+    # Remove chunks from Pinecone
+    try:
+        from pinecone import Pinecone
+        pc = Pinecone(api_key=os.environ.get("PINECONE_API_KEY"))
+        index = pc.Index("maple-prospect")
+        index.delete(filter={"doc_id": {"$eq": doc_id}}, namespace=f"col_{collection_id[:8]}")
+    except Exception as exc:
+        print(f"Warning: Pinecone cleanup for doc {doc_id}: {exc}")
+
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT * FROM rag_documents WHERE id = ?", (doc_id,))
+                doc_data = cursor.fetchone()
+
+        if not doc_data:
+            raise ValueError("Document not found")
+
+        # Remove from Supabase Storage
+        supabase = get_supabase_client()
+        if supabase and doc_data.get("upload_path"):
+            try:
+                supabase.storage.from_("learning-playbook").remove([doc_data["upload_path"]])
+            except Exception as exc:
+                print(f"Warning: Supabase Storage file deletion failed: {exc}")
+
+        # Remove local file if exists
+        local_filename = f"{doc_id}_{doc_data['filename']}"
+        local_path = UPLOADS_DIR / collection_id / local_filename
+        if local_path.exists():
+            local_path.unlink(missing_ok=True)
+
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("DELETE FROM rag_documents WHERE id = ?", (doc_id,))
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        if doc_id not in meta["collections"][collection_id].get("documents", {}):
+            raise ValueError("Document not found")
+
+        # Remove file
+        doc_data = meta["collections"][collection_id]["documents"][doc_id]
+        upload_path = doc_data.get("upload_path")
+        if upload_path and Path(upload_path).exists():
+            Path(upload_path).unlink(missing_ok=True)
+
+        del meta["collections"][collection_id]["documents"][doc_id]
+        save_metadata(meta)
+
+# ---------------------------------------------------------------------------
+# RAG query
+# ---------------------------------------------------------------------------
+def format_docs(docs) -> str:
+    formatted = []
+    seen_content: set[str] = set()
+    for doc in docs:
+        page_num = doc.metadata.get("page", 0)
+        content = doc.page_content.strip()
+        if content not in seen_content:
+            seen_content.add(content)
+            formatted.append(f"[Page {page_num + 1}]: {content}")
+    return "\n\n".join(formatted)
+
+# ---------------------------------------------------------------------------
+# Chat Sessions
+# ---------------------------------------------------------------------------
+MAX_MEMORY_TURNS = 5  # number of Q&A pairs kept as LLM context
+
+def create_session(collection_id: str, name: str | None = None) -> dict:
+    if is_supabase_active():
+        from db import get_db_connection
+        session_id = str(uuid.uuid4())
+        created_at = datetime.now().isoformat()
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT COUNT(*) FROM rag_sessions WHERE collection_id = ?", (collection_id,))
+                count = cursor.fetchone()[0]
+                session_name = name or f"Chat {count + 1}"
+                cursor.execute(
+                    "INSERT INTO rag_sessions (id, collection_id, name, created_at) VALUES (?, ?, ?, ?)",
+                    (session_id, collection_id, session_name, created_at)
+                )
+        return {"id": session_id, "name": session_name, "created_at": created_at}
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        sessions = meta["collections"][collection_id].setdefault("sessions", {})
+        session_id = str(uuid.uuid4())
+        session_name = name or f"Chat {len(sessions) + 1}"
+        sessions[session_id] = {
+            "name": session_name,
+            "created_at": datetime.now().isoformat(),
+            "messages": [],
+        }
+        save_metadata(meta)
+        return {"id": session_id, "name": session_name, "created_at": sessions[session_id]["created_at"]}
+
+def list_sessions(collection_id: str) -> list[dict]:
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("""
+                    SELECT rs.*, COUNT(rm.id) as msg_count
+                    FROM rag_sessions rs
+                    LEFT JOIN rag_messages rm ON rs.id = rm.session_id
+                    WHERE rs.collection_id = ?
+                    GROUP BY rs.id, rs.created_at, rs.name, rs.collection_id
+                    ORDER BY rs.created_at DESC
+                """, (collection_id,))
+                rows = cursor.fetchall()
+        return [
+            {
+                "id": r["id"],
+                "name": r["name"],
+                "created_at": str(r["created_at"]),
+                "message_count": r["msg_count"],
+            }
+            for r in rows
+        ]
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        sessions = meta["collections"][collection_id].get("sessions", {})
+        result = []
+        for sid, sdata in sessions.items():
+            result.append({
+                "id": sid,
+                "name": sdata["name"],
+                "created_at": sdata["created_at"],
+                "message_count": len(sdata.get("messages", [])),
+            })
+        result.sort(key=lambda x: x["created_at"], reverse=True)
+        return result
+
+def get_session_messages(collection_id: str, session_id: str) -> list[dict]:
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT role, content, sources FROM rag_messages WHERE session_id = ? ORDER BY id ASC", (session_id,))
+                rows = cursor.fetchall()
+        return [
+            {
+                "role": r["role"],
+                "content": r["content"],
+                "sources": r["sources"] if isinstance(r["sources"], list) else json.loads(r["sources"] or "[]"),
+            }
+            for r in rows
+        ]
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        sessions = meta["collections"][collection_id].get("sessions", {})
+        if session_id not in sessions:
+            raise ValueError("Session not found")
+        return sessions[session_id].get("messages", [])
+
+def delete_session(collection_id: str, session_id: str) -> None:
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("DELETE FROM rag_sessions WHERE id = ?", (session_id,))
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        sessions = meta["collections"][collection_id].get("sessions", {})
+        if session_id not in sessions:
+            raise ValueError("Session not found")
+        del sessions[session_id]
+        save_metadata(meta)
+
+def rename_session(collection_id: str, session_id: str, new_name: str) -> dict:
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("UPDATE rag_sessions SET name = ? WHERE id = ?", (new_name, session_id))
+        return {"id": session_id, "name": new_name}
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        sessions = meta["collections"][collection_id].get("sessions", {})
+        if session_id not in sessions:
+            raise ValueError("Session not found")
+        sessions[session_id]["name"] = new_name
+        save_metadata(meta)
+        return {"id": session_id, "name": new_name}
+
+def _save_message(collection_id: str, session_id: str, role: str, content: str, sources: list | None = None) -> None:
+    """Append a message to a session's history."""
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    "INSERT INTO rag_messages (collection_id, session_id, role, content, sources) VALUES (?, ?, ?, ?, ?)",
+                    (collection_id, session_id, role, content, json.dumps(sources or []))
+                )
+    else:
+        meta = load_metadata()
+        sessions = meta["collections"][collection_id].get("sessions", {})
+        if session_id not in sessions:
+            return
+        msg: dict[str, Any] = {"role": role, "content": content}
+        if sources is not None:
+            msg["sources"] = sources
+        sessions[session_id]["messages"].append(msg)
+        save_metadata(meta)
+
+# ---------------------------------------------------------------------------
+# RAG query (with session memory)
+# ---------------------------------------------------------------------------
+def query_collection(collection_id: str, question: str, session_id: str | None = None) -> dict[str, Any]:
+    """Run a RAG query against the indexed documents in *collection_id*."""
+    if is_supabase_active():
+        from db import get_db_connection
+        with get_db_connection() as conn:
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT id FROM rag_collections WHERE id = ?", (collection_id,))
+                if not cursor.fetchone():
+                    raise ValueError("Collection not found")
+                cursor.execute("SELECT COUNT(*) FROM rag_documents WHERE collection_id = ?", (collection_id,))
+                doc_count = cursor.fetchone()[0]
+                if doc_count == 0:
+                    return {
+                        "answer": "No documents have been uploaded yet. Please upload some documents first.",
+                        "sources": [],
+                    }
+    else:
+        meta = load_metadata()
+        if collection_id not in meta["collections"]:
+            raise ValueError("Collection not found")
+        if not meta["collections"][collection_id].get("documents"):
+            return {
+                "answer": "No documents have been uploaded yet. Please upload some documents first.",
+                "sources": [],
+            }
+
+    from langchain_pinecone import PineconeVectorStore
+    from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+
+    keys = get_all_gemini_api_keys()
+    if not keys:
+        return {"answer": "Limit reached try after 5 minutes please contact admin", "sources": [], "suggestions": []}
+
+    docs = None
+    last_err = None
+    for key in keys:
+        try:
+            embedding_model = get_embedding_model(key)
+            vector_store = PineconeVectorStore(
+                index_name="maple-prospect",
+                embedding=embedding_model,
+                namespace=f"col_{collection_id[:8]}"
+            )
+            retriever = vector_store.as_retriever(
+                search_type="similarity",
+                search_kwargs={"k": 3},
+            )
+            docs = retriever.invoke(question)
+            break
+        except Exception as e:
+            last_err = e
+            docs = None
+            continue
+
+    if docs is None and last_err is not None:
+        return {"answer": "Limit reached try after 5 minutes please contact admin", "sources": [], "suggestions": []}
+
+    if not docs:
+        return {"answer": "The answer is not available in the uploaded documents.", "sources": []}
+
+    context = format_docs(docs)
+
+    # Build message list with system prompt
+    messages = [
+        SystemMessage(
+            content=(
+                "You are an intelligent explainer and learning assistant — like a knowledgeable tutor "
+                "who can both explain documents and answer general questions. "
+                "Your job is to make complex topics easy to understand. "
+                "Always respond in a clear, engaging, and well-structured way with 3 to 4 sentences minimum. "
+                "Do not give one-line answers. Include key details and slightly elaborate the concept.\n\n"
+
+                "When answering, follow these rules:\n"
+                "1. DOCUMENT QUESTIONS: If the answer is present in the provided context, answer using "
+                "that context. Each piece of context is prefixed with its page number like [Page 3]. "
+                "Naturally include page references like (p. 3) when citing specific information — "
+                "do not overuse them, only cite the most relevant pages.\n"
+                "2. GENERAL QUESTIONS: If the user is asking a general question that is NOT in the "
+                "document context, use your own knowledge to explain it clearly and helpfully. "
+                "In this case, mention that you are answering from general knowledge, not the document.\n"
+                "3. MIXED: If the question is partially answered by the document and partially general, "
+                "combine both — cite the document where relevant and supplement with your own knowledge.\n\n"
+
+                "After your answer, add a line containing ONLY '---SUGGESTIONS---' "
+                "followed by exactly 3 short follow-up questions the user might want to ask next, "
+                "each on its own line starting with '- '. "
+                "These should be relevant to the context and your answer."
+            )
+        ),
+    ]
+
+    # Inject last N conversation turns as memory
+    if session_id:
+        history = get_session_messages(collection_id, session_id)
+        # Take last MAX_MEMORY_TURNS pairs (user + assistant = 2 messages each)
+        recent = history[-(MAX_MEMORY_TURNS * 2):]
+        for msg in recent:
+            if msg["role"] == "user":
+                messages.append(HumanMessage(content=msg["content"]))
+            elif msg["role"] == "assistant":
+                messages.append(AIMessage(content=msg["content"]))
+
+    # Current question with context
+    messages.append(HumanMessage(content=f"Context:\n{context}\n\nQuestion:\n{question}"))
+
+    response = None
+    last_err = None
+    for key in keys:
+        try:
+            llm = get_llm(key)
+            response = llm.invoke(messages)
+            break
+        except Exception as e:
+            last_err = e
+            response = None
+            continue
+
+    if response is None:
+        return {"answer": "Limit reached try after 5 minutes please contact admin", "sources": [], "suggestions": []}
+
+    # Parse answer and follow-up suggestions
+    raw_content = response.content or ""
+    suggestions: list[str] = []
+    answer_text = raw_content
+
+    if "---SUGGESTIONS---" in raw_content:
+        parts = raw_content.split("---SUGGESTIONS---", 1)
+        answer_text = parts[0].strip()
+        suggestion_block = parts[1].strip()
+        for line in suggestion_block.splitlines():
+            line = line.strip()
+            if line.startswith("- "):
+                suggestions.append(line[2:].strip())
+        suggestions = suggestions[:3]  # cap at 3
+
+    # Collect source references
+    sources: list[dict] = []
+    seen_pages: set[int] = set()
+    for doc in docs:
+        page = doc.metadata.get("page", 0) + 1
+        fname = doc.metadata.get("filename", "Unknown")
+        if page not in seen_pages:
+            seen_pages.add(page)
+            sources.append({"page": page, "filename": fname})
+
+    # Persist messages to session
+    if session_id:
+        _save_message(collection_id, session_id, "user", question)
+        _save_message(collection_id, session_id, "assistant", answer_text, sources)
+
+    return {"answer": answer_text, "sources": sources, "suggestions": suggestions}
+

services/research/__init__.py

@@ -0,0 +1 @@
+"""Research pipeline services package for ProspectIQ."""

services/research/analyzer.py

@@ -0,0 +1,568 @@
+#!/usr/bin/env python3
+"""
+Company Research Script
+Uses Gemini 2.5 Flash with Google Search grounding to research a target
+company and produce a B2B sales intelligence profile — tailored to the
+seller's own business context, loaded fresh from company.md on every run.
+"""
+
+import os
+import sys
+import json
+import argparse
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+from dotenv import load_dotenv
+from google import genai
+from google.genai.types import Tool, GoogleSearch, GenerateContentConfig, ServiceTier
+
+# Load environment variables
+load_dotenv()
+
+PAID_GEMINI_ENV_NAMES = (
+    "GEMINI_API_KEY_prime_1",
+    "GEMINI_API_KEY_prime_2",
+    "GEMINI_API_KEY_prime_3",
+)
+
+def get_all_paid_gemini_api_keys() -> list[str]:
+    keys = []
+    for name in PAID_GEMINI_ENV_NAMES:
+        key = os.getenv(name, "").strip()
+        if key:
+            keys.append(key)
+    return keys
+
+DEFAULT_COMPANY_MD_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "company.md")
+DEFAULT_SEARCH_RESULTS_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "combined_results.json")
+
+RESEARCH_PROMPT = """
+You are a world-class B2B sales intelligence researcher working on behalf of OUR COMPANY (described below).
+Your task is to research the TARGET COMPANY "{company_name}" thoroughly using web search and produce a
+structured, detailed profile that helps OUR COMPANY's sales team sell to them.
+
+=== OUR COMPANY (the seller — use this to tailor relevance, fit, and decision-maker targeting) ===
+{seller_context}
+=== END OUR COMPANY CONTEXT ===
+
+Fill in EVERY field below for the TARGET COMPANY "{company_name}". For fields where data is unavailable
+after searching, write "Not publicly available" — never leave blank.
+
+---
+
+# Company Basics
+
+- **Company Name**:
+- **Website**:
+- **LinkedIn URL**:
+- **Industry**:
+- **Sub-Industry**:
+- **Business Description**: (3–5 sentence overview)
+- **Products / Services**: (bullet list)
+- **Customer Segments**: (who they sell to)
+- **Headquarters**:
+- **Other Locations**:
+- **Founded Year**:
+- **Employee Count**:
+- **Revenue Estimate**:
+- **Company Growth Rate**:
+- **Ownership Type**: (Public / Private / PE-backed / etc.)
+- **Parent Company**:
+- **Funding History**: (rounds, amounts, investors)
+- **Tech Stack**: (known tools, platforms, languages)
+
+---
+
+# Company Health & Growth Signals
+
+- **Recent Revenue Growth**:
+- **Recent Funding**:
+- **Profitability Indicators**:
+- **Expansion Plans**:
+- **Market Position**: (leader / challenger / niche)
+- **Key Competitors**:
+
+---
+
+# Trigger Events
+
+Search for recent news (last 12 months) and fill each. Pay special attention to signals relevant to
+OUR COMPANY's offering as described above — i.e. trigger events that would plausibly increase or decrease
+{company_name}'s need for what OUR COMPANY sells:
+
+- **Funding Event**:
+- **Acquisition**:
+- **Merger**:
+- **New Product Launch**:
+- **Executive Hire**:
+- **Executive Departure**:
+- **Office Expansion**:
+- **International Expansion**:
+- **Job Postings Surge**:
+- **Layoffs**:
+- **Digital Transformation Initiative**:
+- **Partnership Announcement**:
+- **Compliance / Regulatory Changes**:
+- **Earnings Report**:
+- **Major Customer Win**:
+- **Major Customer Loss**:
+- **New Facility / Production Line**:
+- **Technology Migration**:
+- **IPO Activity**:
+
+---
+
+# Industry Context
+
+Based on {company_name}'s industry:
+
+- **Industry Trends**:
+- **Industry Growth Rate**:
+- **Emerging Technologies**:
+- **Labor Market Conditions**:
+- **Regulatory Pressures**:
+- **Competitive Pressures**:
+- **Economic Factors**:
+- **Common Industry Challenges**:
+
+---
+
+{search_results_context}
+
+# Decision Makers
+
+First, based on OUR COMPANY's context above (what is being sold, deal size, purchase frequency, and who
+typically owns this kind of buying decision), infer which job titles/functions at {company_name} are most
+likely to be the actual buyers or influencers for OUR COMPANY's offering. Then search (via web search,
+LinkedIn, company "About/Team" pages, and job postings) for real people at {company_name} holding those
+titles.
+
+If a "PRE-FETCHED SEARCH RESULTS" section appears above with content, treat it as your primary evidence
+for this section and the Contact Prioritization section below: extract real names, titles, and LinkedIn
+URLs directly from those results first. Use your own web search only to fill gaps, verify ambiguous or
+conflicting results, or find fields the pre-fetched results don't cover (e.g. email, phone). Do not mention
+in your output that some evidence was pre-fetched — just fill in the fields as instructed below.
+
+List the top 5–7 most relevant people found, prioritizing the roles most likely to own or influence this
+specific purchase over generic executives, unless OUR COMPANY's context indicates this is genuinely a
+senior/strategic sale. For each:
+
+**Person 1:**
+- Name:
+- Title:
+- Department:
+- Seniority Level:
+- LinkedIn URL:
+- Email (if available):
+- Phone (if available):
+
+(repeat for each person found)
+
+If the ideal roles can't be found publicly, fall back to the most relevant person available and note
+this explicitly.
+
+---
+
+# Contact Prioritization
+
+# Contact Prioritization
+
+Based on OUR COMPANY's context above (what's being sold, typical deal size, and purchase pattern), reason
+through the right outreach strategy at {company_name}:
+
+- **Primary Contact**: (the person most likely to own this buying decision, given what OUR COMPANY sells)
+- **Primary Contact Reason**:
+- **Secondary Contact**: (an influencer or alternate budget holder)
+- **Secondary Contact Reason**:
+- **Tertiary Contact**: (a backup option, e.g. relevant for multi-site or specific organizational structures)
+- **Tertiary Contact Reason**:
+- **Too Senior To Cold Contact**: (name/title if found)
+- **Reason**: (explain, based on OUR COMPANY's offering and typical deal size/frequency, why this person
+  is the wrong first point of contact, and why the contacts above are the right entry point instead)
+
+---
+
+Use web search extensively to find the most current and accurate information. Be specific with numbers,
+dates, and sources where possible. Throughout, keep OUR COMPANY's offering in mind so the profile is
+immediately actionable for outreach.
+"""
+
+def load_seller_context(path: str) -> str:
+    """Load the seller's own company context from company.md, re-read fresh each run."""
+    if not os.path.exists(path):
+        print(f"⚠️  Warning: {path} not found. Proceeding without seller context.")
+        return "(No seller context provided — company.md was not found.)"
+
+    with open(path, "r", encoding="utf-8") as f:
+        content = f.read().strip()
+
+    if not content:
+        print(f"⚠️  Warning: {path} is empty. Proceeding without seller context.")
+        return "(No seller context provided — company.md was empty.)"
+
+    return content
+
+def load_search_results(path: str | None) -> dict | None:
+    """Load combined_results.json produced by run_pipeline.py (query -> list of
+    parsed Google result dicts). Returns None if no path/file is available so the
+    caller can proceed without it."""
+    if not path:
+        return None
+    if not os.path.exists(path):
+        print(f"ℹ️  No search-results file found at {path} — proceeding without pre-fetched results.")
+        return None
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        print(f"⚠️  Warning: could not read/parse {path} ({e}). Proceeding without pre-fetched results.")
+        return None
+
+    if not isinstance(data, dict) or not data:
+        print(f"⚠️  Warning: {path} is empty or not in the expected {{query: [...]}} shape. "
+              f"Proceeding without pre-fetched results.")
+        return None
+
+    return data
+
+TRACKING_PARAMS = {
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+    "fbclid",
+    "gclid",
+    "igshid",
+    "mc_cid",
+    "mc_eid",
+}
+
+def compact_url(url: str) -> str:
+    parsed = urlparse(url.strip())
+    if not parsed.scheme or not parsed.netloc:
+        return url.strip()
+
+    query = urlencode([
+        (key, value)
+        for key, value in parse_qsl(parsed.query, keep_blank_values=True)
+        if key.lower() not in TRACKING_PARAMS
+    ])
+    path = parsed.path.rstrip("/") or "/"
+    return urlunparse((parsed.scheme, parsed.netloc.lower(), path, "", query, ""))
+
+def result_score(result: dict) -> int:
+    text = " ".join(
+        str(result.get(key) or "").lower()
+        for key in ("title", "url", "byline", "snippet")
+    )
+    score = 0
+    if "linkedin.com/in" in text:
+        score += 8
+    elif "linkedin.com" in text:
+        score += 5
+    if any(term in text for term in ("procurement", "purchase", "supply chain", "facility", "facilities", "admin")):
+        score += 4
+    if any(term in text for term in ("manager", "head", "director", "vp", "chief", "officer")):
+        score += 3
+    if any(term in text for term in ("email", "phone", "contact")):
+        score += 2
+    return score
+
+def trim_text(value: str, limit: int) -> str:
+    text = " ".join(str(value or "").split())
+    if len(text) <= limit:
+        return text
+    return text[:limit].rsplit(" ", 1)[0].rstrip(".,;:") + "..."
+
+def compact_search_results(data: dict | None, max_results_per_query: int, max_total_results: int) -> dict:
+    if not data:
+        return {}
+
+    rows = []
+    for query_index, (query, results) in enumerate(data.items()):
+        if not isinstance(results, list):
+            continue
+        for result_index, result in enumerate(results):
+            if not isinstance(result, dict):
+                continue
+            url = compact_url(str(result.get("url") or ""))
+            if not url:
+                continue
+            rows.append((
+                result_score(result),
+                query_index,
+                result_index,
+                query,
+                {
+                    "title": trim_text(result.get("title", ""), 120),
+                    "url": url,
+                    "byline": trim_text(result.get("byline", ""), 120),
+                    "followers": trim_text(result.get("followers", ""), 80),
+                    "snippet": trim_text(result.get("snippet", ""), 260),
+                },
+            ))
+
+    seen_urls = set()
+    compacted = {}
+    kept_total = 0
+    rows.sort(key=lambda row: (-row[0], row[1], row[2]))
+
+    for _score, _query_index, _result_index, query, result in rows:
+        if kept_total >= max_total_results:
+            break
+        if result["url"] in seen_urls:
+            continue
+        bucket = compacted.setdefault(query, [])
+        if len(bucket) >= max_results_per_query:
+            continue
+        bucket.append(result)
+        seen_urls.add(result["url"])
+        kept_total += 1
+
+    return {query: compacted[query] for query in data if query in compacted}
+
+def format_search_results(data: dict | None, max_results_per_query: int = 4, max_chars: int = 9000) -> str:
+    """Render combined_results.json into a compact, readable text block the model
+    can use as grounding evidence for the Decision Makers / Contact Prioritization
+    sections. Truncates defensively so a large results file can't blow out the
+    prompt budget."""
+    if not data:
+        return "=== PRE-FETCHED SEARCH RESULTS ===\n(None provided for this run — rely on your own web search.)\n=== END PRE-FETCHED SEARCH RESULTS ==="
+
+    data = compact_search_results(data, max_results_per_query=max_results_per_query, max_total_results=28)
+
+    lines = ["=== PRE-FETCHED SEARCH RESULTS (from prior decision-maker search queries) ===",
+             "These are raw Google results already collected for this target company. Mine them for real "
+             "names, titles, and LinkedIn URLs before doing additional searches.\n"]
+
+    for query, results in data.items():
+        lines.append(f"Query: {query}")
+        if not results:
+            lines.append("  (no results)")
+            lines.append("")
+            continue
+        for r in results[:max_results_per_query]:
+            title = (r.get("title") or "").strip()
+            url = (r.get("url") or "").strip()
+            byline = (r.get("byline") or "").strip()
+            snippet = (r.get("snippet") or "").strip()
+            lines.append(f"  - {title}")
+            if url:
+                lines.append(f"    URL: {url}")
+            if byline:
+                lines.append(f"    {byline}")
+            if snippet:
+                lines.append(f"    {snippet}")
+        lines.append("")
+
+    lines.append("=== END PRE-FETCHED SEARCH RESULTS ===")
+
+    text = "\n".join(lines)
+    if len(text) > max_chars:
+        text = text[:max_chars] + "\n... [truncated for length] ...\n=== END PRE-FETCHED SEARCH RESULTS ==="
+    return text
+
+def research_company(company_name: str, company_md_path: str, search_results_path: str | None = None) -> str:
+    """Research a target company using Gemini 2.5 Flash with Google Search grounding,
+    tailored using the seller's own context loaded fresh from company.md, and grounded
+    further (for the Decision Makers / Contact Prioritization sections) using any
+    pre-fetched search results from run_pipeline.py's combined_results.json."""
+
+def research_company_claude_fallback(prompt: str) -> str:
+    import anthropic
+    api_key = os.getenv("ANTHROPIC_API_KEY", "").strip()
+    if not api_key:
+        raise ValueError("ANTHROPIC_API_KEY is not configured.")
+    client = anthropic.Anthropic(api_key=api_key)
+
+    system_prompt = "You are a world-class B2B sales intelligence researcher. Provide detailed, well-structured answers."
+    tools = [{"type": "web_search_20250305", "name": "web_search"}]
+
+    messages = [{"role": "user", "content": prompt}]
+    full_response = ""
+    continuation_count = 0
+    max_continuations = 5
+
+    while True:
+        response = client.messages.create(
+            model="claude-haiku-4-5",
+            max_tokens=4000,
+            system=system_prompt,
+            messages=messages,
+            tools=tools
+        )
+
+        for block in response.content:
+            if block.type == "text":
+                full_response += block.text
+
+        stop_reason = response.stop_reason
+
+        if stop_reason == "end_turn":
+            break
+        elif stop_reason == "max_tokens":
+            continuation_count += 1
+            if continuation_count >= max_continuations:
+                break
+            messages.append({"role": "assistant", "content": response.content})
+            messages.append({"role": "user", "content": "Your previous response was cut off. Please continue exactly from where you left off."})
+        elif stop_reason == "pause_turn":
+            continuation_count += 1
+            if continuation_count >= max_continuations:
+                break
+            messages.append({"role": "assistant", "content": response.content})
+        elif stop_reason == "refusal":
+            break
+        else:
+            break
+
+    return full_response
+
+def research_company(company_name: str, company_md_path: str, search_results_path: str | None = None) -> str:
+    """Research a target company using Gemini 2.5 Flash with Google Search grounding,
+    tailored using the seller's own context loaded fresh from company.md, and grounded
+    further (for the Decision Makers / Contact Prioritization sections) using any
+    pre-fetched search results from run_pipeline.py's combined_results.json."""
+
+    seller_context = load_seller_context(company_md_path)
+    search_results_data = load_search_results(search_results_path)
+    search_results_context = format_search_results(search_results_data)
+
+    print(f"\n🔍 Researching: {company_name}")
+    print(f"📄 Seller context loaded from: {company_md_path}")
+    if search_results_data:
+        total_queries = len(search_results_data)
+        total_hits = sum(len(v) for v in search_results_data.values())
+        print(f"🗂️  Pre-fetched search results loaded from: {search_results_path} "
+              f"({total_queries} queries, {total_hits} results)")
+    else:
+        print("🗂️  No pre-fetched search results loaded — relying on ProspectIQ AI's own web search.")
+    print("=" * 60)
+    print("Initializing ProspectIQ AI Engine with web search...\n")
+
+    google_search_tool = Tool(google_search=GoogleSearch())
+
+    prompt = RESEARCH_PROMPT.format(
+        company_name=company_name,
+        seller_context=seller_context,
+        search_results_context=search_results_context,
+    )
+
+    print("🌐 Running web searches and compiling profile...\n")
+
+    keys = get_all_paid_gemini_api_keys()
+    if not keys:
+        raise ValueError("Limit reached try after 5 minutes please contact admin")
+
+    last_err = None
+    for api_key in keys:
+        try:
+            client = genai.Client(api_key=api_key)
+            response = client.models.generate_content(
+                model="gemini-2.5-flash",
+                contents=prompt,
+                config=GenerateContentConfig(
+                    tools=[google_search_tool],
+                    temperature=0.2,
+                    service_tier=ServiceTier.PRIORITY,
+                ),
+            )
+            return response.text
+        except Exception as e:
+            last_err = e
+            continue
+
+    try:
+        return research_company_claude_fallback(prompt)
+    except Exception:
+        pass
+
+    raise RuntimeError("Limit reached try after 5 minutes please contact admin")
+
+def save_report(company_name: str, content: str, output_format: str = "md"):
+    """Save the research report to a file."""
+    safe_name = company_name.lower().replace(" ", "_").replace("/", "-")
+    filename = f"{safe_name}_profile.{output_format}"
+    output_path = os.path.join(os.getcwd(), filename)
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        if output_format == "md":
+            f.write(f"# Company Research: {company_name}\n\n")
+        f.write(content)
+
+    return output_path
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Research a target company using Gemini 2.5 Flash + Web Search, "
+                     "tailored to your own business context in company.md",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python company_research.py "Infosys"
+  python company_research.py "Wipro" --output txt
+  python company_research.py "TCS" --no-save
+  python company_research.py "Zoho" --company-md /path/to/company.md
+  python company_research.py "Acme Manufacturing" --search-results ./pipeline_output/combined_results.json
+        """
+    )
+    parser.add_argument(
+        "company_name",
+        type=str,
+        help="Name of the TARGET company to research (your prospect)"
+    )
+    parser.add_argument(
+        "--output",
+        choices=["md", "txt"],
+        default="md",
+        help="Output file format (default: md)"
+    )
+    parser.add_argument(
+        "--no-save",
+        action="store_true",
+        help="Print to stdout only, don't save to file"
+    )
+    parser.add_argument(
+        "--company-md",
+        type=str,
+        default=DEFAULT_COMPANY_MD_PATH,
+        help=f"Path to your own company.md context file (default: {DEFAULT_COMPANY_MD_PATH}). "
+             f"Re-read fresh on every run, so edit it anytime before running."
+    )
+    parser.add_argument(
+        "--search-results",
+        type=str,
+        default=DEFAULT_SEARCH_RESULTS_PATH,
+        help=f"Path to a combined_results.json produced by run_pipeline.py "
+             f"(default: {DEFAULT_SEARCH_RESULTS_PATH}). Used as grounding evidence for the "
+             f"Decision Makers / Contact Prioritization sections. Missing file is fine — "
+             f"the script falls back to Gemini's own web search."
+    )
+    parser.add_argument(
+        "--no-search-results",
+        action="store_true",
+        help="Ignore any combined_results.json and rely entirely on Gemini's own web search."
+    )
+
+    args = parser.parse_args()
+
+    try:
+        search_results_path = None if args.no_search_results else args.search_results
+        result = research_company(args.company_name, args.company_md, search_results_path)
+
+        print(result)
+        print("\n" + "=" * 60)
+
+        if not args.no_save:
+            saved_path = save_report(args.company_name, result, args.output)
+            print(f"\n✅ Report saved to: {saved_path}")
+
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        if "api_key" in str(e).lower() or "api key" in str(e).lower():
+            print("Check that your GEMINI_API_KEY_prime_1/2/3 values are valid in the .env file.")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

services/research/browser.py

@@ -0,0 +1,275 @@
+"""
+Google Search via Selenium + ChromeDriver.
+
+Usage:
+    python browser.py "spaceship titanic kaggle"
+    python browser.py --headless "pytorch tutorial"
+    python browser.py
+"""
+
+import argparse
+import os
+import shutil
+import sys
+import time
+import threading
+import tempfile
+from urllib.parse import parse_qs, quote_plus, urlparse
+
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+from selenium.webdriver.chrome.service import Service
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import WebDriverWait
+from webdriver_manager.chrome import ChromeDriverManager
+
+GOOGLE_URL = "https://www.google.com"
+_CHROMEDRIVER_PATH = ""
+_DRIVER_PATH_LOCK = threading.Lock()
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+def normalize_google_url(url: str) -> str:
+    """Return the destination URL for Google redirect links."""
+    parsed = urlparse(url)
+    if parsed.netloc.endswith("google.com") and parsed.path == "/url":
+        target = parse_qs(parsed.query).get("q", [""])[0]
+        if target:
+            return target
+    return url
+
+def is_search_result_url(url: str) -> bool:
+    if not url:
+        return False
+
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        return False
+
+    blocked_hosts = {
+        "accounts.google.com",
+        "maps.google.com",
+        "policies.google.com",
+        "support.google.com",
+        "www.google.com",
+    }
+    return parsed.netloc.lower() not in blocked_hosts
+
+def build_driver(headless: bool = False) -> webdriver.Chrome:
+    options = Options()
+    options.page_load_strategy = "eager"
+    chrome_bin = os.environ.get("CHROME_BIN") or os.environ.get("GOOGLE_CHROME_BIN")
+    if chrome_bin:
+        options.binary_location = chrome_bin
+
+    if headless:
+        options.add_argument("--headless=new")
+        options.add_argument("--window-size=1920,1080")
+
+    options.add_argument("--no-sandbox")
+    options.add_argument("--disable-dev-shm-usage")
+    options.add_argument("--disable-gpu")
+    options.add_argument("--disable-extensions")
+    options.add_argument("--disable-background-networking")
+    options.add_argument("--disable-default-apps")
+    options.add_argument("--disable-sync")
+    options.add_argument("--metrics-recording-only")
+    options.add_argument("--mute-audio")
+    options.add_argument("--no-first-run")
+    options.add_argument("--remote-debugging-port=0")
+    options.add_argument("--disable-blink-features=AutomationControlled")
+    user_data_dir = tempfile.mkdtemp(prefix="prospectiq-chrome-")
+    options.add_argument(f"--user-data-dir={user_data_dir}")
+    options.add_experimental_option("excludeSwitches", ["enable-automation"])
+    options.add_experimental_option("useAutomationExtension", False)
+    options.add_argument(
+        "user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/124.0.0.0 Safari/537.36"
+    )
+
+    chromedriver_path = os.environ.get("CHROMEDRIVER_PATH") or get_chromedriver_path()
+    service = Service(chromedriver_path)
+    try:
+        driver = webdriver.Chrome(service=service, options=options)
+        driver._prospectiq_user_data_dir = user_data_dir
+        driver.execute_script(
+            "Object.defineProperty(navigator, 'webdriver', {get: () => undefined})"
+        )
+        return driver
+    except Exception:
+        shutil.rmtree(user_data_dir, ignore_errors=True)
+        raise
+
+def close_driver(driver: webdriver.Chrome | None) -> None:
+    if driver is None:
+        return
+    user_data_dir = getattr(driver, "_prospectiq_user_data_dir", "")
+    try:
+        driver.quit()
+    finally:
+        if user_data_dir:
+            shutil.rmtree(user_data_dir, ignore_errors=True)
+
+def get_chromedriver_path() -> str:
+    global _CHROMEDRIVER_PATH
+    if _CHROMEDRIVER_PATH:
+        return _CHROMEDRIVER_PATH
+    with _DRIVER_PATH_LOCK:
+        if not _CHROMEDRIVER_PATH:
+            _CHROMEDRIVER_PATH = ChromeDriverManager().install()
+    return _CHROMEDRIVER_PATH
+
+def accept_consent(driver: webdriver.Chrome, wait: WebDriverWait) -> None:
+    """Dismiss Google's cookie/consent banner if present."""
+    try:
+        btn = wait.until(EC.element_to_be_clickable(
+            (By.XPATH, "//button[.//div[contains(text(),'Accept all')] or contains(.,'I agree')]")
+        ))
+        btn.click()
+        time.sleep(0.5)
+    except Exception:
+        pass
+
+def google_search(driver: webdriver.Chrome, query: str, limit: int = 3) -> list[dict]:
+    """Open Google, run the query, return up to `limit` organic results."""
+    driver.get(f"{GOOGLE_URL}/search?q={quote_plus(query)}&num={max(limit, 3)}")
+    print(f"\n  [browser] Opened: {driver.current_url}")
+
+    wait = WebDriverWait(driver, 8)
+    accept_consent(driver, wait)
+
+    wait.until(EC.url_contains("google.com/search"))
+    print(f"  [browser] Results page: {driver.current_url}")
+
+    wait.until(EC.presence_of_element_located((By.ID, "search")))
+    time.sleep(0.25)
+
+    results = []
+    seen_urls = set()
+
+    links = driver.find_elements(By.XPATH, "//a[@href][.//h3]")
+    for link in links:
+        if len(results) >= limit:
+            break
+        try:
+            title = link.find_element(By.XPATH, ".//h3").text.strip()
+            url = normalize_google_url(link.get_attribute("href"))
+
+            if not title or not is_search_result_url(url) or url in seen_urls:
+                continue
+
+            ancestor_divs = link.find_elements(By.XPATH, "./ancestor::div")
+            ancestor_divs.reverse()
+
+            container = link
+            for div in ancestor_divs:
+                h3_count = len(div.find_elements(By.TAG_NAME, "h3"))
+                if h3_count == 0:
+                    continue
+                if h3_count == 1:
+                    container = div
+                else:
+                    break
+
+            raw_text = container.text.strip()
+            all_lines = []
+            for line in raw_text.splitlines():
+                line = line.strip()
+                if line and line != title and line not in all_lines:
+                    all_lines.append(line)
+
+            byline = ""
+            followers = ""
+            description_lines = []
+            for line in all_lines:
+                if not byline and ("linkedin" in line.lower() or "·" in line or "·" in line):
+                    byline = line
+                    continue
+                if not followers and "follower" in line.lower():
+                    followers = line
+                    continue
+                description_lines.append(line)
+
+            snippet = " ".join(description_lines).replace("Read more", "").strip()
+            results.append({
+                "title": title,
+                "url": url,
+                "byline": byline,
+                "followers": followers,
+                "snippet": snippet,
+                "raw_lines": all_lines,
+            })
+            seen_urls.add(url)
+        except Exception:
+            continue
+
+    return results
+
+def print_results(query: str, results: list[dict]) -> None:
+    sep = "=" * 70
+    print(f"\n{sep}")
+    print(f"  Google results for: \"{query}\"")
+    print(f"{sep}\n")
+    if not results:
+        print("  No results parsed - Google may have changed its HTML structure.")
+        return
+
+    def wrap(text: str, width: int = 66, indent: str = "       ") -> None:
+        words, line = text.split(), []
+        for word in words:
+            if sum(len(item) + 1 for item in line) + len(word) > width:
+                print(indent + " ".join(line))
+                line = [word]
+            else:
+                line.append(word)
+        if line:
+            print(indent + " ".join(line))
+
+    for index, result in enumerate(results, 1):
+        print(f"  [{index}] {result['title']}")
+        print(f"       URL: {result['url']}")
+        if result.get("byline"):
+            print(f"       {result['byline']}")
+        if result.get("followers"):
+            print(f"       {result['followers']}")
+        if result.get("snippet"):
+            print()
+            wrap(result["snippet"])
+        print(f"\n  {'-' * 66}\n")
+
+def interactive_loop(driver: webdriver.Chrome) -> None:
+    print("\n  Google Search - type 'exit' to quit\n")
+    while True:
+        try:
+            query = input("  Query: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if not query:
+            continue
+        if query.lower() in {"exit", "quit", "q"}:
+            break
+        results = google_search(driver, query)
+        print_results(query, results)
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Search Google via Selenium")
+    parser.add_argument("query", nargs="?", help="Search query (omit for interactive mode)")
+    parser.add_argument("--headless", action="store_true", help="Run without a visible browser window")
+    parser.add_argument("--limit", type=int, default=3, help="Max results (default: 3)")
+    args = parser.parse_args()
+
+    driver = build_driver(headless=args.headless)
+    try:
+        if args.query:
+            results = google_search(driver, args.query, limit=args.limit)
+            print_results(args.query, results)
+        else:
+            interactive_loop(driver)
+    finally:
+        close_driver(driver)
+
+if __name__ == "__main__":
+    main()

services/research/company.md

@@ -0,0 +1,27 @@
+# Company Knowledge Base - Drinking Water Can Supply Business
+
+# About Us
+
+We are an India-based B2B drinking water supply company specializing in the manufacturing and distribution of high-quality packaged drinking water in reusable 20-litre water cans. Our primary focus is supplying businesses and organizations that require a continuous, reliable, and hygienic source of drinking water for their employees, workers, visitors, and guests.
+
+Unlike retail bottled water brands, we operate on a recurring business model where customers receive scheduled deliveries of water cans based on their daily or weekly consumption.
+
+Our objective is to become the preferred drinking water supplier for organizations with medium to large workforce requirements.
+
+---
+
+# What We Do
+
+We manufacture purified drinking water that complies with Indian drinking water quality standards.
+
+We supply:
+
+* 20L reusable drinking water cans
+* Bulk drinking water supply
+* Scheduled recurring deliveries
+* Emergency water deliveries
+* Long-term corporate supply contracts
+* Multi-location water supply solutions
+
+We ensure consistent quality, timely deliveries, and uninterrupted supply.
+

services/research/pipeline.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""
+full_pipeline.py
+
+ONE command that runs the entire chain:
+
+    generate_search_queries.py  -->  browser_search.py  -->  company_research.py
+
+1. Gemini generates N pinpoint decision-maker search queries for the client company.
+2. Every query is run through headless Google search (Selenium), with a randomized
+   delay between searches.
+3. The combined search results are fed straight into Gemini (company_research.py's
+   research_company()) as grounding evidence for the Decision Makers / Contact
+   Prioritization sections of the profile.
+4. The final profile is saved to disk.
+
+Everything lands in one output folder -- no manual copy-pasting of paths between
+steps, no second command to run.
+
+Usage:
+    python full_pipeline.py \
+        --company company.md \
+        --client-company "Prestige Constructions India" \
+        --questions questionlist.md \
+        --out-dir ./pipeline_output
+
+That single command replaces:
+    python run_pipeline.py --company company.md --client-company "..." --questions questionlist.md --out-dir ./pipeline_output
+    python company_research.py "..." --search-results ./pipeline_output/combined_results.json
+
+Requires generate_search_queries.py, browser_search.py, and company_research.py to
+sit next to this script (or be on PYTHONPATH). Same dependencies as before:
+    pip install google-genai selenium webdriver-manager python-dotenv --break-system-packages
+Plus GEMINI_API_KEY_prime_1, GEMINI_API_KEY_prime_2, or GEMINI_API_KEY_prime_3
+available via env vars or a .env file (used for both the query-generation step
+and the research step).
+"""
+
+import sys
+import time
+import random
+import argparse
+import re
+import json
+import concurrent.futures
+import os
+from pathlib import Path
+
+import query_generator as qgen
+import browser as bsearch
+import analyzer as crsrch
+
+def elapsed(start: float) -> str:
+    seconds = time.perf_counter() - start
+    return f"{seconds:.1f}s"
+
+# --------------------------------------------------------------------------- #
+# Step 1: Gemini query generation
+# --------------------------------------------------------------------------- #
+
+def generate_queries(args) -> dict:
+    company_md = qgen.read_file(args.company)
+    questionlist_md = qgen.read_file(args.questions)
+    sections = qgen.parse_questionlist(questionlist_md)
+
+    system_prompt = qgen.build_system_prompt(args.num_queries)
+    user_prompt = qgen.build_user_prompt(company_md, args.client_company, questionlist_md, sections)
+
+    print(f"[1/4] Calling ProspectIQ AI Engine to generate {args.num_queries} queries...", file=sys.stderr)
+    raw = qgen.call_gemini(system_prompt, user_prompt)
+
+    data = qgen.extract_json(raw)
+    qgen.validate_queries(data, args.num_queries)
+    return data
+
+# --------------------------------------------------------------------------- #
+# Step 2: headless browser search
+# --------------------------------------------------------------------------- #
+
+def slugify(text: str, max_len: int = 60) -> str:
+    text = text.lower().strip()
+    text = re.sub(r"[^a-z0-9]+", "_", text)
+    text = re.sub(r"_+", "_", text).strip("_")
+    return text[:max_len] or "query"
+
+def run_single_browser_search(index: int, total: int, query: str, results_per_query: int) -> tuple[int, str, list, str]:
+    driver = None
+    try:
+        driver = bsearch.build_driver(headless=True)
+        print(f"  -> ({index}/{total}) {query}", file=sys.stderr)
+        results = bsearch.google_search(driver, query, limit=results_per_query)
+        return index, query, results, ""
+    except Exception as exc:
+        return index, query, [], str(exc)
+    finally:
+        bsearch.close_driver(driver)
+
+def run_browser_searches(queries: list, out_dir: Path, results_per_query: int,
+                         min_delay: float, max_delay: float, parallel_searches: int = 1) -> tuple[dict, dict]:
+    results_dir = out_dir / "results"
+    results_dir.mkdir(parents=True, exist_ok=True)
+
+    combined = {}
+    errors = {}
+
+    total = len(queries)
+    parallel_searches = max(1, min(int(parallel_searches or 1), total or 1))
+    if parallel_searches == 1:
+        print("[2/4] Launching headless Chrome...", file=sys.stderr)
+        driver = None
+        try:
+            driver = bsearch.build_driver(headless=True)
+            for i, query in enumerate(queries, start=1):
+                print(f"  -> ({i}/{total}) {query}", file=sys.stderr)
+                try:
+                    results = bsearch.google_search(driver, query, limit=results_per_query)
+                    combined[query] = results
+
+                    fname = f"{i:02d}_{slugify(query)}.json"
+                    (results_dir / fname).write_text(
+                        json.dumps({"query": query, "results": results}, indent=2),
+                        encoding="utf-8",
+                    )
+                except Exception as e:
+                    print(f"     ! failed: {e}", file=sys.stderr)
+                    errors[query] = str(e)
+                    combined[query] = []
+
+                if i < total and max_delay > 0:
+                    time.sleep(random.uniform(max(0, min_delay), max_delay))
+        except Exception as e:
+            print(f"     ! browser startup failed: {e}", file=sys.stderr)
+            for query in queries:
+                errors[query] = str(e)
+                combined[query] = []
+        finally:
+            bsearch.close_driver(driver)
+        return combined, errors
+
+    print(f"[2/4] Launching {parallel_searches} parallel headless Chrome workers...", file=sys.stderr)
+    indexed_results: dict[int, tuple[str, list, str]] = {}
+    with concurrent.futures.ThreadPoolExecutor(max_workers=parallel_searches) as executor:
+        futures = {
+            executor.submit(run_single_browser_search, i, total, query, results_per_query): (i, query)
+            for i, query in enumerate(queries, start=1)
+        }
+        for future in concurrent.futures.as_completed(futures):
+            fallback_i, fallback_query = futures[future]
+            try:
+                i, query, results, error = future.result()
+            except Exception as exc:
+                i, query, results, error = fallback_i, fallback_query, [], str(exc)
+            indexed_results[i] = (query, results, error)
+            if error:
+                print(f"     ! ({i}/{total}) failed: {error}", file=sys.stderr)
+
+    for i in sorted(indexed_results):
+        query, results, error = indexed_results[i]
+        combined[query] = results
+        if error:
+            errors[query] = error
+        fname = f"{i:02d}_{slugify(query)}.json"
+        (results_dir / fname).write_text(
+            json.dumps({"query": query, "results": results}, indent=2),
+            encoding="utf-8",
+        )
+
+    return combined, errors
+
+def render_combined_markdown(combined: dict) -> str:
+    lines = ["# Combined Search Results\n"]
+    for query, results in combined.items():
+        lines.append(f"## {query}\n")
+        if not results:
+            lines.append("_No results parsed._\n")
+            continue
+        for i, r in enumerate(results, start=1):
+            lines.append(f"{i}. **{r.get('title', '')}**")
+            lines.append(f"   - URL: {r.get('url', '')}")
+            if r.get("byline"):
+                lines.append(f"   - {r['byline']}")
+            if r.get("followers"):
+                lines.append(f"   - {r['followers']}")
+            if r.get("snippet"):
+                lines.append(f"   - {r['snippet']}")
+            lines.append("")
+    return "\n".join(lines)
+
+# --------------------------------------------------------------------------- #
+# Step 3: Gemini research, grounded with the combined results
+# --------------------------------------------------------------------------- #
+
+def run_research(client_company: str, company_md_path: str, combined_results_path: Path) -> str:
+    print("[3/4] Calling ProspectIQ AI Engine to compile the profile...", file=sys.stderr)
+    return crsrch.research_company(
+        company_name=client_company,
+        company_md_path=company_md_path,
+        search_results_path=str(combined_results_path),
+    )
+
+# --------------------------------------------------------------------------- #
+# Main
+# --------------------------------------------------------------------------- #
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="One-shot pipeline: generate search queries -> run them headlessly -> "
+        "feed results into Gemini to produce a sales intelligence profile."
+    )
+    # query generation
+    parser.add_argument("--company", default="company.md", help="Path to your seller/vendor profile markdown")
+    parser.add_argument("--client-company", required=True, help="Exact client/target company name")
+    parser.add_argument("--questions", default="questionlist.md", help="Path to fixed question schema markdown")
+    parser.add_argument("--num-queries", type=int, default=8, help="Number of search queries to generate (default: 8)")
+
+    # browser search
+    parser.add_argument("--results-per-query", type=int, default=4, help="Max Google results to keep per query")
+    parser.add_argument("--min-delay", type=float, default=3.0, help="Min seconds between searches")
+    parser.add_argument("--max-delay", type=float, default=7.0, help="Max seconds between searches")
+    parser.add_argument(
+        "--parallel-searches",
+        type=int,
+        default=int(os.environ.get("COMPANY_EXTRACTOR_PARALLEL_SEARCHES", "6")),
+        help="Number of headless browser searches to run at once",
+    )
+
+    # output / research
+    parser.add_argument("--out-dir", default="pipeline_output", help="Folder to store everything, including the final profile")
+    parser.add_argument("--report-format", choices=["md", "txt"], default="md", help="Final profile file format (default: md)")
+
+    args = parser.parse_args()
+
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Step 1
+    step_start = time.perf_counter()
+    data = generate_queries(args)
+    print(f"      Query generation completed in {elapsed(step_start)}", file=sys.stderr)
+    queries = data["queries"]
+    (out_dir / "queries.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
+    (out_dir / "queries.md").write_text(qgen.render_markdown_report(data), encoding="utf-8")
+
+    # Step 2
+    step_start = time.perf_counter()
+    combined, errors = run_browser_searches(
+        queries, out_dir,
+        results_per_query=args.results_per_query,
+        min_delay=args.min_delay,
+        max_delay=args.max_delay,
+        parallel_searches=args.parallel_searches,
+    )
+    print(f"      Browser evidence collection completed in {elapsed(step_start)}", file=sys.stderr)
+    combined_results_path = out_dir / "combined_results.json"
+    combined_results_path.write_text(json.dumps(combined, indent=2), encoding="utf-8")
+    (out_dir / "combined_results.md").write_text(render_combined_markdown(combined), encoding="utf-8")
+    if errors:
+        (out_dir / "errors.json").write_text(json.dumps(errors, indent=2), encoding="utf-8")
+        print(f"      {len(errors)} quer{'y' if len(errors) == 1 else 'ies'} failed -> {out_dir / 'errors.json'}",
+              file=sys.stderr)
+
+    # Step 3
+    try:
+        step_start = time.perf_counter()
+        profile_text = run_research(args.client_company, args.company, combined_results_path)
+        print(f"      ProspectIQ AI profile synthesis completed in {elapsed(step_start)}", file=sys.stderr)
+    except Exception as e:
+        print(f"\n❌ ProspectIQ AI research step failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Step 4: save the final profile into the same out-dir
+    print("[4/4] Saving final profile...", file=sys.stderr)
+    safe_name = args.client_company.lower().replace(" ", "_").replace("/", "-")
+    report_path = out_dir / f"{safe_name}_profile.{args.report_format}"
+    with open(report_path, "w", encoding="utf-8") as f:
+        if args.report_format == "md":
+            f.write(f"# Company Research: {args.client_company}\n\n")
+        f.write(profile_text)
+
+    print(f"\n✅ Done. Everything is in: {out_dir.resolve()}")
+    print(f"   Queries           : {out_dir / 'queries.json'}")
+    print(f"   Combined results  : {combined_results_path}")
+    print(f"   Final profile     : {report_path}")
+
+if __name__ == "__main__":
+    main()

services/research/query_generator.py

@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""
+generate_search_queries.py
+
+Reads a vendor knowledge-base file (company.md, content varies per run), the
+name of a CLIENT COMPANY you actually want decision-maker contacts at, and a
+FIXED question schema (questionlist.md). Uses Gemini 2.5 Flash to emit exactly
+N (default 10) ready-to-paste-into-Google queries, targeted at that specific
+client company, which collectively are enough to answer every field in
+questionlist.md (decision-maker identification + contact prioritization) --
+informed by the vendor's product/ICP so the right job titles/departments get
+targeted.
+
+No reasoning or persona justification is included in the output -- just the
+queries themselves, since these are meant to be run directly as web searches.
+
+company.md is expected to change between runs (different vendor businesses).
+questionlist.md is expected to stay fixed (same data schema every time), but
+the parser does not hard-code field names, so it still works if the schema
+gains/loses fields later.
+
+Usage:
+    python generate_search_queries.py \
+        --company company.md \
+        --client-company "Acme Manufacturing Pvt Ltd" \
+        --questions questionlist.md \
+        --num-queries 10 \
+        --out-json queries_output.json \
+        --out-md queries_output.md
+"""
+
+import os
+import re
+import sys
+import json
+import argparse
+from pathlib import Path
+
+try:
+    from google import genai
+    from google.genai.types import GenerateContentConfig, ServiceTier
+except ImportError:
+    sys.exit(
+        "Missing dependency 'google-genai'. Install with:\n"
+        "    pip install google-genai --break-system-packages"
+    )
+
+MODEL = "gemini-2.5-flash"
+PAID_GEMINI_ENV_NAMES = (
+    "GEMINI_API_KEY_prime_1",
+    "GEMINI_API_KEY_prime_2",
+    "GEMINI_API_KEY_prime_3",
+)
+
+def load_env_file(path: str = ".env") -> None:
+    env_path = Path(path)
+    if not env_path.is_absolute():
+        env_path = Path(__file__).resolve().parent / env_path
+    if not env_path.exists():
+        return
+
+    for line in env_path.read_text(encoding="utf-8-sig").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+
+        key, value = line.split("=", 1)
+        key = key.strip().lstrip("\ufeff")
+        value = value.strip().strip('"').strip("'")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+def get_all_paid_gemini_api_keys() -> list[str]:
+    keys = []
+    for name in PAID_GEMINI_ENV_NAMES:
+        key = os.environ.get(name, "").strip()
+        if key:
+            keys.append(key)
+    return keys
+
+# --------------------------------------------------------------------------- #
+# File / schema helpers
+# --------------------------------------------------------------------------- #
+
+def read_file(path: str) -> str:
+    p = Path(path)
+    if not p.exists():
+        sys.exit(f"File not found: {path}")
+    return p.read_text(encoding="utf-8")
+
+def parse_questionlist(md_text: str) -> dict:
+    """
+    Parses a markdown file of the form:
+
+        # Section Name
+        - Field
+        - Field
+
+        # Another Section
+        - Field
+
+    into {section_name: [field, field, ...]}. No field names are hard-coded,
+    so this keeps working even if questionlist.md is edited later.
+    """
+    sections = {}
+    current = None
+    for line in md_text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        heading = re.match(r"^#+\s*(.+)", line)
+        if heading:
+            current = heading.group(1).strip()
+            sections[current] = []
+            continue
+        bullet = re.match(r"^[-*]\s*(.+)", line)
+        if bullet and current is not None:
+            sections[current].append(bullet.group(1).strip())
+    if not sections:
+        sys.exit("Could not parse any sections/fields out of questionlist.md")
+    return sections
+
+# --------------------------------------------------------------------------- #
+# Prompt construction
+# --------------------------------------------------------------------------- #
+
+def build_system_prompt(num_queries: int) -> str:
+    return (
+        "You are a senior B2B sales-research analyst. You write precise, ready-to-"
+        "paste-into-Google search queries to find named decision-makers at ONE specific "
+        "client company.\n\n"
+        "You will receive:\n"
+        "1. VENDOR PROFILE - a markdown description of the vendor's product, business "
+        "model, and who it typically sells to. This changes between requests and exists "
+        "ONLY so you know which job titles/departments at the client company actually "
+        "decide, influence, or approve buying this kind of product. It is context, not "
+        "the search target.\n"
+        "2. CLIENT COMPANY - the exact name of the company you must find decision-maker "
+        "contacts at. EVERY query you write must be targeted at this named company, not "
+        "at the vendor and not at generic companies.\n"
+        "3. QUESTION SCHEMA - a fixed set of data fields that need to be answered for "
+        "decision-makers at the CLIENT COMPANY (e.g. name, title, department, seniority, "
+        "LinkedIn URL, email, phone, plus which contact is primary/secondary/tertiary/too-"
+        "senior-to-cold-contact). This does not change between requests.\n\n"
+        "Your job:\n"
+        f"- Produce EXACTLY {num_queries} search queries. No more, no fewer.\n"
+        f"- The {num_queries} queries, taken together, must be enough to find and answer "
+        "every field in the QUESTION SCHEMA for the CLIENT COMPANY -- i.e. enough to "
+        "identify the right decision-makers (using the vendor-context job titles/"
+        "departments), their seniority, LinkedIn URL, email, phone, AND to figure out "
+        "who among them is the primary/secondary/tertiary contact and who is too senior "
+        "to cold contact.\n"
+        "- Spread the queries across the different fields/needs of the QUESTION SCHEMA so "
+        "nothing in the schema is left uncoverable; do not waste multiple queries on the "
+        "same narrow need while ignoring others.\n\n"
+        "=== VALID GOOGLE SEARCH SYNTAX -- FOLLOW EXACTLY, THIS IS THE PART YOU KEEP "
+        "GETTING WRONG ===\n"
+        "Google has NO boolean 'AND' keyword and NO 'NOT' keyword. Writing them produces "
+        "queries that return zero results. The ONLY operators that actually work on Google "
+        "are:\n"
+        '  - Quotes for an exact phrase: "Prestige Constructions India"\n'
+        "  - Space between terms means AND implicitly -- never write the word AND.\n"
+        '  - OR (uppercase) only inside parentheses to mean alternatives: ("CEO" OR "COO")\n'
+        "  - A leading minus with NO space to exclude a term: -intern -trainee (never write "
+        "the word NOT)\n"
+        "  - site: immediately followed by a domain, NO space, NO AND after it: "
+        "site:linkedin.com/in\n"
+        "  - site: must sit directly next to the rest of the query with a space, never "
+        "joined to it with the word AND.\n\n"
+        "CORRECT example:\n"
+        '  site:linkedin.com/in "Prestige Constructions India" ("Facilities Manager" OR "Procurement Manager" OR "Administration Manager")\n'
+        "WRONG example (never produce queries shaped like this):\n"
+        '  site:linkedin.com/in AND ("Prestige Constructions India" AND ("Facilities Manager" OR "Procurement Manager"))\n'
+        "The WRONG example is exactly the kind of query you must never write: no literal "
+        "AND, no nesting the whole query inside one giant parenthesis, no wrapping the "
+        "client company name in parentheses with everything else.\n\n"
+        "Other rules:\n"
+        "- Keep each query to a realistic length a human would actually paste into Google "
+        "-- 1 site: operator, 1 quoted company name, at most one OR-group of 2-4 "
+        "alternatives, and at most one trailing -exclusion. Do not stack 3+ OR-groups in a "
+        "single query.\n"
+        "- Each query must be EXACT, PINPOINT, and immediately runnable as-is: use the "
+        "client company's exact name in quotes, relevant job-title synonyms, and site: "
+        "operators (e.g. site:linkedin.com/in) where useful. Never output a vague or "
+        "generic query.\n"
+        "- Do NOT include any reasoning, justification, explanation, persona labels, or "
+        "commentary anywhere in the output. Output ONLY the queries themselves -- they "
+        "are meant to be copy-pasted straight into Google.\n\n"
+        "Respond with STRICT JSON ONLY. No markdown code fences, no commentary before or "
+        "after. Match exactly this shape:\n"
+        "{\n"
+        '  "client_company": "string - exact client company name as given",\n'
+        f'  "queries": ["query1", "query2", ... exactly {num_queries} strings total ...]\n'
+        "}\n"
+    )
+
+def build_user_prompt(company_md: str, client_company: str, questionlist_md: str, sections: dict) -> str:
+    return (
+        f"VENDOR PROFILE (context only - do not target searches at the vendor):\n"
+        f"{company_md.strip()}\n\n"
+        f"CLIENT COMPANY (target every query at this exact company):\n"
+        f"{client_company.strip()}\n\n"
+        f"QUESTION SCHEMA (raw markdown):\n{questionlist_md.strip()}\n\n"
+        f"QUESTION SCHEMA (parsed sections -> fields):\n{json.dumps(sections, indent=2)}\n\n"
+        "Generate the JSON output now."
+    )
+
+# --------------------------------------------------------------------------- #
+# Gemini call
+# --------------------------------------------------------------------------- #
+
+def call_claude_fallback(system_prompt: str, user_prompt: str) -> str:
+    import anthropic
+    api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    if not api_key:
+        raise ValueError("ANTHROPIC_API_KEY is not configured.")
+    client = anthropic.Anthropic(api_key=api_key)
+
+    messages = [{"role": "user", "content": user_prompt}]
+    full_response = ""
+    continuation_count = 0
+    max_continuations = 5
+
+    while True:
+        response = client.messages.create(
+            model="claude-haiku-4-5",
+            max_tokens=4000,
+            system=system_prompt,
+            messages=messages,
+        )
+
+        for block in response.content:
+            if block.type == "text":
+                full_response += block.text
+
+        stop_reason = response.stop_reason
+
+        if stop_reason == "end_turn":
+            break
+        elif stop_reason == "max_tokens":
+            continuation_count += 1
+            if continuation_count >= max_continuations:
+                break
+            messages.append({"role": "assistant", "content": response.content})
+            messages.append({"role": "user", "content": "Your previous response was cut off. Please continue exactly from where you left off."})
+        elif stop_reason == "refusal":
+            break
+        else:
+            break
+
+    return full_response
+
+def call_gemini(system_prompt: str, user_prompt: str) -> str:
+    load_env_file()
+    keys = get_all_paid_gemini_api_keys()
+    if not keys:
+        sys.exit("Limit reached try after 5 minutes please contact admin")
+
+    last_err = None
+    for api_key in keys:
+        try:
+            client = genai.Client(api_key=api_key)
+            resp = client.models.generate_content(
+                model=MODEL,
+                contents=user_prompt,
+                config=GenerateContentConfig(
+                    system_instruction=system_prompt,
+                    temperature=0.3,
+                    max_output_tokens=4000,
+                    service_tier=ServiceTier.STANDARD,
+                ),
+            )
+            return resp.text
+        except Exception as e:
+            last_err = e
+            continue
+
+    try:
+        return call_claude_fallback(system_prompt, user_prompt)
+    except Exception as e:
+        pass
+
+    sys.exit("Limit reached try after 5 minutes please contact admin")
+
+def extract_json(text: str) -> dict:
+    text = text.strip()
+    text = re.sub(r"^```(json)?", "", text).strip()
+    text = re.sub(r"```$", "", text).strip()
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1:
+        raise ValueError("No JSON object found in model output")
+    return json.loads(text[start:end + 1])
+
+def validate_queries(data: dict, num_queries: int) -> None:
+    queries = data.get("queries")
+    if not isinstance(queries, list) or not all(isinstance(q, str) for q in queries):
+        raise ValueError("'queries' must be a list of strings")
+    if len(queries) != num_queries:
+        raise ValueError(f"Expected exactly {num_queries} queries, got {len(queries)}")
+
+# --------------------------------------------------------------------------- #
+# Reporting
+# --------------------------------------------------------------------------- #
+
+def render_markdown_report(data: dict) -> str:
+    lines = [f"# Search Queries - {data.get('client_company', '')}\n"]
+    for i, q in enumerate(data.get("queries", []), start=1):
+        lines.append(f"{i}. {q}")
+    lines.append("")
+    return "\n".join(lines)
+
+# --------------------------------------------------------------------------- #
+# Main
+# --------------------------------------------------------------------------- #
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate a flat list of pinpoint, directly-runnable web search "
+        "queries to find and prioritize decision-maker contacts at a named client "
+        "company, informed by the vendor's product/ICP and a fixed question schema."
+    )
+    parser.add_argument("--company", default="company.md", help="Path to company.md (vendor profile, varies per run)")
+    parser.add_argument("--client-company", required=True, help="Exact name of the client company to find decision-makers at")
+    parser.add_argument("--questions", default="questionlist.md", help="Path to questionlist.md (fixed schema)")
+    parser.add_argument("--num-queries", type=int, default=10, help="Number of queries to generate (default: 10)")
+    parser.add_argument("--out-json", default="queries_output.json", help="Path for JSON output")
+    parser.add_argument("--out-md", default="queries_output.md", help="Path for Markdown report output")
+    args = parser.parse_args()
+
+    company_md = read_file(args.company)
+    questionlist_md = read_file(args.questions)
+    sections = parse_questionlist(questionlist_md)
+
+    system_prompt = build_system_prompt(args.num_queries)
+    user_prompt = build_user_prompt(company_md, args.client_company, questionlist_md, sections)
+
+    print("Calling ProspectIQ AI Engine...", file=sys.stderr)
+    raw = call_gemini(system_prompt, user_prompt)
+
+    try:
+        data = extract_json(raw)
+        validate_queries(data, args.num_queries)
+    except Exception as e:
+        sys.exit(f"Failed to parse/validate model output: {e}\n\nRaw output:\n{raw}")
+
+    Path(args.out_json).write_text(json.dumps(data, indent=2), encoding="utf-8")
+    Path(args.out_md).write_text(render_markdown_report(data), encoding="utf-8")
+
+    print(f"\nSearch queries for: {data.get('client_company')}\n")
+    for i, q in enumerate(data.get("queries", []), start=1):
+        print(f"{i}. {q}")
+
+    print(f"\nSaved JSON   -> {args.out_json}", file=sys.stderr)
+    print(f"Saved Report -> {args.out_md}", file=sys.stderr)
+
+if __name__ == "__main__":
+    main()

services/research/questionlist.md

@@ -0,0 +1,20 @@
+# Decision Makers
+
+- Name
+- Title
+- Department
+- Seniority Level
+- LinkedIn URL
+- Email (if available)
+- Phone (if available)
+
+# Contact Prioritization
+
+- Primary Contact
+- Primary Contact Reason
+- Secondary Contact
+- Secondary Contact Reason
+- Tertiary Contact
+- Tertiary Contact Reason
+- Too Senior To Cold Contact
+- Reason

services/tool_router.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from services.ai_service import new_job, now, update_job
+
+TOOL_ROUTES: dict[str, dict[str, str]] = {
+    "ocr": {
+        "label": "Business Card Parser",
+        "route": "#/ocr",
+        "summary": "Open Business Card Parser to upload a business card or document image.",
+    },
+    "geo": {
+        "label": "Regional Prospecting",
+        "route": "#/geo-finder",
+        "summary": "Find and rank companies by location, category, industry, or coordinates.",
+    },
+    "research": {
+        "label": "Company Research",
+        "route": "#/company-extractor",
+        "summary": "Run company research and generate a structured company profile.",
+    },
+}
+
+def _clean_query(value: Any) -> str:
+    return re.sub(r"\s+", " ", str(value or "")).strip()
+
+def _strip_tool_verbs(query: str, tool: str) -> str:
+    cleaned = query
+    replacements = {
+        "geo": (
+            r"\b(?:use|run|open|start|launch)?\s*(?:geo\s*finder|geo|geographic(?:al)?\s*(?:finder|search|discovery)|map\s*search|nearby\s*(?:company|companies)?)\b",
+            r"\b(?:find|search|discover|rank|list|show me|look for)\b",
+        ),
+        "research": (
+            r"\b(?:use|run|open|start|launch)?\s*(?:company\s*(?:extractor|research|researcher|intelligence|profile|enrichment)|extractor)\b",
+            r"\b(?:research|extract|enrich|profile|analyze|analyse|make a profile for|build a profile for)\b",
+        ),
+        "ocr": (
+            r"\b(?:use|run|open|start|launch)?\s*(?:ocr|business\s*card\s*(?:scanner|scan|ocr|reader)|card\s*(?:scanner|scan|reader)|image\s*(?:ocr|text extraction))\b",
+            r"\b(?:scan|read|extract text from|parse)\b",
+        ),
+    }
+    for pattern in replacements.get(tool, ()):
+        cleaned = re.sub(pattern, " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"^\s*\b(?:for|to|about|on|near|with|using)\b\s*", " ", cleaned, flags=re.I)
+    cleaned = re.sub(r"\b(?:for|to|about|on|near|with|using)\s*$", " ", cleaned, flags=re.I)
+    return _clean_query(cleaned).strip(" .,:;-")
+
+def heuristic_tool_route(query: str) -> dict[str, Any] | None:
+    normalized = _clean_query(query).lower()
+    if not normalized:
+        return None
+
+    is_explicit_crm = bool(re.search(r"\b(?:database|crm|my companies|saved companies|in crm|from crm|in database|from database|add|create|register|insert|save|put|edit|change|update|set|modify|delete|remove|stage|stages|pipeline|new stage|shortlisted|contacted|engaged|proposal|won|paused|tasks?|contacts?|reps?|users?)\b", normalized))
+    if is_explicit_crm:
+        return None
+
+    crm_company_filter = re.search(r"\b(?:show|sow|shwo|list|view|rank|find|get|fetch|all|existing)\b.*\b(?:companies|prospects|records)\b", normalized) and not re.search(
+        r"\b(?:near|nearby|around|within|coordinates|latitude|longitude|geo\s*finder|map search|prospecting|discover new)\b",
+        normalized,
+    )
+    if crm_company_filter:
+        return None
+
+    ocr_terms = ("ocr", "business card", "scan card", "card scan", "extract text", "read image", "image text")
+    business_plural = r"(?:companies|manufacturers|suppliers|vendors|distributors|producers|firms|businesses|factories|plants)"
+    geo_discovery_patterns = (
+        rf"\b(?:top|best|leading|largest|major|biggest)\b.+\b{business_plural}\b.+\b(?:near|nearby|around|within)\b",
+        rf"\b{business_plural}\b.+\b(?:near|nearby|around|within)\b\s+[a-z0-9, .-]+",
+        rf"\b(?:geo\s*finder|map\s*search|discover\s+new\s+prospects)\b",
+        rf"\b(?:nearby|local)\b.+\b{business_plural}\b",
+    )
+    geo_terms = (
+        "geo finder",
+        "near ",
+        "nearby",
+        "around ",
+        "within ",
+        "coordinates",
+        "latitude",
+        "longitude",
+        "companies near",
+        "discover new companies",
+        "map search",
+    )
+    research_terms = (
+        "company extractor",
+        "company research",
+        "research company",
+        "research ",
+        "extract company",
+        "enrich company",
+        "profile for",
+        "company profile",
+        "analyze company",
+        "analyse company",
+    )
+
+    tool = ""
+    confidence = "heuristic"
+    if any(term in normalized for term in ocr_terms):
+        tool = "ocr"
+        confidence = "rule"
+    elif any(re.search(pattern, normalized, flags=re.I) for pattern in geo_discovery_patterns):
+        tool = "geo"
+        confidence = "rule"
+    elif any(term in normalized for term in geo_terms):
+        tool = "geo"
+    elif any(term in normalized for term in research_terms):
+        tool = "research"
+        confidence = "rule" if any(term in normalized for term in ("company extractor", "company research")) else "heuristic"
+
+    if not tool:
+        return None
+
+    route = dict(TOOL_ROUTES[tool])
+    tool_query = _strip_tool_verbs(query, tool) or _clean_query(query)
+    payload: dict[str, Any] = {
+        "action": "tool_route",
+        "tool": tool,
+        "tool_label": route["label"],
+        "route": route["route"],
+        "message": route["summary"],
+        "tool_input": {},
+        "confidence": confidence,
+    }
+    if tool == "geo":
+        payload["tool_input"] = {"query": tool_query}
+        payload["auto_start"] = True
+    elif tool == "research":
+        payload["tool_input"] = {"company": tool_query}
+        payload["auto_start"] = bool(tool_query)
+    else:
+        payload["tool_input"] = {"query": tool_query}
+        payload["auto_start"] = False
+    return payload
+
+def normalize_tool_route(route_payload: dict[str, Any], original_query: str) -> dict[str, Any]:
+    tool = str(route_payload.get("tool") or "").strip().lower()
+    if tool in {"company_extractor", "company-extractor", "extractor"}:
+        tool = "research"
+    if tool in {"geo_finder", "geo-finder"}:
+        tool = "geo"
+    if tool not in TOOL_ROUTES:
+        fallback = heuristic_tool_route(original_query)
+        if fallback:
+            return fallback
+        return {"action": "answer", "reply": "I could not identify the right tool for that request."}
+
+    route = TOOL_ROUTES[tool]
+    tool_input = route_payload.get("tool_input") if isinstance(route_payload.get("tool_input"), dict) else {}
+    if tool == "geo":
+        tool_input["query"] = _clean_query(tool_input.get("query") or route_payload.get("query") or _strip_tool_verbs(original_query, tool))
+    elif tool == "research":
+        tool_input["company"] = _clean_query(tool_input.get("company") or route_payload.get("company") or _strip_tool_verbs(original_query, tool))
+    elif tool == "ocr":
+        tool_input["query"] = _clean_query(tool_input.get("query") or _strip_tool_verbs(original_query, tool))
+
+    return {
+        "action": "tool_route",
+        "tool": tool,
+        "tool_label": route["label"],
+        "route": route["route"],
+        "message": route_payload.get("message") or route["summary"],
+        "tool_input": tool_input,
+        "auto_start": bool(route_payload.get("auto_start", tool in {"geo", "research"})),
+        "confidence": route_payload.get("confidence") or "model",
+    }
+
+def save_tool_route(query: str, route_payload: dict[str, Any]) -> str:
+    tool_label = route_payload.get("tool_label") or route_payload.get("tool") or "Tool"
+    job_id = new_job(
+        "tool_route",
+        f"{tool_label}: {_clean_query(query)[:90]}",
+        {
+            "query": _clean_query(query),
+            "selected_tool": route_payload.get("tool"),
+            "route": route_payload.get("route"),
+            "tool_input": route_payload.get("tool_input") or {},
+            "auto_start": bool(route_payload.get("auto_start")),
+            "confidence": route_payload.get("confidence") or "",
+        },
+    )
+    update_job(
+        job_id,
+        status="completed",
+        started_at=now(),
+        finished_at=now(),
+        result={
+            "selected_tool": route_payload.get("tool"),
+            "tool_label": route_payload.get("tool_label"),
+            "route": route_payload.get("route"),
+            "message": route_payload.get("message"),
+            "tool_input": route_payload.get("tool_input") or {},
+        },
+    )
+    return job_id

settings/base_company_context.md

@@ -0,0 +1,26 @@
+# Company Knowledge Base - Drinking Water Can Supply Business
+
+# About Us
+
+We are an India-based B2B drinking water supply company specializing in the manufacturing and distribution of high-quality packaged drinking water in reusable 20-litre water cans. Our primary focus is supplying businesses and organizations that require a continuous, reliable, and hygienic source of drinking water for their employees, workers, visitors, and guests.
+
+Unlike retail bottled water brands, we operate on a recurring business model where customers receive scheduled deliveries of water cans based on their daily or weekly consumption.
+
+Our objective is to become the preferred drinking water supplier for organizations with medium to large workforce requirements.
+
+---
+
+# What We Do
+
+We manufacture purified drinking water that complies with Indian drinking water quality standards.
+
+We supply:
+
+* 20L reusable drinking water cans
+* Bulk drinking water supply
+* Scheduled recurring deliveries
+* Emergency water deliveries
+* Long-term corporate supply contracts
+* Multi-location water supply solutions
+
+We ensure consistent quality, timely deliveries, and uninterrupted supply.

start-hf-space.sh

@@ -0,0 +1,26 @@
+#!/bin/sh
+set -eu
+
+export PORT="${PORT:-7860}"
+export PYTHONPATH="${PYTHONPATH:-/app}"
+export WEB_CONCURRENCY="${WEB_CONCURRENCY:-1}"
+export WEB_TIMEOUT="${WEB_TIMEOUT:-180}"
+export CELERY_WORKER_POOL="${CELERY_WORKER_POOL:-solo}"
+export CELERY_WORKER_CONCURRENCY="${CELERY_WORKER_CONCURRENCY:-1}"
+export REDIS_URL="${REDIS_URL:-redis://127.0.0.1:6379/0}"
+export CELERY_BROKER_URL="${CELERY_BROKER_URL:-$REDIS_URL}"
+export CELERY_RESULT_BACKEND="${CELERY_RESULT_BACKEND:-$REDIS_URL}"
+
+if [ "$REDIS_URL" = "redis://127.0.0.1:6379/0" ] || [ "$REDIS_URL" = "redis://localhost:6379/0" ]; then
+  redis-server --daemonize yes
+fi
+
+celery -A celery_app.celery_app worker \
+  --loglevel=info \
+  --pool="${CELERY_WORKER_POOL}" \
+  --concurrency="${CELERY_WORKER_CONCURRENCY}" &
+
+exec gunicorn app:app \
+  --bind "0.0.0.0:${PORT}" \
+  --workers "${WEB_CONCURRENCY}" \
+  --timeout "${WEB_TIMEOUT}"

static/js/api.js

@@ -0,0 +1,109 @@
+async function loadDataFromDb() {
+    showGlobalLoader('Synchronizing workspace data...');
+    try {
+        const bootstrapRes = await fetch('/api/bootstrap');
+        if (bootstrapRes.ok) {
+            const data = await bootstrapRes.json();
+
+            // Apply stages
+            if (data.stages) {
+                dbStages = data.stages;
+            }
+
+            // Apply companies
+            if (data.companies) {
+                mockCompanies = data.companies.map(c => ({
+                    id: c.id,
+                    name: c.name,
+                    province: c.province || '',
+                    city: c.city || '',
+                    industry: c.industry || '',
+                    stage: c.stage_name || 'New',
+                    size: c.size_staff ? `${c.size_staff.toLocaleString()} staff` : 'Not Disclosed',
+                    lastTouched: c.updated_at ? c.updated_at.split(' ')[0] : '',
+                    rep: c.rep_name || 'User2',
+                    score: c.maplempss_fit_score || 0.0,
+                    ...c
+                }));
+            }
+
+            // Apply contacts
+            if (data.contacts) {
+                mockContacts = data.contacts.map(c => ({
+                    id: c.id,
+                    first_name: c.first_name,
+                    last_name: c.last_name,
+                    company: c.company_name || '',
+                    title: c.title || '',
+                    email: c.email || '',
+                    phone: c.phone || '',
+                    is_primary: c.is_primary === 1,
+                    ...c
+                }));
+            }
+
+            // Apply column schemas
+            if (data.columns_companies && typeof loadColumnsFromBootstrap === 'function') {
+                loadColumnsFromBootstrap('companies', data.columns_companies);
+            }
+            if (data.columns_contacts && typeof loadColumnsFromBootstrap === 'function') {
+                loadColumnsFromBootstrap('contacts', data.columns_contacts);
+            }
+
+            hideGlobalLoader();
+            return; // Success — skip fallback
+        }
+    } catch (err) {
+        console.warn("Bootstrap endpoint failed, falling back to sequential loading:", err);
+    }
+
+    // Fallback: sequential loading (for when bootstrap is unavailable)
+    try {
+        await loadColumnsFromDb('companies');
+        await loadColumnsFromDb('contacts');
+
+        const stagesRes = await fetch('/api/stages');
+        if (stagesRes.ok) {
+            dbStages = await stagesRes.json();
+        }
+
+        const companiesRes = await fetch('/api/companies');
+        if (companiesRes.ok) {
+            const dbCompanies = await companiesRes.json();
+            mockCompanies = dbCompanies.map(c => ({
+                id: c.id,
+                name: c.name,
+                province: c.province || '',
+                city: c.city || '',
+                industry: c.industry || '',
+                stage: c.stage_name || 'New',
+                size: c.size_staff ? `${c.size_staff.toLocaleString()} staff` : 'Not Disclosed',
+                lastTouched: c.updated_at ? c.updated_at.split(' ')[0] : '',
+                rep: c.rep_name || 'User2',
+                score: c.maplempss_fit_score || 0.0,
+                ...c
+            }));
+        }
+
+        const contactsRes = await fetch('/api/contacts');
+        if (contactsRes.ok) {
+            const dbContacts = await contactsRes.json();
+            mockContacts = dbContacts.map(c => ({
+                id: c.id,
+                first_name: c.first_name,
+                last_name: c.last_name,
+                company: c.company_name || '',
+                title: c.title || '',
+                email: c.email || '',
+                phone: c.phone || '',
+                is_primary: c.is_primary === 1,
+                ...c
+            }));
+        }
+    } catch (err) {
+        console.error("Failed to load data from database: ", err);
+    } finally {
+        hideGlobalLoader();
+    }
+}
+