Wingman

An AI-powered chatbot that acts as your wingman, answering questions about using your documents, portfolio, and blog content. Built with LangChain, FastAPI, and powered by advanced language models.

🎯 What It Does

Wingman is a conversational AI application that:

• Answers Questions Intelligently - Responds to user queries about your background, experience, and portfolio
• Retrieves Relevant Information - Uses vector search (RAG) to find and cite relevant documents
• Maintains Conversation Context - Keeps track of multi-turn conversations with thread IDs
• Streams Responses - Provides real-time streaming responses for better UX
• Manages Multiple Document Types - Supports portfolios, blogs, and PDF documents

✨ Key Features

• Vector-Based Retrieval: Uses Chroma vector database for semantic document search
• Persistent Conversations: Maintains conversation threads with full history using Postgres
• Tool-Integrated Agents: LangChain agents with tool calling capabilities
• Streaming Responses: Real-time chat streaming for responsive UI

📋 Prerequisites

• Python 3.13 or higher
• Postgres database (for conversation persistence)
• API keys for:
  • Google Generative AI (GOOGLE_API_KEY)
  • Cloudflare Workers AI (CF_ACCOUNT_ID, CF_AI_API_TOKEN)
  • Chroma Vector Database (CHROMA_API_KEY, CHROMA_TENANT, CHROMA_DATABASE)
• Admin credentials for authentication (ADMIN_NAME, ADMIN_PASSWORD)

🚀 Setup

1. Clone and Install

git clone <repository-url>cd wingman
uv sync

2. Configure Environment Variables

Create a .env file in the root directory with from .env.example and fill in your API keys and credentials.

3. Run the Server

Local Development

uv run main

Docker

docker build -t wingman .
docker run --env-file .env -p 8000:8000 wingman

The API will start on http://localhost:8000

📚 Project Structure

wingman/
├── main.py # FastAPI application and endpoints
├── src/
│ ├── __init__.py
│ └── ai/
│ ├── __init__.py
│ ├── agents.py # LangChain agent configuration
│ ├── tools.py # Tool definitions for agents
│ ├── doc_manager.py # Document storage and management
│ └── store.py # Vector store initialization
├── Dockerfile # Docker container configuration
├── .dockerignore # Docker build ignore file
├── .env.example # Example environment variables
├── pyproject.toml # Project dependencies and metadata
├── requirements.txt # Pip dependencies (for Docker)
├── uv.lock # Locked dependencies (uv)
├── README.md # This file
└── LICENCE # Project license

🔌 API Endpoints

Chat Endpoint

POST/chat

Send a message and get a streaming response.

Request:

{
"thread_id": "unique-thread-id",
"prompt": "Tell me about the admin's experience"
}

Response: Streaming text responses

Document Management

• POST/upload - Upload resume (PDF URL), portfolio URL, and blog URL

🛠️ Technologies Used

• Framework: FastAPI
• AI/ML: LangChain, LanGraph
• LLMs: Google Generative AI, Cloudflare Workers AI
• Vector Database: Chroma
• Document Processing: BeautifulSoup4, PyPDF
• Web Framework: Uvicorn (FastAPI default)

📝 Usage Example

importrequests# Start a new conversationthread_id="user-123-conversation-1"# Send a messageresponse=requests.post(
"http://localhost:8000/chat",
json={
"thread_id": thread_id,
"prompt": "What are their main skills?"
},
stream=True
)
# Stream the responseforchunkinresponse.iter_content(decode_unicode=True):
print(chunk, end="", flush=True)

🔐 Authentication

The application requires admin authentication for sensitive operations. Configure admin credentials via environment variables.