Voyagio AI Travel Assistant

Autonomous AI Concierge with Blockchain Payments

Built for the Scoop AI Hackathon: Seoul Bowl (December 20-21, 2025)

Hackathon Tracks

Agentic Infrastructure - SpoonOS implementation
Autonomous Finance - Neo Blockchain integration (Bonus!)

Architecture

User Request → TravelConcierge Agent → SearchTool → Flight/Hotel Results
                        ↓
              CryptoTreasurer Agent → NeoWalletTool → Neo N3 Testnet Transaction
                        ↓
              Confirmed Itinerary + Transaction Hash (TxID)

Quick Start

Option 1: Docker (Recommended)

# Configure environment
cp backend/.env.example backend/.env
# Edit backend/.env with your API keys (see Required API Keys below)

# Start everything
docker-compose up --build

# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000

Option 2: Manual Setup

Prerequisites

Python 3.10+
Node.js 18+
Neo N3 Testnet Wallet

Backend Setup

cd backend

# Install dependencies
pip install -r requirements.txt

# Configure Environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY (Required) and NEO_PRIVATE_KEY (Required)

# Run the API Server
python server.py
# Server running at http://localhost:8000

Frontend Setup

cd frontend
npm install
npm run dev
# Open http://localhost:5173

CLI Demo Mode (Alternative)

cd backend
python main.py --demo

Required API Keys

Key	Required	Get From
`GEMINI_API_KEY`	Yes	Google AI Studio
`NEO_PRIVATE_KEY`	Yes	Your Neo N3 wallet
`NEO_RPC_URL`	No	Default: `https://testnet1.neo.coz.io:443`

Project Structure

velvet-protocol/
├── plan/                    # Project specifications (Kiro methodology)
│   ├── requirements.md      # User stories & acceptance criteria
│   ├── design.md            # Technical architecture & data models
│   └── tasks.md             # Implementation checklist
├── backend/                 # Python FastAPI backend
│   ├── server.py            # FastAPI server
│   ├── main.py              # CLI entry point
│   ├── config.py            # Configuration loader
│   ├── requirements.txt     # Python dependencies
│   ├── .env.example         # Environment template
│   ├── src/
│   │   ├── agents.py        # TravelConcierge & CryptoTreasurer
│   │   ├── state.py         # State management
│   │   └── tools/
│   │       ├── neo_wallet.py    # Neo N3 blockchain tool
│   │       └── search.py        # Travel search tool
│   └── data/
│       └── user_profile.json    # User preferences
├── frontend/                # React + Vite + TypeScript
│   ├── src/
│   │   ├── types/           # TypeScript interfaces
│   │   ├── services/        # API client
│   │   └── components/      # React components
│   └── package.json
├── Agents.md                # AI agent coding instructions
├── CLAUDE.md                # Claude-specific instructions
├── assigning.md             # Team task assignments
└── docker-compose.yml       # Docker orchestration

Project Workflow Documentation

This project uses spec-driven development following the Kiro IDE methodology. Below are the key documentation files that guide development.

Plan Folder (`./plan/`)

The plan/ folder is the source of truth for all implementation work.

File	Purpose	When to Use
`requirements.md`	User stories with EARS-format acceptance criteria	Before implementing any feature
`design.md`	Technical architecture, data models, API specs	Before writing any code
`tasks.md`	Phased implementation checklist with subtasks	Track progress, mark completed items

AI Agent Instructions

File	Purpose	Who Should Read
`Agents.md`	Universal instructions for ALL AI coding agents	Any AI assistant working on this project
`CLAUDE.md`	Claude-specific instructions and reminders	Claude AI specifically

Key Rules Enforced:

NO any types - Zero tolerance in TypeScript and Python
NO mock data - All production code uses real APIs
Full type annotations - Every function must be typed
Read plan first - Always check specifications before coding
Update tasks - Mark checkboxes when completing work

Task Assignments (`assigning.md`)

The assigning.md file divides all tasks from tasks.md among team members:

