metadata

title: Craftwise
emoji: 🧶
colorFrom: green
colorTo: green
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
license: mit
tags:
  - agent-demo-track
  - agents

🧶 Agent Demo Track: Craftwise

Craftwise is an AI-native learning assistant for hands-on crafts including (but not limited to!) origami, knitting, and crochet, and even more exotic crafts like Balkan lacework or Kente cloth making. It guides users through creative projects with smart project suggestions, real-time explanations, YouTube tutorial retrieval, and visual feedback on uploaded photos.

Built with a multi-agent architecture using LangGraph and powered by LLMs, Craftwise helps users learn-by-doing—just like a friendly workshop mentor.

Watch our demo video on Loom

✨ Features

🎨 Personalized craft project recommendations
🤖 Multi-agent orchestration with LangGraph
🔍 YouTube tutorial search
📷 Visual feedback on uploaded craft work
💬 Conversational interface via Gradio
🧵 Modular agent setup for easy extension

🚀 Getting Started

1. Clone the Repository

git clone https://huggingface.co/spaces/Agents-MCP-Hackathon/craftwise
cd craftwise

2. Install Dependencies with uv

uv venv
source .venv/bin/activate
uv sync

ℹ️ Don't have uv installed?
Install via pip: pip install uv

3. Configure Environment Variables

Copy the example file and set your keys:

cp .env.example .env

Fill in:

Gemini API key - for the LLM calls
Google Maps API key - for searching local craft shops
YouTube API key (usually the same as Google Maps API key retrieved from your Google Cloud Console)
Tavily API key - for searching the web

4. Run the Gradio App

gradio app.py

Then open your browser at: http://localhost:7860

🧭 Project Structure

craftwise/
├── agents/           # LangGraph agents: Planner, Mentor, Perception
├── analysis_utils.py # Media analysis logic
├── app.py            # Gradio interface
├── main.py           # LangGraph supervisor setup
├── .env.example      # Sample environment config
└── resources/        # Static images, backgrounds, styles

🧪 Development Notes

🧠 Agents are defined modularly under agents/
🧵 Media feedback handled by PerceptionAgent (analyze_media_structured)
🔎 YouTube search is integrated via API with fallback validation
🌐 Background and UI assets are served via FastAPI + Gradio hybrid

🧩 Ideas for Expansion

Track user learning progress over time
Search for online or in-presence workshops and connect to teachers who know the craft

🤝 Contributing

Pull requests and forks welcome!
To contribute:

Fork the repo
Create a feature branch: git checkout -b feature/my-feature
Commit your changes: git commit -m "Add awesome feature"
Push and open a PR

📄 License

Made by: Alisa Bogatinovski and Jasmin Bogatinovski

Made with code, curiosity, and a little bit of yarn. 🧶