# akhilkadarla/agentic_ai architecture

> Architecture diagram of the GitHub repository akhilkadarla/agentic_ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akhilkadarla/agentic_ai
- Repository: https://github.com/akhilkadarla/agentic_ai

## Overview

FinSight is a financial research assistant: users ask questions through the CLI or Streamlit UI, and a memory-enabled agent consults financial-data tools and Claude before returning research, optionally as a structured note. Separate branches cover SEC filings, Pillar 3 capital metrics and report search, MCP clients, and deployed access. The README documents these capabilities; some subsystem links rely on the source index because their implementation excerpts were not provided.

Main entry points: [`src/finsight/agent.py`](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/agent.py) (Research agent), [`src/finsight/cli.py`](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/cli.py) (CLI), [`src/finsight/tools.py`](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/tools.py) (Tool dispatch), [`src/finsight/ui.py`](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/ui.py) (Streamlit UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_ui["Streamlit UI<br/>[ui.py]"]
  node_remote["Remote client<br/>[remote.py]"]
  node_api["FastAPI<br/>[api.py]"]
end

subgraph group_research["Research workflow"]
  node_agent["Research agent<br/>[agent.py]"]
  node_tools["Tool dispatch<br/>[tools.py]"]
  node_guardrail["Compliance checks<br/>[guardrail.py]"]
  node_notes["Research notes<br/>[notes.py]"]
  node_charts["Charts<br/>[charts.py]"]
end

subgraph group_data["Financial data"]
  node_sec["SEC EDGAR<br/>[sec.py]"]
  node_filings["Filing extraction<br/>[filings.py]"]
  node_knowledge["Knowledge Base<br/>[knowledge_base.py]"]
  node_pillar["Pillar 3 reports<br/>[pillar3.py]"]
  node_metrics[("Capital metrics")]
end

subgraph group_runtime["Model and runtime"]
  node_tracing["Tracing<br/>[tracing.py]"]
  node_providers["Provider selection<br/>[providers.py]"]
  node_llm["Claude calls<br/>[llm.py]"]
end

node_user(("Analyst"))
node_model_service["Anthropic / Bedrock"]
node_sec_service["SEC services"]
node_bedrock_kb["Bedrock Knowledge Base"]
node_guardrail_service["Bedrock Guardrails"]
node_runtime_service["AgentCore Runtime"]
node_cognito["Cognito"]
node_mcp_client(("MCP client"))

node_user -->|"asks via"| node_cli
node_user -->|"uses"| node_ui
node_cli -->|"starts research"| node_agent
node_ui -->|"submits questions"| node_agent
node_ui -->|"renders"| node_charts
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"checks answers"| node_guardrail
node_agent -->|"requests completions"| node_llm
node_agent -->|"writes notes"| node_notes
node_agent -->|"records traces"| node_tracing
node_llm -->|"selects client"| node_providers
node_providers -->|"calls"| node_model_service
node_tools -->|"fetches filings and facts"| node_sec
node_sec -->|"requests data"| node_sec_service
node_tools -->|"searches text"| node_knowledge
node_knowledge -.->|"queries"| node_bedrock_kb
node_tools -->|"gets metrics and passages"| node_pillar
node_pillar -->|"reads"| node_metrics
node_guardrail -->|"applies policy"| node_guardrail_service
node_remote -->|"authenticates"| node_cognito
node_remote -->|"invokes"| node_runtime_service
node_runtime_service -->|"routes requests"| node_api
node_api -->|"serves agent"| node_agent
node_mcp_client -.->|"launches MCP"| node_cli
node_cli -.->|"exposes research tools"| node_tools
node_filings -->|"uses EDGAR data"| node_sec
node_cli -->|"indexes filings"| node_filings
node_cli -->|"manages indexing"| node_knowledge
node_cli -->|"builds report metrics"| node_pillar

click node_cli "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/cli.py"
click node_ui "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/ui.py"
click node_remote "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/remote.py"
click node_api "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/api.py"
click node_agent "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/agent.py"
click node_tools "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/tools.py"
click node_guardrail "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/guardrail.py"
click node_notes "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/notes.py"
click node_charts "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/charts.py"
click node_tracing "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/tracing.py"
click node_providers "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/providers.py"
click node_llm "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/llm.py"
click node_sec "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/sec.py"
click node_filings "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/filings.py"
click node_knowledge "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/knowledge_base.py"
click node_pillar "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/pillar3.py"
click node_metrics "https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/data/pillar3_key_metrics.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_ui,node_remote,node_api,node_mcp_client toneBlue
class node_agent,node_tools,node_guardrail,node_notes,node_charts toneAmber
class node_sec,node_filings,node_knowledge,node_pillar,node_metrics toneMint
class node_tracing,node_providers,node_llm toneRose
class node_user,node_model_service,node_sec_service,node_bedrock_kb,node_guardrail_service,node_runtime_service,node_cognito toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/cli.py): `src/finsight/cli.py`
- [Streamlit UI](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/ui.py): `src/finsight/ui.py`
- [Remote client](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/remote.py): `src/finsight/remote.py`
- [FastAPI](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/api.py): `src/finsight/api.py`

