happycolab 1.0.0__tar.gz

happycolab-1.0.0/PKG-INFO

@@ -0,0 +1,126 @@
+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())
+```

happycolab-1.0.0/README.md

@@ -0,0 +1,115 @@
+# 🌟 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())
+```

happycolab-1.0.0/happycolab/__init__.py

@@ -0,0 +1,17 @@
+"""
+HappyColab: A Python library for running LLMs in Google Colab and executing tools locally on your client machine.
+"""
+
+from .client import HappyClient, ColabClient
+from .agent import HappyAgent, ColabAgent, tool
+from .tools import ALL_DEFAULT_TOOLS
+
+__version__ = "1.0.0"
+__all__ = [
+    "HappyClient",
+    "HappyAgent",
+    "ColabClient",
+    "ColabAgent",
+    "tool",
+    "ALL_DEFAULT_TOOLS",
+]

happycolab-1.0.0/happycolab/agent.py

@@ -0,0 +1,365 @@
+"""
+ColabAgent: High-level Agent class with automatic tool schema generation,
+execution dispatch, and conversational memory.
+"""
+
+import inspect
+import json
+from typing import Callable, Dict, Any, List, Optional
+from .client import HappyClient
+
+
+def python_type_to_json_type(py_type: Any) -> str:
+    """Map python types to JSON schema types."""
+    if py_type in (int,):
+        return "integer"
+    if py_type in (float,):
+        return "number"
+    if py_type in (bool,):
+        return "boolean"
+    if py_type in (list, List):
+        return "array"
+    if py_type in (dict, Dict):
+        return "object"
+    return "string"
+
+
+def generate_tool_schema(func: Callable) -> Dict[str, Any]:
+    """
+    Automatically converts a Python function and its docstring/type hints
+    into an OpenAI-compatible function calling schema.
+    """
+    sig = inspect.signature(func)
+    doc = inspect.getdoc(func) or f"Execute {func.__name__}"
+
+    properties = {}
+    required = []
+
+    for name, param in sig.parameters.items():
+        if name in ("self", "cls"):
+            continue
+
+        param_type = param.annotation if param.annotation != inspect.Parameter.empty else str
+        json_type = python_type_to_json_type(param_type)
+
+        properties[name] = {
+            "type": json_type,
+            "description": f"Parameter '{name}'",
+        }
+
+        if param.default == inspect.Parameter.empty:
+            required.append(name)
+
+    return {
+        "type": "function",
+        "function": {
+            "name": func.__name__,
+            "description": doc,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        },
+    }
+
+
+def tool(func: Callable) -> Callable:
+    """
+    Standalone decorator to mark a Python function as a tool.
+    Usage:
+        @tool
+        def my_func(query: str) -> str:
+            '''Look up information.'''
+            return "data"
+
+        agent.add_tool(my_func)
+    """
+    func.__is_happy_tool__ = True
+    func.__tool_schema__ = generate_tool_schema(func)
+    return func
+
+
+class HappyAgent:
+    """
+    Intelligent Agent running against a Colab-hosted LLM with local tool execution.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        model: str = "qwen2.5:7b",
+        system_prompt: Optional[str] = None,
+        timeout: float = 90.0,
+    ):
+        self.client = HappyClient(url=url, model=model, timeout=timeout)
+        self.model = model
+        self.system_prompt = system_prompt or (
+            "You are a helpful and intelligent AI assistant. "
+            "You have access to tools that can be executed on the user's local machine. "
+            "When the user requests an action (such as opening a website or checking records), "
+            "use the relevant tool. Always provide friendly, direct answers."
+        )
+        self.tools_registry: Dict[str, Callable] = {}
+        self.tools_schema: List[Dict[str, Any]] = []
+        self.history: List[Dict[str, Any]] = [{"role": "system", "content": self.system_prompt}]
+
+    def tool(self, func: Callable) -> Callable:
+        """
+        Decorator to register a Python function as a tool on this agent instance.
+        Example:
+            @agent.tool
+            def open_google() -> str:
+                '''Opens Google in the web browser.'''
+                import webbrowser
+                webbrowser.open("https://www.google.com")
+                return "Google opened successfully"
+        """
+        self.add_tool(func)
+        return func
+
+    def add_tool(self, func: Callable, schema: Optional[Dict[str, Any]] = None):
+        """
+        Register a single function as an executable tool.
+        If no custom schema is provided, auto-generates schema from docstring and type hints.
+        """
+        self.tools_registry[func.__name__] = func
+        auto_schema = schema or getattr(func, "__tool_schema__", None) or generate_tool_schema(func)
+
+        # Replace existing schema if updating, or append
+        existing_idx = next((i for i, s in enumerate(self.tools_schema) if s.get("function", {}).get("name") == func.__name__), None)
+        if existing_idx is not None:
+            self.tools_schema[existing_idx] = auto_schema
+        else:
+            self.tools_schema.append(auto_schema)
+
+    def add_tools(self, funcs: List[Callable]):
+        """
+        Bulk register multiple functions as tools.
+        Example:
+            agent.add_tools([fetch_weather, calculate_tax, open_dashboard])
+        """
+        for f in funcs:
+            self.add_tool(f)
+
+    # Aliases
+    register_tool = add_tool
+    register_tools = add_tools
+
+    def load_default_tools(self):
+        """Load all built-in tools (Google, URLs, Time, Calculator, ID Card lookup)."""
+        from .tools import ALL_DEFAULT_TOOLS
+        for t in ALL_DEFAULT_TOOLS:
+            if t.__name__ not in self.tools_registry:
+                self.add_tool(t)
+
+    def set_model(self, model: str):
+        """Change the active model name."""
+        self.model = model.strip()
+        self.client.set_model(self.model)
+
+    def set_url(self, url: str):
+        """Update the active Colab URL."""
+        self.client.set_url(url)
+
+    def list_models(self) -> List[str]:
+        """List models available on the Colab server."""
+        return self.client.list_models()
+
+    def ping(self) -> bool:
+        """Verify server connection."""
+        return self.client.ping()
+
+    def reset_history(self):
+        """Clear conversation history."""
+        self.history = [{"role": "system", "content": self.system_prompt}]
+
+    def ask(self, user_query: str, verbose: bool = True) -> str:
+        """
+        Process a user input, execute tools if requested by the LLM, and return response.
+        """
+        self.history.append({"role": "user", "content": user_query})
+
+        # Request completion from Colab LLM
+        if self.tools_schema:
+            response_msg = self.client.chat_with_tools(
+                messages=self.history,
+                tools=self.tools_schema,
+            )
+        else:
+            raw_reply = self.client.chat(messages=self.history)
+            self.history.append({"role": "assistant", "content": raw_reply})
+            return raw_reply
+
+        # Handle tool execution loop
+        if response_msg.tool_calls:
+            self.history.append(response_msg)
+
+            for tool_call in response_msg.tool_calls:
+                func_name = tool_call.function.name
+                func_args_str = tool_call.function.arguments or "{}"
+                try:
+                    func_args = json.loads(func_args_str)
+                except Exception:
+                    func_args = {}
+
+                call_id = tool_call.id
+
+                if verbose:
+                    print(f"  ⚡ [Tool Executing] {func_name}({func_args})")
+
+                # Dispatch locally
+                if func_name in self.tools_registry:
+                    try:
+                        res = self.tools_registry[func_name](**func_args)
+                        output_str = json.dumps(res) if not isinstance(res, str) else res
+                    except Exception as err:
+                        output_str = json.dumps({"error": str(err)})
+                else:
+                    output_str = json.dumps({"error": f"Tool '{func_name}' is not registered."})
+
+                if verbose:
+                    print(f"  👉 [Result] {output_str}")
+
+                self.history.append({
+                    "role": "tool",
+                    "tool_call_id": call_id,
+                    "content": output_str,
+                })
+
+            # Get final formulated reply with tool results
+            final_reply = self.client.chat(messages=self.history)
+            self.history.append({"role": "assistant", "content": final_reply})
+            return final_reply
+        else:
+            reply = response_msg.content or ""
+            self.history.append({"role": "assistant", "content": reply})
+            return reply
+
+    def interactive_chat(self):
+        """Launch interactive terminal chat session with commands and error guidance."""
+        from .config import print_error_guide, save_config
+
+        print("\n" + "=" * 65)
+        print("🤖 HAPPYCOLAB AGENT - INTERACTIVE CHAT")
+        print(f"   Model       : {self.model}")
+        print(f"   Endpoint    : {self.client.url}")
+        print(f"   Tools Active: {list(self.tools_registry.keys()) or 'None'}")
+        print("\n💡 Commands:")
+        print("   /model <name>  -> Switch model (e.g. /model llama3.2:3b)")
+        print("   /models        -> List models on Colab")
+        print("   /url <link>    -> Change Colab Cloudflare URL")
+        print("   /tools         -> Show active tools")
+        print("   /clear         -> Reset conversation history")
+        print("   /help          -> Show troubleshooting guide")
+        print("   exit / quit    -> End chat")
+        print("=" * 65)
+
+        while True:
+            try:
+                user_msg = input("\nYou: ").strip()
+                if not user_msg:
+                    continue
+
+                # Exit command
+                if user_msg.lower() in ("exit", "quit", "q"):
+                    print("Goodbye!")
+                    break
+
+                # Help command
+                if user_msg.lower() == "/help":
+                    print_error_guide(self.client.url, "User requested /help guide.")
+                    continue
+
+                # Clear history
+                if user_msg.lower() == "/clear":
+                    self.reset_history()
+                    print("🧹 Conversation history cleared.")
+                    continue
+
+                # Show active tools
+                if user_msg.lower() == "/tools":
+                    print(f"\nRegistered Tools ({len(self.tools_registry)}):")
+                    for t_name, t_func in self.tools_registry.items():
+                        print(f"  • {t_name}: {inspect.getdoc(t_func) or 'No docstring'}")
+                    continue
+
+                # List models on Colab
+                if user_msg.lower() == "/models":
+                    print("Fetching models from Colab...")
+                    avail_models = self.list_models()
+                    if avail_models:
+                        print("Installed Models on Colab:")
+                        for m in avail_models:
+                            marker = " (Active)" if m == self.model else ""
+                            print(f"  • {m}{marker}")
+                    else:
+                        print(f"Current model is: {self.model}. (Could not query models list or only 1 loaded).")
+                    continue
+
+                # Change model command
+                if user_msg.lower().startswith("/model"):
+                    parts = user_msg.split(maxsplit=1)
+                    if len(parts) > 1:
+                        new_model = parts[1].strip()
+                        self.set_model(new_model)
+                        save_config(model=new_model)
+                        print(f"✅ Model switched to: '{new_model}'")
+                    else:
+                        print(f"Current model: '{self.model}'")
+                        new_model = input("Enter new model name (e.g. qwen2.5:7b, llama3.2:3b, mistral:7b): ").strip()
+                        if new_model:
+                            self.set_model(new_model)
+                            save_config(model=new_model)
+                            print(f"✅ Model switched to: '{new_model}'")
+                    continue
+
+                # Change URL command
+                if user_msg.lower().startswith("/url"):
+                    parts = user_msg.split(maxsplit=1)
+                    if len(parts) > 1:
+                        new_url = parts[1].strip()
+                    else:
+                        new_url = input("Enter new Colab Cloudflare URL: ").strip()
+
+                    if new_url:
+                        self.set_url(new_url)
+                        ok, msg = self.client.ping_detailed()
+                        if ok:
+                            save_config(url=new_url)
+                            print(f"✅ URL updated & verified: {new_url}")
+                        else:
+                            print_error_guide(new_url, msg)
+                    continue
+
+                # Normal conversational ask
+                response = self.ask(user_msg, verbose=True)
+                print(f"\n🤖 HappyColab LLM:\n{response}")
+
+            except KeyboardInterrupt:
+                print("\nSession paused.")
+                break
+            except Exception as e:
+                err_msg = str(e)
+                print(f"\n❌ Error encountered: {err_msg}")
+                # Print guided walkthrough
+                print_error_guide(self.client.url, err_msg)
+
+                # Offer immediate prompt to paste a new URL or model
+                prompt_fix = input("Paste your new Colab URL here (or press Enter to retry / skip): ").strip()
+                if prompt_fix:
+                    if prompt_fix.startswith("http"):
+                        self.set_url(prompt_fix)
+                        ok, msg = self.client.ping_detailed()
+                        if ok:
+                            save_config(url=prompt_fix)
+                            print(f"🎉 Successfully reconnected to: {prompt_fix}")
+                        else:
+                            print(f"⚠️ Still unable to connect: {msg}")
+                    else:
+                        print("Invalid URL format. Expected 'https://...trycloudflare.com'")
+
+
+# Backward compatibility alias
+ColabAgent = HappyAgent
+

happycolab-1.0.0/happycolab/cli.py

@@ -0,0 +1,63 @@
+"""
+Command-line interface entry point for happycolab and happy-chat.
+Provides guided error recovery, interactive link pasting, and model switching.
+"""
+
+import argparse
+import sys
+from .agent import HappyAgent
+from .config import load_config, save_config, print_error_guide
+
+DEFAULT_FALLBACK_URL = "https://polished-hang-corrections-skip.trycloudflare.com"
+DEFAULT_FALLBACK_MODEL = "qwen2.5:7b"
+
+
+def main():
+    cfg = load_config()
+    saved_url = cfg.get("url", DEFAULT_FALLBACK_URL)
+    saved_model = cfg.get("model", DEFAULT_FALLBACK_MODEL)
+
+    parser = argparse.ArgumentParser(
+        description="HappyColab: High-speed LLM client with local tool execution backed by Google Colab"
+    )
+    parser.add_argument("--url", default=saved_url, help=f"Cloudflare URL from Colab (default: {saved_url})")
+    parser.add_argument("--model", default=saved_model, help=f"Model name (default: {saved_model})")
+    parser.add_argument("--no-tools", action="store_true", help="Disable default local tools")
+    args = parser.parse_args()
+
+    active_url = args.url
+    active_model = args.model
+
+    agent = HappyAgent(url=active_url, model=active_model)
+
+    # Verify connection
+    print(f"\n🔍 Connecting to HappyColab LLM at: {active_url} (Model: {active_model}) ...")
+    connected, reason = agent.client.ping_detailed()
+
+    while not connected:
+        # Show guided troubleshooting steps
+        print_error_guide(active_url, reason)
+
+        user_input = input("👉 Paste your active Colab Cloudflare URL (or press Enter to exit): ").strip()
+        if not user_input:
+            print("\nExiting. Start your Colab notebook and run happycolab again anytime.")
+            sys.exit(0)
+
+        active_url = user_input
+        agent.set_url(active_url)
+        print(f"\nRetrying connection to: {active_url} ...")
+        connected, reason = agent.client.ping_detailed()
+
+        if connected:
+            save_config(url=active_url)
+            print(" Connected successfully!")
+            break
+
+    if not args.no_tools:
+        agent.load_default_tools()
+
+    agent.interactive_chat()
+
+
+if __name__ == "__main__":
+    main()

happycolab-1.0.0/happycolab/client.py

@@ -0,0 +1,110 @@
+"""
+Core API client for connecting to LLMs hosted on Google Colab or remote endpoints.
+"""
+
+from typing import List, Dict, Any, Generator, Optional
+from openai import OpenAI
+
+
+class HappyClient:
+    """
+    Connects to an OpenAI-compatible LLM server running in Google Colab via Cloudflare/ngrok.
+    """
+
+    def __init__(self, url: str, model: str = "qwen2.5:7b", timeout: float = 90.0):
+        self.timeout = timeout
+        self.model = model
+        self.set_url(url)
+
+    def set_url(self, url: str):
+        """Update Colab tunnel URL and reconfigure OpenAI client."""
+        base_url = url.strip().rstrip("/")
+        if not base_url.endswith("/v1"):
+            base_url = f"{base_url}/v1"
+        self.url = base_url
+        self.client = OpenAI(base_url=self.url, api_key="ollama", timeout=self.timeout)
+
+    def set_model(self, model: str):
+        """Update model name (e.g. 'qwen2.5:7b', 'llama3.2:3b', 'mistral:7b')."""
+        self.model = model.strip()
+
+    def ping(self) -> bool:
+        """Check if Colab server is reachable and active."""
+        ok, _ = self.ping_detailed()
+        return ok
+
+    def ping_detailed(self) -> tuple:
+        """
+        Check connection and return (success: bool, message: str).
+        """
+        try:
+            models = self.client.models.list()
+            return True, f"Connected! Found {len(models.data)} model(s) available."
+        except Exception as e:
+            err_str = str(e)
+            if "403" in err_str:
+                return False, "HTTP 403 Forbidden: Colab blocked the connection. Ensure OLLAMA_ORIGINS='*' and --http-host-header are configured in Colab."
+            if "Connection refused" in err_str or "Failed to connect" in err_str or "ConnectError" in err_str:
+                return False, "Connection Refused: Colab cell might not be running or Cloudflare tunnel is offline."
+            return False, f"Connection Failed: {err_str}"
+
+    def list_models(self) -> List[str]:
+        """List model names available on the Colab server."""
+        try:
+            res = self.client.models.list()
+            return [m.id for m in res.data]
+        except Exception:
+            return []
+
+    def chat(
+        self,
+        messages: List[Dict[str, Any]],
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+    ) -> str:
+        """Standard chat completion."""
+        res = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return res.choices[0].message.content or ""
+
+    def stream_chat(
+        self,
+        messages: List[Dict[str, Any]],
+        temperature: float = 0.7,
+    ) -> Generator[str, None, None]:
+        """Stream response tokens in real-time."""
+        stream = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=temperature,
+            stream=True,
+        )
+        for chunk in stream:
+            content = chunk.choices[0].delta.content
+            if content:
+                yield content
+
+    def chat_with_tools(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        tool_choice: str = "auto",
+        temperature: float = 0.2,
+    ):
+        """Invoke completion with tool definitions."""
+        res = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            tools=tools,
+            tool_choice=tool_choice,
+            temperature=temperature,
+        )
+        return res.choices[0].message
+
+
+# Backward compatibility alias
+ColabClient = HappyClient

happycolab-1.0.0/happycolab/config.py

@@ -0,0 +1,71 @@
+"""
+Configuration and troubleshooting helper for HappyColab.
+Manages persistent URLs, model preferences, and helpful error guidance.
+"""
+
+import json
+import os
+from typing import Dict, Any, Optional
+
+CONFIG_FILE_NAME = ".happycolab.json"
+
+
+def get_config_path() -> str:
+    """Returns local project config path, or user home directory path."""
+    cwd_path = os.path.join(os.getcwd(), CONFIG_FILE_NAME)
+    if os.path.exists(cwd_path):
+        return cwd_path
+    home_dir = os.path.expanduser("~")
+    return os.path.join(home_dir, CONFIG_FILE_NAME)
+
+
+def load_config() -> Dict[str, Any]:
+    """Loads saved config if exists."""
+    path = get_config_path()
+    if os.path.exists(path):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            return {}
+    return {}
+
+
+def save_config(url: Optional[str] = None, model: Optional[str] = None):
+    """Saves preferences to config file."""
+    cfg = load_config()
+    if url:
+        cfg["url"] = url
+    if model:
+        cfg["model"] = model
+    path = get_config_path()
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(cfg, f, indent=2)
+    except Exception:
+        pass
+
+
+def print_error_guide(url: str, reason: str = ""):
+    """
+    Displays a friendly, clear troubleshooting guide when connection fails.
+    """
+    print("\n" + "═" * 70)
+    print("⚠️   COULD NOT CONNECT TO GOOGLE COLAB LLM")
+    print("═" * 70)
+    if reason:
+        print(f"👉 Error Details: {reason}")
+    print(f"👉 Target URL   : {url}")
+    print("\n📋 STEP-BY-STEP TROUBLESHOOTING GUIDE:")
+    print("  1. Check Colab on Laptop 1:")
+    print("     Make sure your Google Colab tab is open and the notebook cell is actively running.")
+    print("  2. Cloudflare URLs are temporary:")
+    print("     Every time you restart Colab or restart the tunnel, a NEW .trycloudflare.com")
+    print("     URL is created. The previous link expires immediately.")
+    print("  3. Check for 403 Forbidden:")
+    print("     If you see a 403 error, ensure your Colab cell has:")
+    print("       os.environ['OLLAMA_ORIGINS'] = '*'")
+    print("       and cloudflared is run with: --http-host-header localhost:11434")
+    print("  4. Check GPU & Model:")
+    print("     In Colab, go to Runtime -> Change runtime type -> Ensure T4 GPU is selected.")
+    print("═" * 70 + "\n")

happycolab-1.0.0/happycolab/tools/__init__.py

@@ -0,0 +1,25 @@
+"""
+Built-in tools bundle for colab-llm.
+"""
+
+from .system_tools import open_google, open_url, get_system_time, calculate
+from .id_card_tools import lookup_id_card, verify_security_clearance
+
+ALL_DEFAULT_TOOLS = [
+    open_google,
+    open_url,
+    get_system_time,
+    calculate,
+    lookup_id_card,
+    verify_security_clearance,
+]
+
+__all__ = [
+    "open_google",
+    "open_url",
+    "get_system_time",
+    "calculate",
+    "lookup_id_card",
+    "verify_security_clearance",
+    "ALL_DEFAULT_TOOLS",
+]

happycolab-1.0.0/happycolab/tools/id_card_tools.py

@@ -0,0 +1,63 @@
+"""
+ID Card and Badge verification tools.
+"""
+
+from typing import Dict, Any
+
+MOCK_ID_DATABASE: Dict[str, Dict[str, Any]] = {
+    "ID-9021": {
+        "status": "active",
+        "name": "Sarah Connor",
+        "role": "Lead Systems Engineer",
+        "department": "Cybernetics Division",
+        "clearance_level": 4,
+        "expiry_date": "2028-12-31",
+    },
+    "ID-4420": {
+        "status": "suspended",
+        "name": "Alex Mercer",
+        "role": "Research Analyst",
+        "department": "Biotech Labs",
+        "clearance_level": 2,
+        "expiry_date": "2025-06-15",
+    },
+    "ID-1001": {
+        "status": "active",
+        "name": "John Doe",
+        "role": "Security Specialist",
+        "department": "Operations",
+        "clearance_level": 3,
+        "expiry_date": "2027-01-01",
+    },
+}
+
+
+def lookup_id_card(card_id: str) -> dict:
+    """
+    Looks up employee or member profile and status using an ID card number (e.g. 'ID-9021', 'ID-4420').
+    """
+    cleaned_id = card_id.strip().upper()
+    if cleaned_id in MOCK_ID_DATABASE:
+        return {"found": True, "record": MOCK_ID_DATABASE[cleaned_id]}
+    return {"found": False, "message": f"No record exists for card ID: {card_id}"}
+
+
+def verify_security_clearance(card_id: str, required_level: int) -> dict:
+    """
+    Checks if a given ID card has sufficient security clearance level (1 to 5).
+    """
+    cleaned_id = card_id.strip().upper()
+    if cleaned_id not in MOCK_ID_DATABASE:
+        return {"authorized": False, "reason": "ID card not found"}
+
+    record = MOCK_ID_DATABASE[cleaned_id]
+    if record["status"] != "active":
+        return {"authorized": False, "reason": f"Card status is {record['status']}"}
+
+    authorized = record["clearance_level"] >= required_level
+    return {
+        "authorized": authorized,
+        "name": record["name"],
+        "clearance_level": record["clearance_level"],
+        "required_level": required_level,
+    }

happycolab-1.0.0/happycolab/tools/system_tools.py

@@ -0,0 +1,53 @@
+"""
+Standard built-in system tools (Web browsing, search, time, calculator).
+"""
+
+import webbrowser
+import datetime
+import urllib.parse
+
+
+def open_google(search_query: str = "") -> str:
+    """
+    Opens Google in the default web browser. If a search query is provided, searches for it.
+    """
+    if search_query:
+        query_encoded = urllib.parse.quote(search_query)
+        target = f"https://www.google.com/search?q={query_encoded}"
+        webbrowser.open(target)
+        return f"Opened Google search for '{search_query}' in your web browser."
+    else:
+        webbrowser.open("https://www.google.com")
+        return "Opened Google in your web browser."
+
+
+def open_url(url: str) -> str:
+    """
+    Opens any website URL in the user's default browser (e.g. 'https://github.com').
+    """
+    if not url.startswith("http://") and not url.startswith("https://"):
+        url = "https://" + url
+    webbrowser.open(url)
+    return f"Opened website: {url}"
+
+
+def get_system_time() -> str:
+    """
+    Returns the current local date, time, and timezone on this machine.
+    """
+    now = datetime.datetime.now()
+    return f"Current local time: {now.strftime('%Y-%m-%d %H:%M:%S')}"
+
+
+def calculate(expression: str) -> str:
+    """
+    Evaluates basic mathematical expressions like '25 * 4 + 10' safely.
+    """
+    allowed_chars = set("0123456789+-*/(). %")
+    if not all(c in allowed_chars for c in expression):
+        return "Error: Expression contains unsupported characters."
+    try:
+        result = eval(expression, {"__builtins__": None}, {})
+        return f"Result: {result}"
+    except Exception as e:
+        return f"Calculation error: {e}"

happycolab-1.0.0/happycolab.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+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())
+```

happycolab-1.0.0/happycolab.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+setup.py
+happycolab/__init__.py
+happycolab/agent.py
+happycolab/cli.py
+happycolab/client.py
+happycolab/config.py
+happycolab.egg-info/PKG-INFO
+happycolab.egg-info/SOURCES.txt
+happycolab.egg-info/dependency_links.txt
+happycolab.egg-info/entry_points.txt
+happycolab.egg-info/requires.txt
+happycolab.egg-info/top_level.txt
+happycolab/tools/__init__.py
+happycolab/tools/id_card_tools.py
+happycolab/tools/system_tools.py

happycolab-1.0.0/happycolab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

happycolab-1.0.0/happycolab.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+happy-chat = happycolab.cli:main
+happycolab = happycolab.cli:main

happycolab-1.0.0/happycolab.egg-info/requires.txt

@@ -0,0 +1,3 @@
+openai>=1.30.0
+requests>=2.31.0
+pydantic>=2.0.0

happycolab-1.0.0/happycolab.egg-info/top_level.txt

@@ -0,0 +1 @@
+happycolab

happycolab-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "happycolab"
+version = "1.0.0"
+description = "HappyColab: High-speed LLM bridge between Google Colab GPU and local machines with native tool execution"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [{ name = "Aswin Lal S Y" }]
+dependencies = [
+    "openai>=1.30.0",
+    "requests>=2.31.0",
+    "pydantic>=2.0.0"
+]
+
+[project.scripts]
+happycolab = "happycolab.cli:main"
+happy-chat = "happycolab.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["happycolab*"]

happycolab-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

happycolab-1.0.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()