How asef69/buet-air works
1. Overall shape
- This repository is a small, stateless AI support-analysis service.
- The core workflow is: incoming ticket → validate/normalize → analyze transaction evidence in Python → call Gemini for a structured answer → apply safety filtering → return JSON to the client.
2. API boundary
- The public entrypoint lives in Iztihad/api.
- main.py boots the FastAPI application, routes.py defines the HTTP endpoints, schemas.py defines request/response contracts, and middleware.py holds cross-cutting request handling.
- The README indicates the main use case is a POST-style ticket analysis endpoint rather than a broader web app.
3. Domain / orchestration layer
- Asef/core/ticket_analyzer.py is the central orchestrator.
- It likely coordinates classification, evidence extraction, prompt assembly, model invocation, and response shaping.
- This is the main seam between API concerns and business logic.
4. Evidence-first analysis
- Asef/core/evidence_engine.py is a deterministic rules-based layer that examines the complaint and transaction history before any LLM call.
- The README says it extracts amounts in English/Bangla, matches amounts to history, detects duplicate payments, and infers recipient patterns.
- Architecturally, this is the factual grounding layer that reduces dependence on the model for numeric or transactional reasoning.
5. Complaint classification
- Asef/core/classifier.py appears to categorize ticket intent or dispute type before downstream response generation.
- This likely helps route the case or choose the right prompt/analysis branch.
- It functions as a lightweight domain decision layer rather than a machine-learning-heavy subsystem.
6. Response generation
- Asef/core/reply_builder.py is the component that turns analysis results into the final customer-facing reply.
- It sits after evidence analysis and model output, shaping the answer into a support-appropriate format.
- This is the formatting/composition boundary between internal reasoning and the external response.
7. Safety and compliance layer
- Asef/core/safety_guard.py is a post-processing gate on model-generated text.
- The README describes protections against PIN/OTP leakage, overpromising refunds, and non-official contact instructions.
- In the architecture diagram, this should be shown as a final filter before the API response leaves the system.
8. LLM integration
- Asef/llm/client.py is the external-model adapter, and Asef/llm/prompts.py contains prompt templates/context construction.
- The service uses Google Generative AI Gemini, specifically gemini-2.5-flash, as a hosted external dependency.
- The architecture relies on structured JSON output from the model, which is important for reliable API responses.
9. Shared contracts and types
- Shared/models/enums.py and the test fixtures under Shared/tests suggest shared domain constants and reusable cases.
- These shared definitions likely keep the API layer, core engine, and tests aligned on status labels, categories, or response codes.
- This is the repo’s main contract layer for consistency across modules.
10. Validation and test harness
- Shared/tests/test_api.py, test_classifier.py, test_evidence.py, and test_safety.py indicate unit/integration coverage around the major subsystems.
- sample_output.json and Shared/tests/SUST_Preli_Sample_Cases.json provide reference cases for regression verification.
- The scratch/ scripts are ad hoc validation tools and are not part of the runtime path.
11. Configuration and deployment
- Iztihad/config/settings.py likely centralizes environment-driven config such as API keys and runtime settings.
- Iztihad/infra/Dockerfile, docker-compose.yaml, vercel.json, and .env.example show the service is designed for containerized deployment with environment configuration.
- This is a deployable service, not a stateful platform; there is no visible database or queue subsystem in the tree.
12. External dependencies and trust boundary
- The only explicit external runtime dependency in the architecture is the Gemini API hosted by Google.
- All ticket reasoning is performed inside the service before and after the model call, with the model acting as an assistant rather than the source of truth.
- The trust boundary should therefore show: client → FastAPI service → external LLM → safety filter → client, with deterministic Python analysis anchoring the model output.
Main entry points: ticket_analyzer.py Analyzer · main.py Main app · routes.py Routes · safety_guard.py Safety guard
Components 20
API boundary
Public HTTP entrypoint and request/response handling.
- Main app · Starts the API service and wires runtime components.
Iztihad/api/main.py - Routes · Defines the ticket analysis API endpoints.
Iztihad/api/routes.py - Schemas · Request and response models for the public interface.
Iztihad/api/schemas.py - Middleware · Shared request handling and API-level concerns.
Iztihad/api/middleware.py
Domain core
Ticket analysis, evidence extraction, classification, reply shaping, and safety.
- Analyzer · Coordinates the full ticket analysis workflow.
Asef/core/ticket_analyzer.py - Classifier · Categorizes the ticket before downstream analysis.
Asef/core/classifier.py - Evidence engine · Extracts and matches transaction facts before LLM use.
Asef/core/evidence_engine.py - Reply builder · Shapes analysis output into a customer-facing reply.
Asef/core/reply_builder.py - Safety guard · Screens generated text for leakage and unsafe guidance.
Asef/core/safety_guard.py
LLM integration
External model adapter and prompt construction.
- Gemini client · Calls the hosted Gemini model and handles structured output.
Asef/llm/client.py - Prompts · Builds the instructions and context sent to the model.
Asef/llm/prompts.py
Shared contracts
Common enums and reusable test fixtures.
- Enums · Common domain labels and status values shared across modules.
Shared/models/enums.py - Sample cases · Reference cases used to validate expected behavior.
Shared/tests/SUST_Preli_Sample_Cases.json
Deployment
Container and environment configuration.
- Settings · Centralizes environment-driven configuration.
Iztihad/config/settings.py - Dockerfile · Builds the service image for deployment.
Iztihad/infra/Dockerfile - Compose · Runs the service with container orchestration locally.
Iztihad/infra/docker-compose.yaml - Vercel config · Deployment configuration for the hosted environment.
vercel.json
Validation
Repository-level tests and sample cases.
- API tests · Exercises the public ticket analysis API.
Shared/tests/test_api.py - Core tests · Covers classifier and evidence analysis behavior.
Shared/tests/test_classifier.py - Safety tests · Checks the safety and compliance filter.
Shared/tests/test_safety.py
Connections 25
- Main app → Routes: registers · Bootstraps the HTTP routes into the application.
- Main app → Middleware: uses · Applies cross-cutting request handling.
- Routes → Schemas: validates · Shapes incoming and outgoing payloads.
- Routes → Analyzer: calls · Hands ticket requests to the domain orchestrator.
- Analyzer → Classifier: classifies · Determines the ticket or dispute type.
- Analyzer → Evidence engine: grounds · Extracts factual transaction evidence.
- Analyzer → Prompts: prepares · Assembles structured prompt context.
- Analyzer → Gemini client: invokes · Sends the analysis context to Gemini.
- Prompts → Gemini client: feeds · Provides the model instructions and context.
- Analyzer → Reply builder: formats · Turns analysis output into a support reply.
- Analyzer → Safety guard: filters · Applies policy checks before returning text.
- Reply builder → Safety guard: checks · Routes the generated reply through safety review.
- Safety guard → Routes: returns · Produces the final safe response for the client.
- Classifier → Enums: uses · Shares canonical labels and statuses.
- Evidence engine → Enums: uses · Aligns extracted evidence with shared domain values.
- Schemas → Enums: uses · Reuses common contract values in API models.
- API tests → Routes: exercises · Validates the public endpoint behavior.
- Core tests → Classifier: tests · Checks classification behavior.
- Core tests → Evidence engine: tests · Checks evidence extraction and matching.
- Safety tests → Safety guard: tests · Checks safety filtering behavior.
- Core tests → Sample cases: uses · Loads reference cases for regression coverage.
- Settings → Main app: configures · Supplies runtime settings to the service.
- Dockerfile → Main app: packages · Containerizes the API service.
- Compose → Dockerfile: runs · Coordinates the local containerized deployment.
- Vercel config → Main app: deploys · Defines hosted deployment entry behavior.