How codepath/ai201-project2-fitfindr-starter works
1. Project purpose
- This repo is a starter kit for an AI styling assistant called FitFindr.
- The core job is to take a user query plus their wardrobe, search a small catalog of secondhand listings, and produce an outfit or “fit card” response.
2. Main runtime entry points
- app.py is the likely top-level application entry point for running the experience.
- agent.py appears to contain the orchestration logic that interprets user intent and decides which tools to call.
- tools.py is the functional boundary between the agent and the task-specific capabilities.
3. Agent orchestration layer
- The agent layer is the control plane: it receives a natural-language request, reasons over it, and invokes tools in sequence.
- Based on the README, the expected flow is: user query → listing search / wardrobe-aware suggestion → fit card creation.
- This layer is where integration with the Groq API is expected, since the setup instructions require GROQ_API_KEY.
4. Tooling layer
- tools.py is the primary capability surface and must expose the tools documented in the README:
- search_listings
- suggest_outfit
- create_fit_card
- The README emphasizes that the documented signatures must match the code exactly, so this file is part of the grading contract and a clear subsystem boundary.
5. Data layer
- data/listings.json is the catalog of mock secondhand inventory.
- data/wardrobe_schema.json defines the structure of the user wardrobe, plus example and empty templates.
- These files are static inputs, not live services; the architecture is centered on local dataset loading rather than external product APIs.
6. Shared data-loading utilities
- utils/data_loader.py is the reusable adapter for reading the JSON assets into Python objects.
- It likely abstracts file-path handling and gives the rest of the code a stable interface for loading listings and wardrobe examples.
- This keeps file I/O out of the agent and tool logic.
7. Data flow through the system
- The user provides a query to the app.
- The agent interprets intent and pulls structured data from the loaded listings and wardrobe state.
- Tool functions operate on that in-memory data to filter, rank, or assemble recommendations.
- A final fit card is produced and returned to the user.
8. Domain model boundaries
- The repository separates two main data domains:
- Marketplace inventory: secondhand listings with category, style, size, condition, price, colors, brand, and platform.
- User wardrobe: items following the schema in wardrobe_schema.json.
- Outfit logic sits at the intersection of these two domains, combining existing wardrobe items with candidate listings.
9. External dependency boundary
- The only material external service implied by the repo is Groq for LLM-powered agent reasoning.
- Everything else appears local and file-based, which means the system is mostly deterministic outside of model calls.
- requirements.txt defines the Python runtime dependencies needed for this stack.
10. Planning and specification artifacts
- planning.md is a design/specification artifact, not runtime code.
- The README makes it clear the planning document should be completed before implementation, so it serves as the architectural contract for the student’s chosen agent design.
- This file helps explain intended behavior even if the implementation is not yet finished.
11. Likely deployment shape
- The repo looks like a single-process Python application rather than a distributed system.
- There is no evidence of databases, queues, or microservices.
- The architecture diagram should therefore show one application boundary with local JSON assets and an LLM API dependency.
12. What to draw in an architecture diagram
- Show app.py as the user-facing entry point.
- Show agent.py as the orchestration engine.
- Show tools.py as the callable action layer.
- Show utils/data_loader.py as the data access helper.
- Show data/listings.json and data/wardrobe_schema.json as static inputs.
- Show Groq as the external model service.
Main entry points: tools.py Tools · agent.py Agent · data_loader.py Data loader · listings.json Listings
Components 12
Application
Single-process Python runtime that accepts requests and produces fit cards.
- App entry · Top-level application launcher for the FitFindr experience.
app.py - Agent · Interprets user intent and coordinates tool calls.
agent.py - Tools · Task-specific functions for search, outfit suggestion, and fit card creation.
tools.py - Data loader · Shared helper for reading JSON assets into Python objects.
utils/data_loader.py - Search listings · Finds relevant secondhand items from the catalog.
tools.py - Suggest outfit · Combines wardrobe state and candidate listings into outfit ideas.
tools.py - Fit card · Formats the final style recommendation for the user.
tools.py
Local Data
Static JSON assets used for listings and wardrobe structure.
- Listings · Mock secondhand inventory used as search input.
data/listings.json - Wardrobe schema · Wardrobe structure plus example and empty templates.
data/wardrobe_schema.json
External Service
LLM provider used for agent reasoning.
- Groq API · External model service for agent reasoning and tool orchestration.
Connections 15
- App entry → Agent: start request · Application hands user input to the orchestration layer.
- Agent → Groq API: reasoning · Agent uses the model service for intent interpretation and planning.
- Agent → Tools: invoke · Agent selects and calls task-specific capabilities.
- Tools → Data loader: load data · Tools read structured JSON through the shared loader.
- Data loader → Listings: read · Catalog data is loaded from local JSON.
- Data loader → Wardrobe schema: read · Wardrobe structure and templates are loaded from local JSON.
- Tools → Search listings: expose · Search capability is part of the tool surface.
- Tools → Suggest outfit: expose · Outfit suggestion capability is part of the tool surface.
- Tools → Fit card: expose · Fit card creation capability is part of the tool surface.
- Search listings → Listings: filter · Search operates on the marketplace catalog.
- Suggest outfit → Listings: match · Outfit suggestion considers candidate items from the catalog.
- Suggest outfit → Wardrobe schema: combine · Outfit logic is grounded in wardrobe structure.
- Fit card → Agent: return · Final composed recommendation is returned through the agent flow.
- Planning → Agent: design input · Planning document specifies intended orchestration behavior.
- Deps → App entry: runtime deps · Dependency manifest supports the application runtime.