# zaidbagawan/ai_project architecture

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

- Interactive diagram: https://gitdiagram.com/zaidbagawan/ai_project
- Repository: https://github.com/zaidbagawan/ai_project

## Overview

This repository is a set of standalone Python experiments rather than one integrated application. Its main user-facing workflows are a Gemini chat loop and semantic document search, implemented in two variants: local cosine ranking and PostgreSQL/pgvector ranking. It also includes a sentence-similarity experiment and a small recent-history example. No README is provided, and the available excerpts do not show these scripts being orchestrated together; the graph therefore treats them as separate entry points.

Main entry points: [`semantic_search.py`](https://github.com/zaidbagawan/ai_project/blob/main/semantic_search.py) (Local semantic search), [`chatbot.py`](https://github.com/zaidbagawan/ai_project/blob/main/chatbot.py) (Chat loop), [`postgres_vector_search.py`](https://github.com/zaidbagawan/ai_project/blob/main/postgres_vector_search.py) (Vector search CLI), [`similarity_experiment.py`](https://github.com/zaidbagawan/ai_project/blob/main/similarity_experiment.py) (Sentence similarity demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation"]
  node_chat["Chat loop<br/>[chatbot.py]"]
  node_history["Recent history slice"]
end

subgraph group_retrieval["Semantic retrieval"]
  node_semantic["Local semantic search<br/>[semantic_search.py]"]
  node_document_set["Sample documents<br/>[semantic_search.py]"]
  node_local_rank["Cosine ranking<br/>[semantic_search.py]"]
  node_pg_search["Vector search CLI"]
end

subgraph group_experiments["Similarity examples"]
  node_similarity_demo["Sentence similarity demo"]
end

node_user(("User"))
node_gemini_chat["Gemini interactions"]
node_gemini_embed["Gemini embeddings"]
node_postgres[("PostgreSQL pgvector")]

node_user -->|"enters messages"| node_chat
node_chat -->|"sends interaction"| node_gemini_chat
node_chat -->|"prints reply"| node_user
node_user -->|"enters question"| node_pg_search
node_semantic -->|"embeds text"| node_gemini_embed
node_semantic -->|"inserts documents"| node_postgres
node_semantic -->|"ranks embeddings"| node_local_rank
node_local_rank -->|"returns best match"| node_semantic
node_pg_search -->|"embeds question"| node_gemini_embed
node_pg_search -->|"queries vectors"| node_postgres
node_similarity_demo -->|"embeds sentences"| node_gemini_embed

click node_chat "https://github.com/zaidbagawan/ai_project/blob/main/chatbot.py"
click node_history "https://github.com/zaidbagawan/ai_project/blob/main/history_management.py"
click node_semantic "https://github.com/zaidbagawan/ai_project/blob/main/semantic_search.py"
click node_document_set "https://github.com/zaidbagawan/ai_project/blob/main/semantic_search.py"
click node_local_rank "https://github.com/zaidbagawan/ai_project/blob/main/semantic_search.py"
click node_pg_search "https://github.com/zaidbagawan/ai_project/blob/main/postgres_vector_search.py"
click node_similarity_demo "https://github.com/zaidbagawan/ai_project/blob/main/similarity_experiment.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_chat,node_history,node_user toneBlue
class node_semantic,node_document_set,node_local_rank,node_pg_search,node_postgres toneAmber
class node_similarity_demo toneMint
class node_gemini_chat,node_gemini_embed toneIndigo
```

## Components

### Conversation

- [Chat loop](https://github.com/zaidbagawan/ai_project/blob/main/chatbot.py): `chatbot.py`
- [Recent history slice](https://github.com/zaidbagawan/ai_project/blob/main/history_management.py): `history_management.py`

### Semantic retrieval

- [Local semantic search](https://github.com/zaidbagawan/ai_project/blob/main/semantic_search.py): `semantic_search.py`
- [Sample documents](https://github.com/zaidbagawan/ai_project/blob/main/semantic_search.py): `semantic_search.py`
- [Cosine ranking](https://github.com/zaidbagawan/ai_project/blob/main/semantic_search.py): `semantic_search.py`
- [Vector search CLI](https://github.com/zaidbagawan/ai_project/blob/main/postgres_vector_search.py): `postgres_vector_search.py`

### Similarity examples

- [Sentence similarity demo](https://github.com/zaidbagawan/ai_project/blob/main/similarity_experiment.py): `similarity_experiment.py`

### Other components

- **User**
- **Gemini interactions**
- **Gemini embeddings**
- **PostgreSQL pgvector**

## Connections

- User → Chat loop: enters messages (evidence: `chatbot.py`)
- Chat loop → Gemini interactions: sends interaction (evidence: `chatbot.py`)
- Chat loop → User: prints reply (evidence: `chatbot.py`)
- User → Vector search CLI: enters question (evidence: `postgres_vector_search.py`)
- Local semantic search → Gemini embeddings: embeds text (evidence: `semantic_search.py`)
- Local semantic search → PostgreSQL pgvector: inserts documents (evidence: `semantic_search.py`)
- Local semantic search → Cosine ranking: ranks embeddings (evidence: `semantic_search.py`)
- Cosine ranking → Local semantic search: returns best match (evidence: `semantic_search.py`)
- Vector search CLI → Gemini embeddings: embeds question (evidence: `postgres_vector_search.py`)
- Vector search CLI → PostgreSQL pgvector: queries vectors (evidence: `postgres_vector_search.py`)
- Sentence similarity demo → Gemini embeddings: embeds sentences (evidence: `similarity_experiment.py`)