shobika-p/ai-agent-coordination-decision-engine

Purpose and Entry Points

This repository is an AI-assisted business decision-support workspace. A React/Vite dashboard submits business questions to a Flask REST API, which runs a LangGraph multi-agent workflow, persists reports and conversations, and returns decision analysis.

• Backend/API entry point: app.py

• Frontend entry points: business-decision-ui/src/main.jsx, business-decision-ui/src/App.jsx

• Deployment command definition: Procfile

API and Application Boundary

app.py is the backend integration boundary for report generation, follow-ups, what-if calculations, report-library CRUD, export, monitoring, and decision reruns. It accepts frontend requests, invokes graph/agent services, and serializes results for the UI.

The frontend API client centralizes HTTP calls in business-decision-ui/src/services/api.js. Main interaction surfaces include the submission form, report viewer, workflow status view, scenario panel, and persisted-report UI:

• business-decision-ui/src/components/BusinessForm.jsx

• business-decision-ui/src/components/ReportViewer.jsx

• business-decision-ui/src/components/WorkflowVisualizer.jsx

• business-decision-ui/src/components/WhatIfPanel.jsx

Decision Workflow Orchestration

The primary control flow is a LangGraph StateGraph defined in graph/decision_graph.py:

START → tool selection/execution → research → planning → decision → report compilation → END

The graph passes structured state across stages and exposes node status/metrics to the API/UI. Coordination and report-level assembly are represented by:

• agents/coordination_agent.py

• agents/business_decision_engine.py

• graph/decision_graph.py

Specialized AI Agent Stages

Agents isolate distinct reasoning responsibilities while sharing graph state:

• Research and market/context analysis: agents/research_agent.py

• Strategy and execution planning: agents/planning_agent.py

• Final viability/recommendation evaluation: agents/decision_agent.py

• Contextual question-answering after a generated report: agents/followup_agent.py

• Suggested next questions: agents/suggest_followups_agent.py

Prompt contracts are separated from execution logic in prompts/research_prompt.py, prompts/planning_prompt.py, and prompts/decision_prompt.py.

Quantitative Analysis Layer

Before or alongside LLM reasoning, tool selection and deterministic calculations provide financial and market inputs to the decision state. This is the boundary for ROI, profit, break-even, and risk computations:

• tools/tool_selector.py

• tools/tool_manager.py

• tools/roi_tool.py

• tools/break_even_tool.py

• tools/market_risk_tool.py

The what-if API applies adjustable operating assumptions to recompute outcomes for the UI scenario controls.

AI Runtime and Resilience

All Gemini interactions are intended to route through a centralized client, rather than agents directly owning provider behavior:

• utils/gemini_client.py

• utils/llm_helper.py

• config.py

This layer manages Gemini model calls, normalized caching, quota/rate-limit handling, retries, telemetry, and a demo/cache fallback when API credentials or quota are unavailable. External AI dependency: Google Gemini via LangChain Google GenAI.

Persistence, Reporting, and Exports

SQLite-backed storage maintains reports, scores, risk metadata, and report-specific conversation history:

• memory/report_db.py

• memory/shared_memory.py

• memory/decision_engine.db

Report export is a separate output boundary; PDF generation uses ReportLab, while API export also supports JSON and Markdown:

• utils/pdf_generator.py

Material Runtime Stack

Backend runtime is Python 3.11+, Flask with CORS, LangGraph/LangChain, SQLite3, and ReportLab. Frontend runtime is React 19 with Vite and Axios. The system normally runs as two local processes: Flask on port 5000 and Vite on port 5173; the frontend communicates solely through the REST API.