npcpy 1.3.9__py3-none-any.whl → 1.3.11__py3-none-any.whl

npcpy/serve.py

@@ -42,7 +42,8 @@ class SilentUndefined(Undefined):
         return ""
 
 # Import ShellState and helper functions from npcsh
-from npcsh._state import ShellState
+from npcsh._state import ShellState, initialize_base_npcs_if_needed
+from npcsh.config import NPCSH_DB_PATH
 
 
 from npcpy.memory.knowledge_graph import load_kg_from_db
@@ -814,19 +815,44 @@ def _get_jinx_files_recursively(directory):
 @app.route("/api/jinxs/available", methods=["GET"])
 def get_available_jinxs():
     try:
+        import yaml
         current_path = request.args.get('currentPath')
         jinx_names = set()
 
+        def get_jinx_name_from_file(filepath):
+            """Read jinx_name from file, fallback to filename."""
+            try:
+                with open(filepath, 'r') as f:
+                    data = yaml.safe_load(f)
+                    if data and 'jinx_name' in data:
+                        return data['jinx_name']
+            except:
+                pass
+            return os.path.basename(filepath)[:-5]
+
+        # 1. Project jinxs
         if current_path:
             team_jinxs_dir = os.path.join(current_path, 'npc_team', 'jinxs')
             jinx_paths = _get_jinx_files_recursively(team_jinxs_dir)
             for path in jinx_paths:
-                jinx_names.add(os.path.basename(path)[:-5])
+                jinx_names.add(get_jinx_name_from_file(path))
 
+        # 2. Global user jinxs (~/.npcsh)
         global_jinxs_dir = os.path.expanduser('~/.npcsh/npc_team/jinxs')
         jinx_paths = _get_jinx_files_recursively(global_jinxs_dir)
         for path in jinx_paths:
-            jinx_names.add(os.path.basename(path)[:-5])
+            jinx_names.add(get_jinx_name_from_file(path))
+
+        # 3. Package built-in jinxs (from npcsh package)
+        try:
+            import npcsh
+            package_dir = os.path.dirname(npcsh.__file__)
+            package_jinxs_dir = os.path.join(package_dir, 'npc_team', 'jinxs')
+            jinx_paths = _get_jinx_files_recursively(package_jinxs_dir)
+            for path in jinx_paths:
+                jinx_names.add(get_jinx_name_from_file(path))
+        except Exception as pkg_err:
+            print(f"Could not load package jinxs: {pkg_err}")
 
         return jsonify({'jinxs': sorted(list(jinx_names)), 'error': None})
     except Exception as e:
@@ -1870,14 +1896,8 @@ def get_jinxs_global():
                 with open(jinx_path, 'r') as f:
                     raw_data = yaml.safe_load(f)
                 
-                inputs = []
-                for inp in raw_data.get("inputs", []):
-                    if isinstance(inp, str):
-                        inputs.append(inp)
-                    elif isinstance(inp, dict):
-                        inputs.append(list(inp.keys())[0])
-                    else:
-                        inputs.append(str(inp))
+                # Preserve full input definitions including defaults
+                inputs = raw_data.get("inputs", [])
                 
                 rel_path = os.path.relpath(jinx_path, global_jinx_directory)
                 path_without_ext = rel_path[:-5]
@@ -1912,14 +1932,8 @@ def get_jinxs_project():
                 with open(jinx_path, 'r') as f:
                     raw_data = yaml.safe_load(f)
                 
-                inputs = []
-                for inp in raw_data.get("inputs", []):
-                    if isinstance(inp, str):
-                        inputs.append(inp)
-                    elif isinstance(inp, dict):
-                        inputs.append(list(inp.keys())[0])
-                    else:
-                        inputs.append(str(inp))
+                # Preserve full input definitions including defaults
+                inputs = raw_data.get("inputs", [])
                 
                 rel_path = os.path.relpath(jinx_path, project_dir)
                 path_without_ext = rel_path[:-5]
@@ -2354,39 +2368,97 @@ def init_project_team():
 
 @app.route("/api/npcsh/check", methods=["GET"])
 def check_npcsh_folder():
-    """Check if ~/.npcsh folder exists and has a valid npc_team."""
+    """Check if npcsh has been initialized by looking for actual npc_team content."""
     try:
         npcsh_path = os.path.expanduser("~/.npcsh")
         npc_team_path = os.path.join(npcsh_path, "npc_team")
