How shiiinooo/thesis-code works
Project type and purpose
• This is a research-oriented multi-service codebase (“Thesis Code”) that demonstrates and evaluates three different search/QA approaches:
• Agentic (Node.js/TypeScript)
• Retrieval-Augmented Generation (RAG) (Python)
• Semantic Search (Python)
• A small Python “front” runner drives experiments, and there is a shared utility library plus a PostgreSQL database and external LLM API (e.g., OpenAI).
File structure
• Top-level:
• back/agentic – TS microservice with its own server.ts, DB schema (Drizzle + PostgreSQL), LLM providers, LangGraph tools
• back/rag – Python scripts using a RAG approach (backend.py, rag-based-approach.py)
• back/semantic – Python scripts for semantic embedding, search, indexing
• front/front.py – lightweight runner/UI that invokes each backend approach
• lib/ – shared Python/TS utilities (db_utils, llm_providers)
• one-for-all.py – likely an orchestrator that ties everything together
• test/ – evaluation scripts, test queries, test outputs
• Config/deployment files:
• .env.example – env vars (DATABASE_URL, OPENAI_API_KEY)
• back/agentic/package.json + tsconfig.json, Python requirements.txt in rag & semantic
README for additional insights
• Confirms split by approach in back/
• front/ is a small UI/runner
• test/ holds evaluation code and result plots
• Environment variables: database connection, OpenAI key
1. Front-end Runner (front/front.py or one-for-all.py)
2. Agentic Service (back/agentic)
3. RAG Scripts (back/rag)
4. Semantic Search Scripts (back/semantic)
5. Shared Utilities Library (lib/)
6. PostgreSQL Database (back/agentic/db + used by other services)
7. External LLM Provider (OpenAI API)
8. Test Harness & Reporting (test/) – optional side component
b. Relationships and interactions
1. Front Runner invokes each backend approach (Agentic, RAG, Semantic) in sequence or parallel.
2. Each backend:
• Reads/writes to PostgreSQL (e.g., Agentic uses Drizzle ORM; semantic uses index_embeddings.py; RAG may cache embeddings/search results).
• Calls the OpenAI API (via shared llm_providers module) or other LLM providers to generate or embed text.
• Returns results back to the front runner.
3. Front Runner collects results, passes them into test harness or evaluation scripts.
4. Test Harness reads test queries from test/data and writes test outputs/results in test/test_outputs.
c. Architectural patterns or design principles
• Micro-service–like separation: each approach lives in its own backend folder with its own runtime (Node vs. Python).
• Shared code extraction: lib/ provides common DB and LLM interfaces.
• Data-flow-driven evaluation: front runner orchestrates data flows through each service.
• Clear separation of concerns: indexing, searching, agent orchestration isolated per approach.
d. Key technologies/frameworks
• Node.js + TypeScript + Drizzle ORM (Agentic)
• Python + requirements.txt (RAG & Semantic)
• PostgreSQL (DATABASE_URL)
• OpenAI (OPENAI_API_KEY)
• Bun lockfile (back/agentic/bun.lock)
• ESLint (back/agentic/eslint.config.mjs)
Key details to capture
• Environment variables dependency (.env) for DB and API keys
• Distinct runtimes (Node vs. Python)
• Shared utilities library usage
• Data flow from test inputs → Front Runner → Backends → DB & LLM → Results → Test Outputs