Hands‑On AI Engineering – Technical Briefing

Clone: git clone https://github.com/moses-y/Hands-On-AI-Engineering

The Problem

The repository is a portfolio of five independent AI projects (AI agents, RAG, multimodal, OCR, audio) that lacks production‑ready fundamentals. No license, no CI/CD, duplicated logic, and missing lockfiles make it unsuitable for direct client reuse without significant cleanup.

What This Does

The repo contains 5 self‑contained projects organized under ai_agents/, rag_apps/, multimodal/, OCR/, and audio/.

  • AI agents (254 files) include form‑filling, SQL search, travel planning, and financial analysis agents. Notable entry points: ai_agents/agentic-form-filler/app.py, ai_agents/agentic_sql_search/app.py, ai_agents/finagent/main.py.
  • RAG applications (92 files) provide hybrid/graph‑RAG pipelines; key hubs are rag_apps/rag_agent_with_database_routing/rag_agent/pipeline (Ca 1 Ce 5, instability 0.83) and rag_apps/hybrid_rag_system/app.py.
  • Multimodal (39 files) mixes vision‑language models; multimodal/multimodal_rag/rag.py defines embed and query functions used by seven other files.
  • OCR (18 files) implements receipt, prescription, and formula digitisation; OCR/image_to_structured_data/app.py and OCR/latex_formula_ocr/app.py are the primary entry points.
  • Audio (15 files) features a music explorer (audio/music_explorer/app.py, entry load_yt).

Each project ships its own requirements.txt (or pyproject.toml) and .env.example for configuration.

How It Is Wired

Execution starts at the listed entry points; the internal call graph resolves 593 self‑call edges.

  • Main entry points (functions reached from the start):
  • main in OCR/latex_formula_ocr/app.py:413 → 112 functions.
  • analyze_stock in ai_agents/finagent/main.py:10 → 43 functions (called by nothing else in repo).
  • run in ai_agents/offline_medical_agent/offline_medical_agent/agents.py:103 → 18 functions.
  • load_yt in audio/music_explorer/app.py:350 → 20 functions.
  • _run in ai_agents/smolagents_code_agent/app.py:79 → 19 functions.
  • run_vector in rag_apps/hybrid_rag_system/app.py:329 → 17 functions.
  • Hot functions (called from many places): search (19 callers), _save (8), query (6), complete (6).
  • Out‑of‑process effects (from WHAT THIS CODE TOUCHES OUTSIDE ITSELF): 31 file I/O ops, 38 model inference calls, 28 network calls (e.g., main → check_ollama_status via requests.get), 9 DB operations.
  • Hubs with blast radius: rag_apps/rag_agent_with_database_routing/rag_agent/pipeline (high fan‑in, instability 0.83) and ai_agents/agentic-form-filler/llm.py (broad except handling).

A file‑by‑file responsibility map (from the “WHAT EACH FILE IS RESPONSIBLE FOR” block) shows that rag_apps/graphrag_knowledge_system/src/vector_store.py is called from 21 other files and makes an outbound network call, while ai_agents/personal_finance_agent/agent.py reads/writes a database and files and calls a model.

How To Use It

  1. Clone the repo (URL above).
  2. Install dependencies per project – each has a requirements.txt or pyproject.toml. Example for the OCR image‑to‑structured‑data project: ``bash cd OCR/image_to_structured_data python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt # installs flask, pytesseract, etc. ``
  3. Copy the environment template – .env.example files exist for OCR and AI‑agent projects; fill in keys (Ollama, OpenAI, etc.).
  4. Run the entry point – most projects expose an app.py that can be started with python app.py or, where a pyproject.toml is present, uv run app.py.
  5. Optional: lockfile – the ai_agents/agent_discovery_agent directory already has uv.lock; run uv pip sync to freeze transitive dependencies and commit the lockfile for reproducible builds.

If a specific project lacks an obvious run command, consult its README.md (present for most folders) or the app.py guard if __name__ == "__main__" block.

Real‑World Use

Scenario: Digitising a stack of payment receipts for bookkeeping.

  • Use OCR/image_to_structured_data/app.py which accepts an image (payment-receipt.png in assets/), runs processor.py (extracts text via Tesseract), and outputs a JSON structure defined in schemas.py.
  • The pipeline reads the image, resizes it (resize_if_needed), converts to base64 (to_base64), and returns a StructuredProduct‑style payload that can be dropped into a financial ledger API.
  • No model inference is required; the tooling is pure image‑processing, making it quick to prototype or embed in a larger ETL flow.

Code Health & Issues

Static analysis (measured) reports 77 findings across 9 high, 68 medium categories:

  • [HIGH/clarity] Duplicated 6‑line blocks (131 occurrences) in ai_agents/agent_discovery_agent/app.py, ai_agents/cal_scheduling_agent/app.py, ai_agents/hotel_finder_agent/app.py, multimodal/multimodal_rag/app.py, … – extract shared helpers.
  • [HIGH/cognitive_load] Deep nesting (max indentation depth 8) in ai_agents/agentic-form-filler/app.py, pdf_filler.py, ai_agents/job_posting_agent/app.py – flatten with guard clauses.
  • [MEDIUM/resource_safety] 11 open(...) calls without context managers: OCR/image_to_structured_data/processor.py, OCR/latex_formula_ocr/app.py, OCR/medical_prescription_digitizer/app.py – wrap in with open(...) as f:.
  • [MEDIUM/resilience] 25 broad except clauses swallowing errors: OCR/latex_formula_ocr/app.py, ai_agents/agentic-form-filler/llm.py, ai_agents/agentic_sql_search/app.py – catch specific exceptions.

SDLC observations (beyond the measured block):

  • No license at repository root – redistribution rights undefined.
  • No CI/CD – no automated build/test gate.
  • No lockfile alongside manifests (e.g., ai_agents/agentic_sql_search/pyproject.toml).
  • No dependabot/renovate configuration – 53 manifests unmonitored for updates.
  • Large binaries committed: ai_agents/travel_planner_agent/assets/demo.gif (23.1 MB), plus two other GIFs > 10 MB – track with Git LFS or move to object storage.
  • Test coverage is minimal: 6 test files vs. 161 source files (ratio 0.037).

The Bottom Line

This repo is a valuable portfolio of ready‑to‑run AI demos covering OCR, RAG, agents, and multimodal pipelines. However, production adoption is blocked by missing licensing, no reproducibility guard (no lockfile/CI), duplicated logic, and low test coverage. It is best suited for learning, prototyping, or as a starting point after a cleanup pass (add MIT/Apache‑2.0 license, commit lockfiles, enable CI, and expand tests on the highest‑fan‑in modules). Teams that need a solid foundation will want to fork, apply the listed fixes, and then tailor the projects to their own stacks.