How nishithp2004/aegis works
1. Repo shape and primary boundary
- AEGIS is split into two independently containerized services: an agent backend under agents/ and a Streamlit dashboard under dashboard/.
- docker-compose.yaml is the top-level orchestration boundary that connects the UI to the grading API over the Docker network.
2. Backend service: grading engine
- agents/main.py is the HTTP entry point, exposing the grading API with FastAPI.
- The backend is responsible for receiving a grading request, invoking the AI-based grading workflow, and returning the final evaluation payload.
3. Agent subsystem
- agents/aegis_agent/agent.py and agents/aegis_agent/prompts.py contain the core grading logic and prompt construction.
- This is the internal “intelligence” layer: it likely assembles the rubric, student answer, and agent-specific prompts into a coordinated evaluation pipeline.
4. Multi-agent evaluation model
- The README describes specialized roles such as Arbiter, Scrutinizer, Validator, and Mentor.
- Architecturally, this implies the backend is not a single pass scorer; it performs cross-checking and reasoning across multiple agent perspectives before producing the final score and feedback.
5. External model dependency
- The backend depends on Google Cloud / Vertex AI credentials (GOOGLE_API_KEY, PROJECT_ID).
- This is the main external execution dependency: the grading logic is mediated through hosted AI models rather than local inference.
6. Dashboard service: user-facing presentation
- dashboard/app.py is the Streamlit UI entry point.
- It provides the interactive workflow for submitting assignments, viewing results, and navigating history/analytics tabs.
7. Dashboard-to-backend communication
- dashboard/api_client.py is the integration boundary between the UI and the agent service.
- The dashboard does not appear to grade directly; it packages user input, calls the backend API, and renders the returned grading output.
8. Request types and input channels
- The system supports at least two input paths:
- Text submission: rubric + student answer posted directly.
- OCR-based submission: two PDF uploads, then text extraction/proc essing before grading.
- This means the dashboard is the ingestion layer, while the backend consumes a normalized grading prompt.
9. Persistence and analytics
- The README mentions history and analytics, with optional Redis settings in Streamlit secrets.
- No dedicated database service is present in the visible tree, so persistence is either optional, external, or lightweight rather than a core repo-managed datastore.
10. Deployment and runtime packaging
- Each service has its own Dockerfile and dependency manifest (requirements.txt; the agents package also has pyproject.toml).
- docker-compose.yaml starts the backend on port 8000 and the dashboard on port 8501, which is the main runtime topology to capture in an architecture diagram.
11. End-to-end data flow
- User submits rubric/answer in Streamlit → dashboard prepares request via api_client.py → FastAPI backend receives the prompt → multi-agent grading logic in aegis_agent evaluates and cross-checks → final score/feedback is returned to the dashboard → results are displayed and optionally stored for history/analytics.
12. Useful diagram boundaries
- For a diagram, the clearest boxes are: User/UI, Streamlit Dashboard, FastAPI Agent Service, Multi-agent Grading Core, and External AI/Vertex AI.
- The main arrows are: user input into dashboard, API call from dashboard to agents, and model-backed evaluation from agents to Google AI services.
Main entry points: app.py Dashboard app · agent.py Agent core · main.py Agent API · docker-compose.yaml Compose
Components 16
Runtime services
Containerized services and orchestration at the repository boundary
- Compose · Top-level container orchestration connecting dashboard and backend
docker-compose.yaml
Agent backend
FastAPI grading service and AI-driven evaluation core
- Agent API · HTTP entry point for the grading backend
agents/main.py - Agent core · Coordinates rubric-aware grading and orchestrates the evaluation workflow
agents/aegis_agent/agent.py - Prompts · Constructs prompts and role instructions for the grading pipeline
agents/aegis_agent/prompts.py - Multi-agent eval · Cross-checking roles such as arbiter, scrutinizer, validator, and mentor
- Vertex AI · External AI model backend used for grading and feedback generation
- Google creds · API key and project credentials required by the backend
- Agent image · Container build for the grading backend
agents/Dockerfile - Agent package · Backend packaging and dependency definition
agents/pyproject.toml
Dashboard
Streamlit UI and request packaging layer
- Dashboard app · Streamlit user interface for submissions, results, and history
dashboard/app.py - API client · Packages dashboard input and calls the grading service
dashboard/api_client.py - Grading input · Rubric and student answer after UI packaging and preprocessing
- OCR flow · PDF upload and text extraction path used for scanned submissions
- History · Optional history and analytics surfaced in the dashboard
- Dashboard image · Container build for the Streamlit service
dashboard/Dockerfile - UI deps · Streamlit service dependency manifest
dashboard/requirements.txt
Connections 18
- Compose → Dashboard image: builds · Compose starts the dashboard container
- Compose → Agent image: builds · Compose starts the grading backend container
- Dashboard image → Dashboard app: runs · Dashboard image launches the Streamlit app
- Dashboard app → API client: uses · UI delegates backend communication to the API client
- API client → Grading input: packages · Converts user input into a normalized grading payload
- Dashboard app → OCR flow: uploads · Supports PDF-based submission and text extraction
- OCR flow → Grading input: extracts · Normalizes OCR output into text for grading
- Grading input → Agent API: POSTs to · Dashboard sends the grading request to the backend API
- Agent image → Agent API: runs · Backend image launches the FastAPI service
- Agent API → Agent core: dispatches · HTTP entry point hands requests to the grading coordinator
- Agent core → Prompts: builds · Core logic assembles role-specific prompts
- Agent core → Multi-agent eval: orchestrates · Coordinates cross-checking and role-based evaluation
- Multi-agent eval → Vertex AI: calls · Evaluation uses hosted AI models
- Google creds → Vertex AI: authenticates · Credentials configure access to the model service
- Agent package → Agent API: packages · Defines backend runtime and dependencies
- UI deps → Dashboard app: packages · Defines dashboard runtime dependencies
- Agent core → History: returns · Grading results can feed dashboard history and analytics
- Dashboard app → History: displays · Dashboard surfaces prior results and analytics views