### Research workflow

- [Research agent](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/agent.py): `src/finsight/agent.py`
- [Tool dispatch](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/tools.py): `src/finsight/tools.py`
- [Compliance checks](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/guardrail.py): `src/finsight/guardrail.py`
- [Research notes](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/notes.py): `src/finsight/notes.py`
- [Charts](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/charts.py): `src/finsight/charts.py`

### Financial data

- [SEC EDGAR](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/sec.py): `src/finsight/sec.py`
- [Filing extraction](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/filings.py): `src/finsight/filings.py`
- [Knowledge Base](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/knowledge_base.py): `src/finsight/knowledge_base.py`
- [Pillar 3 reports](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/pillar3.py): `src/finsight/pillar3.py`
- [Capital metrics](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/data/pillar3_key_metrics.json): `src/finsight/data/pillar3_key_metrics.json`

### Model and runtime

- [Tracing](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/tracing.py): `src/finsight/tracing.py`
- [Provider selection](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/providers.py): `src/finsight/providers.py`
- [Claude calls](https://github.com/akhilkadarla/agentic_ai/blob/main/src/finsight/llm.py): `src/finsight/llm.py`

### Other components

- **Analyst**
- **Anthropic / Bedrock**
- **SEC services**
- **Bedrock Knowledge Base**
- **Bedrock Guardrails**
- **AgentCore Runtime**
- **Cognito**
- **MCP client**

## Connections

- Analyst → CLI: asks via (evidence: `README.md`)
- Analyst → Streamlit UI: uses (evidence: `README.md`)
- CLI → Research agent: starts research (evidence: `src/finsight/cli.py`)
- Streamlit UI → Research agent: submits questions (evidence: `src/finsight/ui.py`)
- Streamlit UI → Charts: renders (evidence: `src/finsight/ui.py`)
- Research agent → Tool dispatch: dispatches tools (evidence: `src/finsight/agent.py`)
- Research agent → Compliance checks: checks answers (evidence: `src/finsight/agent.py`)
- Research agent → Claude calls: requests completions (evidence: `src/finsight/agent.py`)
- Research agent → Research notes: writes notes (evidence: `src/finsight/agent.py`)
- Research agent → Tracing: records traces (evidence: `src/finsight/agent.py`)
- Claude calls → Provider selection: selects client (evidence: `src/finsight/llm.py`)
- Provider selection → Anthropic / Bedrock: calls (evidence: `src/finsight/providers.py`)
- Tool dispatch → SEC EDGAR: fetches filings and facts (evidence: `src/finsight/tools.py`)
- SEC EDGAR → SEC services: requests data (evidence: `src/finsight/sec.py`)
- Tool dispatch → Knowledge Base: searches text (evidence: `src/finsight/tools.py`)
- Knowledge Base → Bedrock Knowledge Base: queries (evidence: `README.md`)
- Tool dispatch → Pillar 3 reports: gets metrics and passages (evidence: `src/finsight/tools.py`)
- Pillar 3 reports → Capital metrics: reads (evidence: `README.md`)
- Compliance checks → Bedrock Guardrails: applies policy (evidence: `src/finsight/guardrail.py`)
- Remote client → Cognito: authenticates (evidence: `src/finsight/remote.py`)
- Remote client → AgentCore Runtime: invokes (evidence: `README.md`)
- AgentCore Runtime → FastAPI: routes requests (evidence: `README.md`)
- FastAPI → Research agent: serves agent (evidence: `src/finsight/api.py`)
- MCP client → CLI: launches MCP (evidence: `README.md`)
- CLI → Tool dispatch: exposes research tools (evidence: `README.md`)
- Filing extraction → SEC EDGAR: uses EDGAR data (evidence: `src/finsight/filings.py`)
- CLI → Filing extraction: indexes filings (evidence: `src/finsight/cli.py`)
- CLI → Knowledge Base: manages indexing (evidence: `src/finsight/cli.py`)
- CLI → Pillar 3 reports: builds report metrics (evidence: `src/finsight/cli.py`)