-
-        exists = os.path.exists(npcsh_path)
-        has_npc_team = os.path.exists(npc_team_path)
-        has_forenpc = os.path.exists(os.path.join(npc_team_path, "forenpc.npc")) if has_npc_team else False
-
+        # Check if npc_team exists and has .npc files (actual initialization)
+        initialized = os.path.isdir(npc_team_path) and any(
+            f.endswith('.npc') for f in os.listdir(npc_team_path)
+        ) if os.path.exists(npc_team_path) else False
         return jsonify({
-            "exists": exists,
-            "has_npc_team": has_npc_team,
-            "has_forenpc": has_forenpc,
+            "initialized": initialized,
             "path": npcsh_path,
             "error": None
         })
     except Exception as e:
-        print(f"Error checking npcsh folder: {e}")
+        print(f"Error checking npcsh: {e}")
         return jsonify({"error": str(e)}), 500
 
+@app.route("/api/npcsh/package-contents", methods=["GET"])
+def get_package_contents():
+    """Get NPCs and jinxs available in the npcsh package for installation."""
+    try:
+        from npcsh._state import get_package_dir
+        package_dir = get_package_dir()
+        package_npc_team_dir = os.path.join(package_dir, "npc_team")
+
+        npcs = []
+        jinxs = []
+
+        if os.path.exists(package_npc_team_dir):
+            # Get NPCs
+            for f in os.listdir(package_npc_team_dir):
+                if f.endswith('.npc'):
+                    npc_path = os.path.join(package_npc_team_dir, f)
+                    try:
+                        with open(npc_path, 'r') as file:
+                            npc_data = yaml.safe_load(file) or {}
+                        npcs.append({
+                            "name": npc_data.get("name", f[:-4]),
+                            "primary_directive": npc_data.get("primary_directive", ""),
+                            "model": npc_data.get("model", ""),
+                            "provider": npc_data.get("provider", ""),
+                        })
+                    except Exception as e:
+                        print(f"Error reading NPC {f}: {e}")
+
+            # Get jinxs recursively
+            jinxs_dir = os.path.join(package_npc_team_dir, "jinxs")
+            if os.path.exists(jinxs_dir):
+                for root, dirs, files in os.walk(jinxs_dir):
+                    for f in files:
+                        if f.endswith('.jinx'):
+                            jinx_path = os.path.join(root, f)
+                            rel_path = os.path.relpath(jinx_path, jinxs_dir)
+                            try:
+                                with open(jinx_path, 'r') as file:
+                                    jinx_data = yaml.safe_load(file) or {}
+                                jinxs.append({
+                                    "name": f[:-5],
+                                    "path": rel_path[:-5],
+                                    "description": jinx_data.get("description", ""),
+                                })
+                            except Exception as e:
+                                print(f"Error reading jinx {f}: {e}")
+
+        return jsonify({
+            "npcs": npcs,
+            "jinxs": jinxs,
+            "package_dir": package_dir,
+            "error": None
+        })
+    except Exception as e:
+        print(f"Error getting package contents: {e}")
+        import traceback
+        traceback.print_exc()
+        return jsonify({"error": str(e), "npcs": [], "jinxs": []}), 500
+
+
 @app.route("/api/npcsh/init", methods=["POST"])
 def init_npcsh_folder():
-    """Initialize the ~/.npcsh folder with a default npc_team."""
+    """Initialize npcsh with config and default npc_team."""
     try:
-        npcsh_path = os.path.expanduser("~/.npcsh")
-        result = initialize_npc_project(directory=npcsh_path)
+        db_path = os.path.expanduser(NPCSH_DB_PATH)
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+        initialize_base_npcs_if_needed(db_path)
         return jsonify({
-            "message": result,
-            "path": npcsh_path,
+            "message": "npcsh initialized",
+            "path": os.path.expanduser("~/.npcsh"),
             "error": None
         })
     except Exception as e:
-        print(f"Error initializing npcsh folder: {e}")
+        print(f"Error initializing npcsh: {e}")
         return jsonify({"error": str(e)}), 500
 
 @app.route("/api/context/websites", methods=["GET"])
@@ -3417,7 +3489,13 @@ def stream():
     npc_name = data.get("npc", None)
     npc_source = data.get("npcSource", "global")
     current_path = data.get("currentPath")
-    is_resend = data.get("isResend", False)  # ADD THIS LINE
+    is_resend = data.get("isResend", False)
+    parent_message_id = data.get("parentMessageId", None)
+    # Accept frontend-generated message IDs to maintain parent-child relationships after reload
+    frontend_user_message_id = data.get("userMessageId", None)
+    frontend_assistant_message_id = data.get("assistantMessageId", None)
+    # For sub-branches: the parent of the user message (points to an assistant message)
+    user_parent_message_id = data.get("userParentMessageId", None)
 
     if current_path:
         loaded_vars = load_project_env(current_path)
