How daudimwiti/qualagent-bridge works
Project Type and Purpose
• QualAgents is primarily a backend service geared toward qualitative data analysis using AI. Its core functionality involves project management, agent orchestration for processing qualitative data, and generating insights. Despite being backend-focused, there is also a frontend component (built with TypeScript/React) used for visualizing and managing projects.
• The README confirms use of FastAPI, LangGraph (and LangChain), PostgreSQL with the pgvector extension, and Async SQLAlchemy to support an AI analysis pipeline.
Main Components
• API Layer:
• FastAPI endpoints (located in src/api/api_v1/ endpoints and api.py)
• Request validation via Pydantic schemas (in src/schemas)
• Authentication and middleware (as suggested by project structure)
• Service Layer:
• Business logic for handling projects, agents, and analysis (found in src/services, e.g., project_service.py, agent_service.py, analysis_service.py)
• Agent System:
• AI agents and the orchestrator (src/agents/orchestrator.py) that manage qualitative analysis tasks.
• Tools used per agent (under src/agents/tools such as sentiment_analysis.py, document_search.py, etc.)
• Data Processing / Analysis Pipeline:
• Steps that process qualitative data, perform sentiment analysis, theme clustering, and generate insights.
• Memory management and vector embeddings for semantic analysis (utilizing PostgreSQL with pgvector, referenced in src/core/embeddings.py and src/utils/vector_store.py).
• Database Layer:
• PostgreSQL database integration with the pgvector extension.
• Database models and initialization scripts (src/db/models.py and src/db/init_db.py) together with dependencies (src/db/dependencies.py).
• Frontend Component:
• React interface found in various TypeScript (.tsx) files under src/components and src/pages.
• Handles user interactions, project creation, configuration of agents, and result visualization.
• Deployment/Containerization:
• Docker file, docker-compose.yml, and associated scripts (entrypoint.sh) indicate containerized deployment.
Relationships and Interactions
• API calls from the frontend interact with the FastAPI backend. These endpoints handle requests such as creating projects, configuring agents, and retrieving analysis results.
• The API layer utilizes the Service Layer to apply business logic. The Service Layer further calls on the Agent System to orchestrate the data analysis pipeline.
• The Agent System processes raw qualitative data using its different tools (e.g., document_search, sentiment_analysis, theme_cluster) and consults persistent memory backed by the database.
• The Database Layer underpins storage for structured project data and vector embeddings for semantic similarity search.
Architectural Patterns and Design Principles
• Layered Architecture: Clearly separates the API, service, agent, and database layers.
• Component-Based Design: The frontend is modular (React components under src/components), which helps in understanding the separation of UI from business logic.
• Microservice or Modular RESTful Approach: While primarily a single service, the clear segmentation of API endpoints and services suggests a modular design approach.
• Containerization: Use of Docker ensures that the system’s components are containerized for easier deployment.
Relevant Technologies/Frameworks
• Backend: Python 3.11+, FastAPI, Async SQLAlchemy, LangGraph for agent orchestration, PostgreSQL along with pgvector.
• Frontend: React (TypeScript) with a rich component library (many UI components in src/components/ui).
• Containerization: Docker, Docker Compose.
• Scripting: Utility scripts and tools that assist with database initialization and caching are located in src/scripts.