FoodSnap AI - Team unnita1235 Submission

.agents/rules/rules.md

@@ -0,0 +1,80 @@
+# FoodSnap AI — Project Rules (Anti-Hallucination Constitution)
+
+## CRITICAL: Code Quality Rules
+
+### Rule 1: No Hallucinated Imports
+- NEVER import a package, library, or module that has not been explicitly installed.
+- Before using ANY third-party package, first check if it exists in package.json (frontend) or requirements.txt (backend).
+- If it doesn't exist, add it to the dependency file AND run the install command BEFORE writing code that uses it.
+- NEVER invent package names. If you're unsure whether a package exists, say so.
+
+### Rule 2: No Hallucinated APIs
+- NEVER call an API endpoint that doesn't exist in this project.
+- NEVER assume an external API has a specific endpoint without verifying its documentation.
+- When integrating with external services (USDA, OpenAI, Supabase), always reference the ACTUAL documented API, not a guessed one.
+- If you're unsure about an API's exact endpoint or parameters, say "I need to verify this API" instead of guessing.
+
+### Rule 3: No Hallucinated File Paths
+- NEVER import from a file that doesn't exist in the project.
+- Before adding an import statement, verify the target file exists.
+- Use relative imports consistently. Don't mix relative and absolute import styles.
+
+### Rule 4: Verify Before Declaring Done
+- After writing any code, RUN it to verify it works.
+- For backend code: run the server and test with a curl command or the built-in browser.
+- For frontend code: start the dev server and visually verify in the browser.
+- NEVER say "this should work" — run it and SHOW me it works.
+
+### Rule 5: Error Handling is Mandatory
+- Every API call must have try/catch or equivalent error handling.
+- Every database query must handle connection failures.
+- Every file operation must handle missing files.
+- Every user input must be validated before processing.
+- No bare except/catch blocks — always catch specific errors.
+
+### Rule 6: No Placeholder Code
+- NEVER write `// TODO: implement this later` and move on.
+- NEVER write `pass` in Python and call a function complete.
+- If a function cannot be fully implemented, explain what's missing and what's needed.
+- Every function must either work completely or not exist.
+
+### Rule 7: Type Safety
+- Backend (Python): Use type hints on all function signatures.
+- Frontend (React/TypeScript): Use TypeScript interfaces for all props, state, and API responses.
+- Never use `any` type in TypeScript.
+- Never use untyped dictionaries in Python where a dataclass or TypedDict would work.
+
+## Architecture Rules
+
+### Tech Stack (Do Not Deviate)
+- Frontend: React Native with Expo (TypeScript)
+- Backend: Python 3.11+ with FastAPI
+- Database: PostgreSQL (via Supabase)
+- Cache: Redis (via Upstash, free tier)
+- Auth: Supabase Auth
+- Object Storage: Cloudflare R2 (free tier: 10GB)
+- AI: OpenAI GPT-4o API (primary), with fallback prompt for Gemini
+- Nutrition Data: USDA FoodData Central
+- Deployment: Backend on Render (free tier), Frontend on Expo/EAS
+
+### Code Style
+- Python: Follow PEP 8. Use Black formatter. Max line length 88.
+- TypeScript: Follow ESLint recommended. Use Prettier.
+- Naming: snake_case for Python, camelCase for TypeScript/React.
+- Files: One component per file in frontend. One router per file in backend.
+
+### Git Rules
+- Commit after every working feature (not after every file change).
+- Commit messages: imperative mood, present tense. "Add user auth endpoint" not "Added auth."
+- Never commit secrets, API keys, or .env files.
+
+### Testing Rules
+- Every backend endpoint must have at least one happy-path test and one error test.
+- Use pytest for Python. Use Jest for TypeScript.
+- Run tests before declaring any feature complete.
+
+## Communication Rules
+- When uncertain about a requirement, ASK before implementing.
+- When a task would take more than 50 lines of code, generate a PLAN first and wait for approval.
+- When you encounter an error, show the FULL error message, explain what caused it, and propose a fix.
+- Never silently swallow errors or hide failures.