@@ -3513,55 +3591,63 @@ def stream():
 
 
     attachments = data.get("attachments", [])
+    print(f"[DEBUG] Received attachments: {attachments}")
     command_history = CommandHistory(app.config.get('DB_PATH'))
-    images = []     
+    images = []
     attachments_for_db = []
     attachment_paths_for_llm = []
 
-    message_id = generate_message_id()
+    # Use frontend-provided ID if available, otherwise generate new one
+    message_id = frontend_user_message_id if frontend_user_message_id else generate_message_id()
     if attachments:
-        attachment_dir = os.path.expanduser(f"~/.npcsh/attachments/{conversation_id+message_id}/")
-        os.makedirs(attachment_dir, exist_ok=True)
+        print(f"[DEBUG] Processing {len(attachments)} attachments")
 
         for attachment in attachments:
             try:
                 file_name = attachment["name"]
-                
                 extension = file_name.split(".")[-1].upper() if "." in file_name else ""
                 extension_mapped = extension_map.get(extension, "others")
-                
-                save_path = os.path.join(attachment_dir, file_name)
 
-                if "data" in attachment and attachment["data"]:
-                    decoded_data = base64.b64decode(attachment["data"])
-                    with open(save_path, "wb") as f:
-                        f.write(decoded_data)
-                
-                elif "path" in attachment and attachment["path"]:
-                    shutil.copy(attachment["path"], save_path)
-                
-                else:
+                file_path = None
+                file_content_bytes = None
+
+                # Use original path directly if available
+                if "path" in attachment and attachment["path"]:
+                    file_path = attachment["path"]
+                    if os.path.exists(file_path):
+                        with open(file_path, "rb") as f:
+                            file_content_bytes = f.read()
+
+                # Fall back to base64 data if no path
+                elif "data" in attachment and attachment["data"]:
+                    file_content_bytes = base64.b64decode(attachment["data"])
+                    # Save to temp file for LLM processing
+                    import tempfile
+                    temp_dir = tempfile.mkdtemp()
+                    file_path = os.path.join(temp_dir, file_name)
+                    with open(file_path, "wb") as f:
+                        f.write(file_content_bytes)
+
+                if not file_path:
                     continue
 
-                attachment_paths_for_llm.append(save_path)
+                attachment_paths_for_llm.append(file_path)
 
                 if extension_mapped == "images":
-                    images.append(save_path)
-
-                with open(save_path, "rb") as f:
-                    file_content_bytes = f.read()
+                    images.append(file_path)
 
                 attachments_for_db.append({
                     "name": file_name,
-                    "path": save_path,
+                    "path": file_path,
                     "type": extension_mapped,
                     "data": file_content_bytes,
-                    "size": os.path.getsize(save_path)
+                    "size": len(file_content_bytes) if file_content_bytes else 0
                 })
 
             except Exception as e:
                 print(f"Error processing attachment {attachment.get('name', 'N/A')}: {e}")
                 traceback.print_exc()
