---
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](https://www.loom.com/share/fb64d6e163c142a8bd634e483c6165b1#Settings)**

---

## ✨ 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**

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

### 2. **Install Dependencies with [uv](https://github.com/astral-sh/uv)**

```bash
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:

```bash
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**

```bash
gradio app.py
```

Then open your browser at: [http://localhost:7860](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:

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

---

## 📄 License

MIT License © 2025 

Made by: [Alisa Bogatinovski](https://www.linkedin.com/in/alisakrstova) and [Jasmin Bogatinovski](https://www.linkedin.com/in/bogatinovskijasmin/)

---

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