# vamsi513/agentiq architecture

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

- Interactive diagram: https://gitdiagram.com/vamsi513/agentiq
- Repository: https://github.com/vamsi513/agentiq

## Overview

AgentIQ is a multi-step research assistant: users submit questions through either the Next.js chat or Streamlit interface; the backend runs a session-aware agent that routes questions to corpus retrieval, live web search, or direct answering, then returns cited results, optionally as a stream. The graph preserves documented optional persistence, caching, tracing, and alternative retrieval implementations. Some subsystem wiring is described in the README rather than shown in sampled source, so uncertain connections are omitted.

Main entry points: [`agent/graph.py`](https://github.com/vamsi513/agentiq/blob/master/agent/graph.py) (Agent Graph), [`api/main.py`](https://github.com/vamsi513/agentiq/blob/master/api/main.py) (FastAPI Endpoints), [`agent/nodes.py`](https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py) (Intent Router), [`frontend/app/page.tsx`](https://github.com/vamsi513/agentiq/blob/master/frontend/app/page.tsx) (Next.js Chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_next_chat["Next.js Chat<br/>[page.tsx]"]
  node_next_proxy["Chat Proxy Routes<br/>[route.ts]"]
  node_streamlit["Streamlit App<br/>[app.py]"]
end

subgraph group_backend["API and Orchestration"]
  node_api["FastAPI Endpoints<br/>[main.py]"]
  node_sse["SSE Streaming<br/>[streaming.py]"]
  node_graph["Agent Graph<br/>[graph.py]"]
  node_security["Query Security<br/>[security.py]"]
end

subgraph group_research["Research and Answers"]
  node_router["Intent Router<br/>[nodes.py]"]
  node_retriever["Corpus Retrieval<br/>[nodes.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_faiss[("FAISS Vector Store<br/>[vectorstore.py]")]
  node_web_node["Web Search Node<br/>[nodes.py]"]
  node_web_tool["Tavily Search<br/>[web_search.py]"]
  node_direct["Direct Answer Node<br/>[nodes.py]"]
  node_generator["Grounded Answer Node<br/>[nodes.py]"]
  node_pinecone[("Pinecone Reference Store<br/>[pinecone_store.py]")]
  node_llamaindex["LlamaIndex Loader"]
end

subgraph group_state["Session and Operations"]
  node_memory["Checkpoint Memory<br/>[memory.py]"]
  node_cache["Response Cache<br/>[cache.py]"]
  node_tracing["LangSmith Tracing"]
end

subgraph group_integrations["External Services"]
  node_llm{{"OpenAI Model"}}
  node_tavily{{"Tavily API"}}
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_langsmith{{"LangSmith"}}
end

node_user(("Researcher"))

node_user -->|"asks"| node_next_chat
node_next_chat -->|"streams query"| node_next_proxy
node_next_proxy -->|"proxies request"| node_api
node_user -->|"asks"| node_streamlit
node_streamlit -->|"invokes agent"| node_graph
node_api -->|"invokes agent"| node_graph
node_api -->|"streams response"| node_sse
node_sse -->|"streams graph output"| node_graph
node_graph -->|"dispatches nodes"| node_router
node_router -->|"checks query"| node_security
node_router -->|"classifies intent"| node_llm
node_graph -->|"routes retrieval"| node_retriever
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"queries vectors"| node_faiss
node_graph -->|"routes web search"| node_web_node
node_web_node -->|"searches"| node_web_tool
node_web_tool -->|"requests results"| node_tavily
node_graph -->|"routes direct"| node_direct
node_direct -->|"answers query"| node_llm
node_graph -->|"routes synthesis"| node_generator
node_generator -->|"generates answer"| node_llm
node_graph -->|"checkpoints turns"| node_memory
node_memory -.->|"persists checkpoints"| node_postgres
node_graph -.->|"checks response cache"| node_cache
node_cache -.->|"reads and writes"| node_redis
node_graph -.->|"emits run data"| node_tracing
node_tracing -.->|"sends traces"| node_langsmith

click node_next_chat "https://github.com/vamsi513/agentiq/blob/master/frontend/app/page.tsx"
click node_next_proxy "https://github.com/vamsi513/agentiq/blob/master/frontend/app/api/chat/stream/route.ts"
click node_streamlit "https://github.com/vamsi513/agentiq/blob/master/app.py"
click node_api "https://github.com/vamsi513/agentiq/blob/master/api/main.py"
click node_sse "https://github.com/vamsi513/agentiq/blob/master/api/streaming.py"
click node_graph "https://github.com/vamsi513/agentiq/blob/master/agent/graph.py"
click node_security "https://github.com/vamsi513/agentiq/blob/master/agent/security.py"
click node_router "https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py"
click node_retriever "https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py"
click node_embeddings "https://github.com/vamsi513/agentiq/blob/master/retrieval/embeddings.py"
click node_faiss "https://github.com/vamsi513/agentiq/blob/master/retrieval/vectorstore.py"
click node_web_node "https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py"
click node_web_tool "https://github.com/vamsi513/agentiq/blob/master/tools/web_search.py"
click node_direct "https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py"
click node_generator "https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py"
click node_memory "https://github.com/vamsi513/agentiq/blob/master/agent/memory.py"
click node_cache "https://github.com/vamsi513/agentiq/blob/master/agent/cache.py"
click node_tracing "https://github.com/vamsi513/agentiq/blob/master/observability/langsmith_tracer.py"
click node_pinecone "https://github.com/vamsi513/agentiq/blob/master/retrieval/pinecone_store.py"
click node_llamaindex "https://github.com/vamsi513/agentiq/blob/master/retrieval/llamaindex_loader.py"

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_next_chat,node_next_proxy,node_streamlit toneBlue
class node_api,node_sse,node_graph,node_security toneAmber
class node_router,node_retriever,node_embeddings,node_faiss,node_web_node,node_web_tool,node_direct,node_generator,node_pinecone,node_llamaindex toneMint
class node_memory,node_cache,node_tracing toneRose
class node_llm,node_tavily,node_postgres,node_redis,node_langsmith,node_user toneIndigo
```

## Components

### User Interfaces

- [Next.js Chat](https://github.com/vamsi513/agentiq/blob/master/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Chat Proxy Routes](https://github.com/vamsi513/agentiq/blob/master/frontend/app/api/chat/stream/route.ts): `frontend/app/api/chat/stream/route.ts`
- [Streamlit App](https://github.com/vamsi513/agentiq/blob/master/app.py): `app.py`

### API and Orchestration

- [FastAPI Endpoints](https://github.com/vamsi513/agentiq/blob/master/api/main.py): `api/main.py`
- [SSE Streaming](https://github.com/vamsi513/agentiq/blob/master/api/streaming.py): `api/streaming.py`
- [Agent Graph](https://github.com/vamsi513/agentiq/blob/master/agent/graph.py): `agent/graph.py`
- [Query Security](https://github.com/vamsi513/agentiq/blob/master/agent/security.py): `agent/security.py`

### Research and Answers

- [Intent Router](https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py): `agent/nodes.py`
- [Corpus Retrieval](https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py): `agent/nodes.py`
- [Embeddings](https://github.com/vamsi513/agentiq/blob/master/retrieval/embeddings.py): `retrieval/embeddings.py`
- [FAISS Vector Store](https://github.com/vamsi513/agentiq/blob/master/retrieval/vectorstore.py): `retrieval/vectorstore.py`
- [Web Search Node](https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py): `agent/nodes.py`
- [Tavily Search](https://github.com/vamsi513/agentiq/blob/master/tools/web_search.py): `tools/web_search.py`
- [Direct Answer Node](https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py): `agent/nodes.py`
- [Grounded Answer Node](https://github.com/vamsi513/agentiq/blob/master/agent/nodes.py): `agent/nodes.py`
- [Pinecone Reference Store](https://github.com/vamsi513/agentiq/blob/master/retrieval/pinecone_store.py): `retrieval/pinecone_store.py`
- [LlamaIndex Loader](https://github.com/vamsi513/agentiq/blob/master/retrieval/llamaindex_loader.py): `retrieval/llamaindex_loader.py`

### Session and Operations

- [Checkpoint Memory](https://github.com/vamsi513/agentiq/blob/master/agent/memory.py): `agent/memory.py`
- [Response Cache](https://github.com/vamsi513/agentiq/blob/master/agent/cache.py): `agent/cache.py`
- [LangSmith Tracing](https://github.com/vamsi513/agentiq/blob/master/observability/langsmith_tracer.py): `observability/langsmith_tracer.py`

### External Services

- **OpenAI Model**
- **Tavily API**
- **PostgreSQL**
- **Redis**
- **LangSmith**

### Other components

- **Researcher**

## Connections

- Researcher → Next.js Chat: asks
- Next.js Chat → Chat Proxy Routes: streams query
- Chat Proxy Routes → FastAPI Endpoints: proxies request
- Researcher → Streamlit App: asks
- Streamlit App → Agent Graph: invokes agent
- FastAPI Endpoints → Agent Graph: invokes agent
- FastAPI Endpoints → SSE Streaming: streams response
- SSE Streaming → Agent Graph: streams graph output
- Agent Graph → Intent Router: dispatches nodes
- Intent Router → Query Security: checks query
- Intent Router → OpenAI Model: classifies intent
- Agent Graph → Corpus Retrieval: routes retrieval
- Corpus Retrieval → Embeddings: embeds query
- Corpus Retrieval → FAISS Vector Store: queries vectors
- Agent Graph → Web Search Node: routes web search
- Web Search Node → Tavily Search: searches
- Tavily Search → Tavily API: requests results
- Agent Graph → Direct Answer Node: routes direct
- Direct Answer Node → OpenAI Model: answers query
- Agent Graph → Grounded Answer Node: routes synthesis
- Grounded Answer Node → OpenAI Model: generates answer
- Agent Graph → Checkpoint Memory: checkpoints turns
- Checkpoint Memory → PostgreSQL: persists checkpoints
- Agent Graph → Response Cache: checks response cache
- Response Cache → Redis: reads and writes
- Agent Graph → LangSmith Tracing: emits run data
- LangSmith Tracing → LangSmith: sends traces