Metadata-Version: 2.4
Name: happycolab
Version: 1.0.0
Summary: HappyColab: High-speed LLM bridge between Google Colab GPU and local machines with native tool execution
Author: Aswin Lal S Y
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.30.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=2.0.0

# 🌟 HappyColab (Python Library)

**HappyColab** is a high-speed Python client and AI agent framework that lets you run Large Language Models in **Google Colab** (with free GPU acceleration) and call them from any other machine with **native Tool & Function Calling**, real-time streaming, error recovery guides, and interactive chat.

---

## 📁 Repository Structure

```text
HappyColab/
├── happycolab/                 # 📦 Library Source Code
│   ├── __init__.py             # Exports HappyAgent, HappyClient, tool
│   ├── agent.py                # Agent with auto-schema tool decorator & loop
│   ├── client.py               # Low-level OpenAI-compatible API connector
│   ├── config.py               # Error recovery, guided troubleshooting & configs
│   ├── cli.py                  # CLI command runner (happycolab, happy-chat)
│   └── tools/                  # Built-in tool suite
│       ├── system_tools.py     # Open Google, open URL, calculate, local time
│       └── id_card_tools.py    # ID card verification & clearance checks
│
├── examples/                   # 💡 Ready-to-Run Examples
│   ├── 01_simple_chat.py       # Basic single-turn Q&A
│   ├── 02_streaming.py         # Real-time token streaming
│   ├── 03_custom_tool.py       # Adding a custom tool
│   ├── 04_full_assistant.py    # Interactive assistant with all default tools
│   └── 05_custom_function_calling.py # All 3 ways to register function calling
│
├── colab_server/               # 🚀 Laptop 1 (Colab Server Files)
│   ├── colab_server_code.py    # Copy-pasteable script for Google Colab
│   └── colab_server_notebook.ipynb # Ready-to-upload Colab notebook
│
├── .gitignore
├── pyproject.toml
├── setup.py
└── requirements.txt
```

---

## ⚡ Quick Start

### 1. Launch Server (Laptop 1 - Google Colab)
Open [`colab_server/colab_server_notebook.ipynb`](colab_server/colab_server_notebook.ipynb) in Colab with T4 GPU. Copy the public Cloudflare URL (e.g. `https://xxxx.trycloudflare.com`).

### 2. Interactive Chat (Laptop 2)
The library is installed in your Python environment. You can immediately launch the interactive AI chat:

```powershell
happycolab
```
*(Or alias: `happy-chat`)*

If your URL is expired or unreachable, **HappyColab displays a step-by-step troubleshooting guide** and lets you paste your new URL directly into the prompt!

---

## 🛠️ Adding Function Calling (3 Ways)

Users can add custom functions for the LLM to call in any of these 3 ways:

### Method 1: Using `@agent.tool` Decorator
Type hints and docstrings are automatically converted into OpenAI function calling schemas:
```python
from happycolab import HappyAgent

agent = HappyAgent(url="https://your-url.trycloudflare.com")

@agent.tool
def get_user_profile(user_id: str) -> dict:
    """Fetch employee department and clearance by User ID."""
    return {"user_id": user_id, "name": "Jane Miller", "department": "AI Security"}
```

### Method 2: Using the Standalone `@tool` Decorator
```python
from happycolab import HappyAgent, tool

@tool
def calculate_tax(amount: float, tax_rate_percent: float = 10.0) -> dict:
    """Calculate tax and total cost for a transaction."""
    tax = amount * (tax_rate_percent / 100.0)
    return {"subtotal": amount, "tax": tax, "total": amount + tax}

agent = HappyAgent(url="https://your-url.trycloudflare.com")
agent.add_tool(calculate_tax)
```

### Method 3: Registering Regular Python Functions (No Decorators!)
```python
def check_server(server_name: str) -> dict:
    """Check health and ping of an internal server."""
    return {"server": server_name, "status": "ONLINE", "uptime": "99.9%"}

agent.add_tool(check_server)
# Or bulk register:
# agent.add_tools([func_a, func_b, func_c])
```

---

## 🔀 Flexible Model Switching

### In Terminal Chat:
While chatting inside `happycolab`, you can use slash commands:
- `/model llama3.2:3b` ➔ Switch model dynamically.
- `/models` ➔ Query all models installed on your Colab instance.
- `/url <new_url>` ➔ Change the tunnel URL on the fly.
- `/tools` ➔ View active tools.
- `/help` ➔ Show troubleshooting guide.

### In Python:
```python
agent.set_model("llama3.2:3b")
print(agent.list_models())
```