Team Member	Focus Area
Ricky	Infrastructure, Docker, DevOps, SpoonOS
Abdul	Blockchain, Neo N3, Wallet integration
윤주	Frontend, TypeScript, React components
Yuriy	Testing, Backend APIs, Documentation
유민	UI/UX, Styling, Presentation

Each member has:

Specific task assignments with checkboxes
List of files they own
Dependencies on other members
Phase-by-phase breakdown

Workflow for AI Agents

When an AI agent starts working on this project:

1. Read ./CLAUDE.md (or ./Agents.md)
2. Read ./plan/requirements.md
3. Read ./plan/design.md
4. Read ./plan/tasks.md
5. Find your assigned tasks in ./assigning.md
6. Implement following the specifications
7. Mark completed tasks with [x] in tasks.md

Agents

TravelConcierge

Role: Senior Travel Logistics Manager
Tools: SearchTool
LLM: Gemini 2.5 Flash via SpoonOS
Task: Find optimal flights and hotels matching user preferences

CryptoTreasurer

Role: Financial Controller
Tools: NeoWalletTool
LLM: Gemini 2.5 Flash via SpoonOS
Task: Execute blockchain payments and manage budget
Auto-approve: < $50 (configurable)

Custom Tools

NeoWalletTool

Neo N3 blockchain operations (REAL testnet, no mocks):

balance - Check NEO/GAS balance via RPC
pay - Send GAS transaction on testnet
sign - Cryptographically sign messages

SearchTool

Travel search operations (REAL APIs):

flight - Search for flights via DuckDuckGo
hotel - Search for hotels via DuckDuckGo
Crypto-friendly filtering

API Endpoints

Chat & Search

Endpoint	Method	Description
`/api/chat`	POST	Send message to AI agents
`/health`	GET	Service health check

Wallet Operations

Endpoint	Method	Description
`/api/wallet/balance`	GET	Get NEO/GAS balance
`/api/wallet/pay`	POST	Execute GAS payment

User Profile

Endpoint	Method	Description
`/api/profile`	GET	Get user profile
`/api/profile`	PUT	Update preferences
`/api/bookings`	GET	Get booking history
`/api/bookings`	POST	Record new booking

Testing

# Run backend unit tests
cd backend
pip install pytest pytest-asyncio
pytest tests/ -v

# Run type safety validation
./scripts/type_check.sh

# Run Docker integration tests
./scripts/test_docker.sh

Neo N3 Integration

Network: Neo N3 Testnet
RPC: https://testnet1.neo.coz.io:443
SDK: neo-mamba (Python)
Token: GAS for payments
Explorer: Dora

Get Test GAS

Visit: https://neowish.ngd.network/
Enter your Neo address
Receive free testnet GAS

Code Quality Standards

This project enforces strict code quality:

Standard	Enforcement
No `any` types	TypeScript strict mode, mypy strict
No mock data	All production code uses real APIs
Full type annotations	Every function fully typed
Real API integration	Gemini, Neo N3, DuckDuckGo

Hackathon Compliance

SpoonOS Core: Uses SpoonReactAI with ToolManager
LLM via SpoonOS: Agent → SpoonOS → Gemini 2.5 Flash
Custom Tools: NeoWalletTool, SearchTool
Neo Technologies: neo-mamba for REAL testnet (Bonus!)
Working Demo: Full-stack application with Docker
UI/UX: Premium React + TypeScript Frontend
Type Safety: Zero any types, full annotations

Team

Name	Role
Ricky	Infrastructure & DevOps
Abdul	Blockchain & Neo N3
윤주	Frontend & TypeScript
Yuriy	Testing & Backend APIs
유민	UI/UX & Design

Built for the Scoop AI Hackathon: Seoul Bowl

Design

Figma Design

Voyagio AI - Making autonomous travel bookings seamless with AI and blockchain.

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
backend		backend
frontend		frontend
plan		plan
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
Agents.md		Agents.md
CLAUDE.md		CLAUDE.md
DEMO_SCRIPT.md		DEMO_SCRIPT.md
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
assigning.md		assigning.md
docker-compose.yml		docker-compose.yml
presentation_slides.md		presentation_slides.md
requirements.txt		requirements.txt

fastians/voyagio

Folders and files

Latest commit

History

Repository files navigation