.agents/skills/nutrition-api/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: nutrition-api
+description: Knowledge about the USDA FoodData Central API for nutrition lookups
+---
+
+# USDA FoodData Central API
+
+## Base URL
+https://api.nal.usda.gov/fdc/v1/
+
+## Authentication
+All requests require an API key as query parameter: ?api_key=YOUR_KEY
+Get a free key at: https://fdc.nal.usda.gov/api-key-signup.html
+
+## Key Endpoints
+
+### Search Foods
+GET /foods/search?query={query}&api_key={key}
+- Returns a list of matching foods with basic nutrition info
+- Use dataType=Foundation,SR%20Legacy for best results
+- pageSize default is 50, max 200
+
+### Get Food Details
+GET /food/{fdcId}?api_key={key}
+- Returns complete nutrition profile for a specific food
+- fdcId is the numeric identifier from search results
+
+## Important Notes
+- Rate limit: 3,600 requests per hour per API key (generous)
+- Nutrient IDs: 1008=calories, 1003=protein, 1004=fat, 1005=carbs
+- Values are per 100g unless otherwise specified
+- Some foods have multiple data types; prefer "Foundation" over "Survey"

.agents/skills/openai-vision/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: openai-vision
+description: Knowledge about using OpenAI GPT-4o API for food image analysis
+---
+
+# OpenAI GPT-4o Vision API for Food Analysis
+
+## Endpoint
+POST https://api.openai.com/v1/chat/completions
+
+## Required Headers
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+
+## Request Format for Image Analysis
+```json
+{
+  "model": "gpt-4o",
+  "messages": [
+    {
+      "role": "system",
+      "content": "You are a food identification system. [see full prompt in project docs]"
+    },
+    {
+      "role": "user",
+      "content": [
+        {
+          "type": "image_url",
+          "image_url": {
+            "url": "data:image/jpeg;base64,{base64_image}",
+            "detail": "low"
+          }
+        },
+        {
+          "type": "text",
+          "text": "Identify all food items in this image."
+        }
+      ]
+    }
+  ],
+  "max_tokens": 1000,
+  "response_format": { "type": "json_object" }
+}
+```
+
+## Cost (as of 2026)
+- Input: ~$0.0025 per image (low detail)
+- Input: ~$0.01 per image (high detail)
+- Output: ~$0.01 per 1K tokens
+- Total per analysis: $0.01-$0.03
+
+## Important Notes
+- Use detail: "low" for cost savings (512x512 resize)
+- Use detail: "high" only when identification fails on low
+- Always request JSON output format
+- The model can hallucinate food items — always cross-reference with USDA
+- Set max_tokens to 1000 — food responses are typically 200-400 tokens

.agents/workflows/build-section.md

@@ -0,0 +1,31 @@
+---
+description: Build a specific section of FoodSnap AI step by step
+---
+
+## Steps
+
+### 1. Read the requirement
+- Read the section specification from the prompt
+- List all files that will need to be created or modified
+- Identify all external dependencies needed
+
+### 2. Create implementation plan
+- Generate a numbered plan of what will be built
+- List all API endpoints, components, or functions
+- Wait for user approval before proceeding
+
+### 3. Implement
+- Write the code for each item in the plan
+- Install dependencies as needed
+- After each file: save, check for errors
+
+### 4. Verify
+- Run /verify-section workflow
+- If errors: fix them and re-verify
+- Only proceed when verification passes
+
+### 5. Report
+- List all files created/modified
+- List all new dependencies added
+- Show test results
+- Ask user: "Ready to move to the next section?"

.agents/workflows/verify-section.md

@@ -0,0 +1,26 @@
+---
+description: Verify that the current section/feature is fully working before proceeding
+---
+
+## Steps
+
+### 1. Check for syntax errors
+- Run the linter on all modified files
+- Fix any syntax or type errors
+
+### 2. Check for missing dependencies
+- Verify all imports reference installed packages
+- Run `pip install -r requirements.txt` or `npm install` if needed
+
+### 3. Start the service
+- For backend: start the FastAPI server and verify it responds to health check
+- For frontend: start the Expo dev server and verify it renders
+
+### 4. Run tests
+- Execute all tests related to the modified files
+- Report pass/fail results with details
+
+### 5. Manual verification
+- If the feature has a UI, open it in the browser and take a screenshot
+- If the feature is an API, make a test request and show the response
+- Confirm: "Section verified and working" or "Issues found: [list]"