+    print(f"[DEBUG] After processing - images: {images}, attachment_paths_for_llm: {attachment_paths_for_llm}")
     messages = fetch_messages_for_conversation(conversation_id)
     if len(messages) == 0 and npc_object is not None:
         messages = [{'role': 'system', 
@@ -3603,16 +3689,17 @@ def stream():
             api_url = None
 
     if exe_mode == 'chat':
+        print(f"[DEBUG] Calling get_llm_response with images={images}, attachments={attachment_paths_for_llm}")
         stream_response = get_llm_response(
-            commandstr, 
-            messages=messages, 
-            images=images, 
+            commandstr,
+            messages=messages,
+            images=images,
             model=model,
-            provider=provider, 
-            npc=npc_object, 
+            provider=provider,
+            npc=npc_object,
             api_url = api_url,
             team=team_object,
-            stream=True, 
+            stream=True,
             attachments=attachment_paths_for_llm,
             auto_process_tool_calls=True,
             **tool_args
@@ -3924,25 +4011,27 @@ def stream():
                 user_message_filled += txt
     
     # Only save user message if it's NOT a resend
-    if not is_resend:  # ADD THIS CONDITION
+    if not is_resend:
         save_conversation_message(
-            command_history, 
-            conversation_id, 
-            "user", 
-            user_message_filled if len(user_message_filled) > 0 else commandstr, 
-            wd=current_path, 
-            model=model, 
-            provider=provider, 
+            command_history,
+            conversation_id,
+            "user",
+            user_message_filled if len(user_message_filled) > 0 else commandstr,
+            wd=current_path,
+            model=model,
+            provider=provider,
             npc=npc_name,
-            team=team, 
-            attachments=attachments_for_db, 
+            team=team,
+            attachments=attachments_for_db,
             message_id=message_id,
+            parent_message_id=user_parent_message_id,  # For sub-branches: points to assistant message
         )
 
 
 
 
-    message_id = generate_message_id()
+    # Use frontend-provided assistant message ID if available
+    message_id = frontend_assistant_message_id if frontend_assistant_message_id else generate_message_id()
 
     def event_stream(current_stream_id):
         complete_response = []
@@ -4209,6 +4298,7 @@ def stream():
                 reasoning_content=''.join(complete_reasoning) if complete_reasoning else None,
                 tool_calls=accumulated_tool_calls if accumulated_tool_calls else None,
                 tool_results=tool_results_for_db if tool_results_for_db else None,
+                parent_message_id=parent_message_id,
             )
 
             # Start background tasks for memory extraction and context compression
@@ -4388,6 +4478,7 @@ def get_conversation_messages(conversation_id):
                         ch.reasoning_content,
                         ch.tool_calls,
                         ch.tool_results,
+                        ch.parent_message_id,
                         GROUP_CONCAT(ma.id) as attachment_ids,
                         ROW_NUMBER() OVER (
                             PARTITION BY ch.role, strftime('%s', ch.timestamp)
@@ -4431,9 +4522,10 @@ def get_conversation_messages(conversation_id):
                             "reasoningContent": msg[11] if len(msg) > 11 else None,
                             "toolCalls": parse_json_field(msg[12]) if len(msg) > 12 else None,
                             "toolResults": parse_json_field(msg[13]) if len(msg) > 13 else None,
+                            "parentMessageId": msg[14] if len(msg) > 14 else None,
                             "attachments": (
                                 get_message_attachments(msg[1])
-                                if len(msg) > 1 and msg[14]  # attachment_ids is at index 14
+                                if len(msg) > 1 and msg[15]  # attachment_ids is now at index 15
                                 else []
                             ),
                         }
@@ -4448,6 +4540,157 @@ def get_conversation_messages(conversation_id):
         return jsonify({"error": str(e), "messages": []}), 500
 
 
+# ==================== CONVERSATION BRANCHES ====================
+
+@app.route("/api/conversation/<conversation_id>/branches", methods=["GET"])
+def get_conversation_branches(conversation_id):
+    """Get all branches for a conversation."""
+    try:
+        engine = get_db_connection()
+        with engine.connect() as conn:
+            query = text("""
+                SELECT id, name, parent_branch_id, branch_from_message_id, created_at, metadata
+                FROM conversation_branches
+                WHERE conversation_id = :conversation_id
+                ORDER BY created_at ASC
+            """)
+            result = conn.execute(query, {"conversation_id": conversation_id})
+            branches = result.fetchall()
+
+            return jsonify({
+                "branches": [
+                    {
+                        "id": b[0],
+                        "name": b[1],
+                        "parentBranchId": b[2],
+                        "branchFromMessageId": b[3],
+                        "createdAt": b[4],
+                        "metadata": json.loads(b[5]) if b[5] else None
+                    }
+                    for b in branches
+                ],
+                "error": None
+            })
+    except Exception as e:
+        print(f"Error getting branches: {e}")
+        return jsonify({"branches": [], "error": str(e)}), 500
+
+
+@app.route("/api/conversation/<conversation_id>/branches", methods=["POST"])
+def create_conversation_branch(conversation_id):
+    """Create a new branch for a conversation."""
+    try:
+        data = request.get_json()
+        branch_id = data.get("id") or generate_message_id()
+        name = data.get("name", f"Branch {branch_id[:8]}")
+        parent_branch_id = data.get("parentBranchId", "main")
+        branch_from_message_id = data.get("branchFromMessageId")
+        created_at = data.get("createdAt") or datetime.now().isoformat()
+        metadata = json.dumps(data.get("metadata")) if data.get("metadata") else None
+
+        engine = get_db_connection()
+        with engine.connect() as conn:
+            query = text("""
+                INSERT INTO conversation_branches
+                (id, conversation_id, name, parent_branch_id, branch_from_message_id, created_at, metadata)
+                VALUES (:id, :conversation_id, :name, :parent_branch_id, :branch_from_message_id, :created_at, :metadata)
+            """)
+            conn.execute(query, {
+                "id": branch_id,
+                "conversation_id": conversation_id,
+                "name": name,
+                "parent_branch_id": parent_branch_id,
+                "branch_from_message_id": branch_from_message_id,
+                "created_at": created_at,
+                "metadata": metadata
+            })
+            conn.commit()
+
+        return jsonify({"success": True, "branchId": branch_id})
+    except Exception as e:
+        print(f"Error creating branch: {e}")
+        return jsonify({"success": False, "error": str(e)}), 500
+
+
+@app.route("/api/conversation/<conversation_id>/branches/<branch_id>", methods=["DELETE"])
+def delete_conversation_branch(conversation_id, branch_id):
+    """Delete a branch."""
+    try:
+        engine = get_db_connection()
+        with engine.connect() as conn:
+            # Delete branch metadata
+            query = text("DELETE FROM conversation_branches WHERE id = :branch_id AND conversation_id = :conversation_id")
+            conn.execute(query, {"branch_id": branch_id, "conversation_id": conversation_id})
+
+            # Optionally delete messages on this branch (or leave them orphaned)
+            # For now, we leave them - they just won't be displayed
+            conn.commit()
+
+        return jsonify({"success": True})
+    except Exception as e:
+        print(f"Error deleting branch: {e}")
+        return jsonify({"success": False, "error": str(e)}), 500
+
+
+@app.route("/api/conversation/<conversation_id>/messages/branch/<branch_id>", methods=["GET"])
+def get_branch_messages(conversation_id, branch_id):
+    """Get messages for a specific branch."""
+    try:
+        engine = get_db_connection()
+        with engine.connect() as conn:
+            # For 'main' branch, get messages with NULL or 'main' branch_id
+            if branch_id == 'main':
+                query = text("""
+                    SELECT message_id, timestamp, role, content, model, provider, npc, reasoning_content, tool_calls, tool_results
+                    FROM conversation_history
+                    WHERE conversation_id = :conversation_id
+                    AND (branch_id IS NULL OR branch_id = 'main')
+                    ORDER BY timestamp ASC, id ASC
+                """)
+            else:
+                query = text("""
+                    SELECT message_id, timestamp, role, content, model, provider, npc, reasoning_content, tool_calls, tool_results
+                    FROM conversation_history
+                    WHERE conversation_id = :conversation_id
+                    AND branch_id = :branch_id
+                    ORDER BY timestamp ASC, id ASC
+                """)
+
+            result = conn.execute(query, {"conversation_id": conversation_id, "branch_id": branch_id})
+            messages = result.fetchall()
+
+            def parse_json_field(value):
+                if not value:
+                    return None
+                try:
+                    return json.loads(value)
+                except:
+                    return None
+
+            return jsonify({
+                "messages": [
+                    {
+                        "message_id": m[0],
+                        "timestamp": m[1],
+                        "role": m[2],
+                        "content": m[3],
+                        "model": m[4],
+                        "provider": m[5],
+                        "npc": m[6],
+                        "reasoningContent": m[7],
+                        "toolCalls": parse_json_field(m[8]),
+                        "toolResults": parse_json_field(m[9])
+                    }
+                    for m in messages
+                ],
+                "error": None
+            })
+    except Exception as e:
+        print(f"Error getting branch messages: {e}")
+        return jsonify({"messages": [], "error": str(e)}), 500
+
+
+# ==================== END CONVERSATION BRANCHES ====================
 
 @app.after_request
 def after_request(response):
@@ -4940,6 +5183,140 @@ def download_hf_model():
         return jsonify({'error': str(e)}), 500
 
 
+@app.route('/api/models/hf/search', methods=['GET'])
+def search_hf_models():
+    """Search HuggingFace for GGUF models."""
+    query = request.args.get('q', '')
+    limit = int(request.args.get('limit', 20))
+
+    if not query:
+        return jsonify({'models': [], 'error': 'No search query provided'})
+
+    try:
+        from huggingface_hub import HfApi
+
+        api = HfApi()
+        # Search for models with GGUF in name or tags
+        models = api.list_models(
+            search=query,
+            filter="gguf",
+            limit=limit,
+            sort="downloads",
+            direction=-1
+        )
+
+        results = []
+        for model in models:
+            results.append({
+                'id': model.id,
+                'author': model.author,
+                'downloads': model.downloads,
+                'likes': model.likes,
+                'tags': model.tags[:10] if model.tags else [],
+                'last_modified': model.last_modified.isoformat() if model.last_modified else None,
+            })
+
+        return jsonify({'models': results, 'error': None})
+    except ImportError:
+        return jsonify({'error': 'huggingface_hub not installed. Run: pip install huggingface_hub'}), 500
+    except Exception as e:
+        print(f"Error searching HF models: {e}")
+        return jsonify({'error': str(e)}), 500
+
+
+@app.route('/api/models/hf/files', methods=['GET'])
+def list_hf_model_files():
+    """List GGUF files in a HuggingFace repository."""
+    repo_id = request.args.get('repo_id', '')
+
+    if not repo_id:
+        return jsonify({'files': [], 'error': 'No repo_id provided'})
+
+    try:
+        from huggingface_hub import list_repo_files, repo_info
+
+        # Get repo info
+        info = repo_info(repo_id)
+
+        # List all files
+        all_files = list_repo_files(repo_id)
+
+        # Filter for GGUF files and get their sizes
+        gguf_files = []
+        for f in all_files:
+            if f.endswith('.gguf'):
+                # Try to get file size from siblings
+                size = None
+                for sibling in info.siblings or []:
+                    if sibling.rfilename == f:
+                        size = sibling.size
+                        break
+
+                # Parse quantization from filename
+                quant = 'unknown'
+                for q in ['Q2_K', 'Q3_K_S', 'Q3_K_M', 'Q3_K_L', 'Q4_0', 'Q4_1', 'Q4_K_S', 'Q4_K_M', 'Q5_0', 'Q5_1', 'Q5_K_S', 'Q5_K_M', 'Q6_K', 'Q8_0', 'F16', 'F32', 'IQ1', 'IQ2', 'IQ3', 'IQ4']:
+                    if q.lower() in f.lower() or q in f:
+                        quant = q
+                        break
+
+                gguf_files.append({
+                    'filename': f,
+                    'size': size,
+                    'size_gb': round(size / (1024**3), 2) if size else None,
+                    'quantization': quant,
+                })
+
+        # Sort by quantization quality (Q4_K_M is usually best balance)
+        quant_order = {'Q4_K_M': 0, 'Q4_K_S': 1, 'Q5_K_M': 2, 'Q5_K_S': 3, 'Q3_K_M': 4, 'Q6_K': 5, 'Q8_0': 6}
+        gguf_files.sort(key=lambda x: quant_order.get(x['quantization'], 99))
+
+        return jsonify({
+            'repo_id': repo_id,
+            'files': gguf_files,
+            'total_files': len(all_files),
+            'gguf_count': len(gguf_files),
+            'error': None
+        })
+    except ImportError:
+        return jsonify({'error': 'huggingface_hub not installed. Run: pip install huggingface_hub'}), 500
+    except Exception as e:
+        print(f"Error listing HF files: {e}")
+        return jsonify({'error': str(e)}), 500
+
+
+@app.route('/api/models/hf/download_file', methods=['POST'])
+def download_hf_file():
+    """Download a specific file from a HuggingFace repository."""
+    data = request.json
+    repo_id = data.get('repo_id', '')
+    filename = data.get('filename', '')
+    target_dir = data.get('target_dir', '~/.npcsh/models/gguf')
+
+    if not repo_id or not filename:
+        return jsonify({'error': 'repo_id and filename are required'}), 400
+
+    target_dir = os.path.expanduser(target_dir)
+    os.makedirs(target_dir, exist_ok=True)
+
+    try:
+        from huggingface_hub import hf_hub_download
+
+        print(f"Downloading {filename} from {repo_id} to {target_dir}")
+        path = hf_hub_download(
+            repo_id=repo_id,
+            filename=filename,
+            local_dir=target_dir,
+            local_dir_use_symlinks=False
+        )
+
+        return jsonify({'path': path, 'error': None})
+    except ImportError:
+        return jsonify({'error': 'huggingface_hub not installed. Run: pip install huggingface_hub'}), 500
+    except Exception as e:
+        print(f"Error downloading HF file: {e}")
+        return jsonify({'error': str(e)}), 500
+
+
 # ============== Local Model Provider Status ==============
 @app.route('/api/models/local/scan', methods=['GET'])
 def scan_local_models():
@@ -5003,6 +5380,213 @@ def get_local_model_status():
     return jsonify({'status': 'unknown', 'running': False, 'error': f'Unknown provider: {provider}'})
 
 
+# ============== Audio / Voice ==============
+@app.route('/api/audio/tts', methods=['POST'])
+def text_to_speech_endpoint():
+    """Convert text to speech and return audio file."""
+    try:
+        import base64
+        from npcpy.gen.audio_gen import (
+            text_to_speech, get_available_engines,
+            pcm16_to_wav, KOKORO_VOICES
+        )
+
+        data = request.json or {}
+        text = data.get('text', '')
+        engine = data.get('engine', 'kokoro')  # kokoro, elevenlabs, openai, gemini, gtts
+        voice = data.get('voice', 'af_heart')
+
+        if not text:
+            return jsonify({'success': False, 'error': 'No text provided'}), 400
+
+        # Check engine availability
+        engines = get_available_engines()
+        if engine not in engines:
+            return jsonify({'success': False, 'error': f'Unknown engine: {engine}'}), 400
+
+        if not engines[engine]['available']:
+            # Try fallback to kokoro or gtts
+            if engines.get('kokoro', {}).get('available'):
+                engine = 'kokoro'
+            elif engines.get('gtts', {}).get('available'):
+                engine = 'gtts'
+                voice = 'en'
+            else:
+                return jsonify({
+                    'success': False,
+                    'error': f'{engine} not available. Install: {engines[engine].get("install", engines[engine].get("requires", ""))}'
+                }), 400
+
+        # Generate audio
+        audio_bytes = text_to_speech(text, engine=engine, voice=voice)
+
+        # Determine format
+        if engine in ['kokoro']:
+            audio_format = 'wav'
+        elif engine in ['elevenlabs', 'gtts']:
+            audio_format = 'mp3'
+        elif engine in ['openai', 'gemini']:
+            # These return PCM16, convert to WAV
+            audio_bytes = pcm16_to_wav(audio_bytes, sample_rate=24000)
+            audio_format = 'wav'
+        else:
+            audio_format = 'wav'
+
+        audio_data = base64.b64encode(audio_bytes).decode('utf-8')
+
+        return jsonify({
+            'success': True,
+            'audio': audio_data,
+            'format': audio_format,
+            'engine': engine,
+            'voice': voice
+        })
+
+    except ImportError as e:
+        return jsonify({'success': False, 'error': f'TTS dependency not installed: {e}'}), 500
+    except Exception as e:
+        print(f"TTS error: {e}")
+        traceback.print_exc()
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@app.route('/api/audio/stt', methods=['POST'])
+def speech_to_text_endpoint():
+    """Convert speech audio to text using various STT engines."""
+    try:
+        import tempfile
+        import base64
+        from npcpy.data.audio import speech_to_text, get_available_stt_engines
+
+        data = request.json or {}
+        audio_data = data.get('audio')  # Base64 encoded audio
+        audio_format = data.get('format', 'webm')  # webm, wav, mp3
+        language = data.get('language')  # None for auto-detect
+        engine = data.get('engine', 'whisper')  # whisper, openai, gemini, elevenlabs, groq
+        model_size = data.get('model', 'base')  # For whisper: tiny, base, small, medium, large
+
+        if not audio_data:
+            return jsonify({'success': False, 'error': 'No audio data provided'}), 400
+
+        # Decode base64 audio
+        audio_bytes = base64.b64decode(audio_data)
+
+        # Convert to wav if needed
+        wav_bytes = audio_bytes
+        if audio_format != 'wav':
+            with tempfile.NamedTemporaryFile(suffix=f'.{audio_format}', delete=False) as f:
+                f.write(audio_bytes)
+                temp_path = f.name
+
+            wav_path = temp_path.replace(f'.{audio_format}', '.wav')
+            converted = False
+
+            # Try ffmpeg first
+            try:
+                subprocess.run([
+                    'ffmpeg', '-y', '-i', temp_path,
+                    '-acodec', 'pcm_s16le', '-ac', '1', '-ar', '16000',
+                    wav_path
+                ], check=True, capture_output=True)
+                with open(wav_path, 'rb') as f:
+                    wav_bytes = f.read()
+                converted = True
+                os.unlink(wav_path)
+            except FileNotFoundError:
+                pass
+            except subprocess.CalledProcessError:
+                pass
+
+            # Try pydub as fallback
+            if not converted:
+                try:
+                    from pydub import AudioSegment
+                    audio = AudioSegment.from_file(temp_path, format=audio_format)
+                    audio = audio.set_frame_rate(16000).set_channels(1)
+                    import io
+                    wav_buffer = io.BytesIO()
+                    audio.export(wav_buffer, format='wav')
+                    wav_bytes = wav_buffer.getvalue()
+                    converted = True
+                except ImportError:
+                    pass
+                except Exception as e:
+                    print(f"pydub conversion failed: {e}")
+
+            os.unlink(temp_path)
+
+            if not converted:
+                return jsonify({
+                    'success': False,
+                    'error': 'Audio conversion failed. Install ffmpeg: sudo apt-get install ffmpeg'
+                }), 500
+
+        # Use the unified speech_to_text function
+        result = speech_to_text(
+            wav_bytes,
+            engine=engine,
+            language=language,
+            model_size=model_size
+        )
+
+        return jsonify({
+            'success': True,
+            'text': result.get('text', ''),
+            'language': result.get('language', language or 'en'),
+            'segments': result.get('segments', [])
+        })
+
+    except Exception as e:
+        print(f"STT error: {e}")
+        traceback.print_exc()
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@app.route('/api/audio/stt/engines', methods=['GET'])
+def get_stt_engines_endpoint():
+    """Get available STT engines."""
+    try:
+        from npcpy.data.audio import get_available_stt_engines
+        engines = get_available_stt_engines()
+        return jsonify({'success': True, 'engines': engines})
+    except Exception as e:
+        print(f"Error getting STT engines: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@app.route('/api/audio/voices', methods=['GET'])
+def get_available_voices_endpoint():
+    """Get available TTS voices/engines."""
+    try:
+        from npcpy.gen.audio_gen import get_available_engines, get_available_voices
+
+        engines_info = get_available_engines()
+        result = {}
+
+        for engine_id, info in engines_info.items():
+            voices = get_available_voices(engine_id) if info['available'] else []
+            result[engine_id] = {
+                'name': info['name'],
+                'type': info.get('type', 'unknown'),
+                'available': info['available'],
+                'description': info.get('description', ''),
+                'default': engine_id == 'kokoro',
+                'voices': voices
+            }
+            if not info['available']:
+                if 'install' in info:
+                    result[engine_id]['install'] = info['install']
+                if 'requires' in info:
+                    result[engine_id]['requires'] = info['requires']
+
+        return jsonify({'success': True, 'engines': result})
+
+    except Exception as e:
+        print(f"Error getting voices: {e}")
+        traceback.print_exc()
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
 # ============== Activity Tracking ==============
 @app.route('/api/activity/track', methods=['POST'])
 def track_activity():
@@ -5018,6 +5602,56 @@ def track_activity():
         return jsonify({'success': False, 'error': str(e)}), 500
 
 
+# ============== Studio Action Results ==============
+# Storage for pending action results that agents are waiting for
+_studio_action_results = {}
+
+@app.route('/api/studio/action_result', methods=['POST'])
+def studio_action_result():
+    """
+    Receive action results from the frontend after executing studio.* tool calls.
+    This allows the agent to continue with the result of UI actions.
+    """
+    try:
+        data = request.json or {}
+        stream_id = data.get('streamId')
+        tool_id = data.get('toolId')
+        result = data.get('result', {})
+
+        if not stream_id or not tool_id:
+            return jsonify({'success': False, 'error': 'Missing streamId or toolId'}), 400
+
+        # Store the result keyed by stream_id and tool_id
+        key = f"{stream_id}_{tool_id}"
+        _studio_action_results[key] = result
+
+        print(f"[Studio] Received action result for {key}: {result.get('success', False)}")
+        return jsonify({'success': True, 'stored': key})
+    except Exception as e:
+        print(f"Error storing studio action result: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@app.route('/api/studio/action_result/<stream_id>/<tool_id>', methods=['GET'])
+def get_studio_action_result(stream_id, tool_id):
+    """
+    Retrieve a pending action result for the agent to continue.
+    """
+    try:
+        key = f"{stream_id}_{tool_id}"
+        result = _studio_action_results.get(key)
+
+        if result is None:
+            return jsonify({'success': False, 'pending': True}), 202
+
+        # Remove the result after retrieval (one-time use)
+        del _studio_action_results[key]
+        return jsonify({'success': True, 'result': result})
+    except Exception as e:
+        print(f"Error retrieving studio action result: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
 def start_flask_server(
     port=5337,
     cors_origins=None,
@@ -5071,8 +5705,22 @@ if __name__ == "__main__":
 
     SETTINGS_FILE = Path(os.path.expanduser("~/.npcshrc"))
 
-
-    db_path = os.path.expanduser("~/npcsh_history.db")
+    # Use standard npcsh paths
+    db_path = os.path.expanduser("~/.npcsh/npcsh_history.db")
     user_npc_directory = os.path.expanduser("~/.npcsh/npc_team")
 
-    start_flask_server(db_path=db_path, user_npc_directory=user_npc_directory)
+    # Ensure directories exist
+    os.makedirs(os.path.dirname(db_path), exist_ok=True)
+    os.makedirs(user_npc_directory, exist_ok=True)
+
+    # Initialize base NPCs if needed (creates ~/.npcsh structure)
+    try:
+        initialize_base_npcs_if_needed(db_path)
+        print(f"[SERVE] Base NPCs initialized")
+    except Exception as e:
+        print(f"[SERVE] Warning: Failed to initialize base NPCs: {e}")
+
+    # Get port from environment or use default
+    port = int(os.environ.get('INCOGNIDE_PORT', 5337))
+
+    start_flask_server(db_path=db_path, user_npc_directory=user_npc_directory, port=port)