open-swarm 0.1.1743362777__py3-none-any.whl → 0.1.1743368545__py3-none-any.whl

{open_swarm-0.1.1743362777.dist-info → open_swarm-0.1.1743368545.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-swarm
-Version: 0.1.1743362777
+Version: 0.1.1743368545
 Summary: Open Swarm: Orchestrating AI Agent Swarms with Django
 Project-URL: Homepage, https://github.com/yourusername/open-swarm
 Project-URL: Documentation, https://github.com/yourusername/open-swarm/blob/main/README.md
@@ -40,6 +40,7 @@ Requires-Dist: google-auth-oauthlib>=1.2.1
 Requires-Dist: gunicorn>=21.0.0
 Requires-Dist: httpx<0.26.0,>=0.25.2
 Requires-Dist: jinja2>=3.1.6
+Requires-Dist: jmespath>=1.0.1
 Requires-Dist: openai-agents>=0.0.1
 Requires-Dist: openai<2.0.0,>=1.3.0
 Requires-Dist: platformdirs>=4.0.0
@@ -92,6 +93,11 @@ Description-Content-Type: text/markdown
 
 **Open Swarm** is a Python framework for creating, managing, and deploying autonomous agent swarms. It leverages the `openai-agents` library for core agent functionality and provides a structured way to build complex, multi-agent workflows using **Blueprints**.
 
+Open Swarm can be used in two primary ways:
+
+1.  **As a CLI Utility (`swarm-cli`):** Manage, run, and install blueprints directly on your local machine. Ideal for personal use, testing, and creating standalone agent tools. (Recommended installation: PyPI)
+2.  **As an API Service (`swarm-api`):** Deploy a web server that exposes your blueprints via an OpenAI-compatible REST API. Ideal for integrations, web UIs, and shared access. (Recommended deployment: Docker)
+
 ---
 
 ## Core Concepts
@@ -105,97 +111,160 @@ Description-Content-Type: text/markdown
 
 ---
 
-## Quickstart (Docker - Recommended)
+## Quickstart 1: Using `swarm-cli` Locally (via PyPI)
 
-This is the easiest and recommended way to get started, especially for deploying the API service.
+This is the recommended way to use `swarm-cli` for managing and running blueprints on your local machine.
 
 **Prerequisites:**
-*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
-*   Docker Compose ([Install Docker Compose](https://docs.docker.com/compose/install/))
+*   Python 3.10+
+*   `pip` (Python package installer)
 
 **Steps:**
 
-1.  **Clone the Repository:**
+1.  **Install `open-swarm` from PyPI:**
     ```bash
-    git clone https://github.com/matthewhand/open-swarm.git
-    cd open-swarm
+    pip install open-swarm
     ```
+    *(Using a virtual environment is recommended: `python -m venv .venv && source .venv/bin/activate`)*
 
-2.  **Configure Environment:**
-    *   Copy the example environment file:
+2.  **Initial Configuration (First Run):**
+    *   The first time you run a `swarm-cli` command that requires configuration (like `run` or `config`), it will automatically create a default `swarm_config.json` at `~/.config/swarm/swarm_config.json` if one doesn't exist.
+    *   You **must** set the required environment variables (like `OPENAI_API_KEY`) in your shell for the configuration to work. Create a `.env` file in your working directory or export them:
         ```bash
-        cp .env.example .env
+        export OPENAI_API_KEY="sk-..."
+        # Add other keys as needed (GROQ_API_KEY, etc.)
         ```
-    *   Edit `.env` and add your necessary API keys (e.g., `OPENAI_API_KEY`).
+    *   You can customize the configuration further using `swarm-cli config` commands (see `USERGUIDE.md`).
 
-3.  **Configure Docker Compose Overrides (Optional but Recommended):**
-    *   Copy the override example:
+3.  **Add a Blueprint:**
+    *   Download or create a blueprint file (e.g., `my_blueprint.py`). Example blueprints are available in the [project repository](https://github.com/matthewhand/open-swarm/tree/main/src/swarm/blueprints).
+    *   Add it using `swarm-cli`:
         ```bash
-        cp docker-compose.override.yaml.example docker-compose.override.yaml
-        ```
-    *   Edit `docker-compose.override.yaml` to:
-        *   Mount any local directories containing custom blueprints you want the API server to access (e.g., uncomment and adjust the `./my_custom_blueprints:/app/custom_blueprints:ro` line).
-        *   Make any other necessary adjustments (ports, environment variables, etc.).
+        # Example: Adding a downloaded blueprint file
+        swarm-cli add ./path/to/downloaded/blueprint_echocraft.py
 
-4.  **Start the Service:**
-    ```bash
-    docker compose up -d
-    ```
-    This will build the image (if not already pulled/built) and start the `open-swarm` service, exposing the API on port 8000 (or the port specified in your `.env`/override).
+        # Example: Adding a directory containing a blueprint
+        swarm-cli add ./my_custom_blueprints/agent_smith --name agent_smith
+        ```
 
-5.  **Verify API:**
-    *   Check the available models (blueprints):
+4.  **Run the Blueprint:**
+    *   **Single Instruction:**
         ```bash
-        curl http://localhost:8000/v1/models
+        swarm-cli run echocraft --instruction "Hello from CLI!"
         ```
-    *   Send a chat completion request:
+    *   **Interactive Mode:**
         ```bash
-        curl http://localhost:8000/v1/chat/completions \
-          -H "Content-Type: application/json" \
-          -d '{
-                "model": "echocraft",
-                "messages": [{"role": "user", "content": "Hello Docker!"}]
-              }'
+        swarm-cli run echocraft
+        # Now you can chat with the blueprint interactively
         ```
-        *(Replace `echocraft` with a blueprint name available in your mounted volumes or the base image).*
+
+5.  **(Optional) Install as Command:**
+    ```bash
+    swarm-cli install echocraft
+    # Now run (ensure ~/.local/share/swarm/bin is in your PATH):
+    echocraft --instruction "I am a command now!"
+    ```
 
 ---
 
-## Usage Modes
+## Quickstart 2: Deploying `swarm-api` Service (via Docker)
+
+This section covers deploying the API service using Docker.
+
+### Option A: Docker Compose (Recommended for Flexibility)
+
+This method uses `docker-compose.yaml` and is best if you need to customize volumes, environment variables easily, or manage related services (like Redis).
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+*   Docker Compose ([Install Docker Compose](https://docs.docker.com/compose/install/))
+*   Git
+
+**Steps:**
+
+1.  **Clone the Repository:** (Needed for `docker-compose.yaml` and config files)
+    ```bash
+    git clone https://github.com/matthewhand/open-swarm.git
+    cd open-swarm
+    ```
+
+2.  **Configure Environment:**
+    *   Copy `cp .env.example .env` and edit `.env` with your API keys (e.g., `OPENAI_API_KEY`, `SWARM_API_KEY`).
+
+3.  **Prepare Blueprints & Config:**
+    *   Place blueprints in `./blueprints`.
+    *   Ensure `./swarm_config.json` exists and is configured.
+
+4.  **Configure Overrides (Optional):**
+    *   Copy `cp docker-compose.override.yaml.example docker-compose.override.yaml`.
+    *   Edit the override file to mount additional volumes, change ports, etc.
+
+5.  **Start the Service:**
+    ```bash
+    docker compose up -d
+    ```
+
+6.  **Verify API:** (Default port 8000)
+    *   Models: `curl http://localhost:8000/v1/models`
+    *   Chat: `curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "echocraft", ...}'` (Add `-H "Authorization: Bearer <key>"` if needed).
+
+### Option B: Direct `docker run` (Simpler for Single Container)
+
+This method runs the pre-built image directly from Docker Hub. Good for quick tests or simple deployments without cloning the repo. Customization requires careful use of `-v` (volume) and `-e` (environment) flags.
+
+**Prerequisites:**
+*   Docker ([Install Docker](https://docs.docker.com/engine/install/))
+
+**Steps:**
 
-Open Swarm offers several ways to interact with your blueprints:
+1.  **Prepare Local Files (If Customizing):**
+    *   Create a directory for your blueprints (e.g., `~/my_swarm_blueprints`).
+    *   Create your `swarm_config.json` file locally (e.g., `~/my_swarm_config.json`).
+    *   Create a `.env` file locally (e.g., `~/swarm.env`) with your API keys (`OPENAI_API_KEY`, `SWARM_API_KEY`, etc.).
 
-1.  **Run via `swarm-api` (OpenAI-Compatible REST API):**
-    *   **How:** Start the Django server (`uv run python manage.py runserver` or via Docker as shown above).
-    *   **What:** Exposes blueprints listed in `settings.BLUEPRINT_DIRECTORY` (within the Docker container, this typically includes `/app/blueprints` and any volumes mounted in the override file) via `/v1/models` and `/v1/chat/completions`.
-    *   **Auth:** If `SWARM_API_KEY` is set in `.env`, requests require an `Authorization: Bearer <your_key>` header. Otherwise, access is anonymous.
-    *   **Security:** **Warning:** Running with anonymous access, especially when bound to `0.0.0.0`, can be insecure if blueprints have access to sensitive operations (filesystem, shell commands). **Setting `SWARM_API_KEY` is highly recommended for non-local deployments.**
-    *   **(TODO) Web UI:** A future mode will integrate a simple web chat interface with the API server.
+2.  **Run the Container:**
+    ```bash
+    docker run -d \
+      --name open-swarm-api \
+      -p 8000:8000 \
+      --env-file ~/swarm.env \
+      -v ~/my_swarm_blueprints:/app/blueprints:ro \
+      -v ~/my_swarm_config.json:/app/swarm_config.json:ro \
+      -v open_swarm_db:/app/db.sqlite3 \
+      --restart unless-stopped \
+      mhand79/open-swarm:latest
+    ```
+    *   `-d`: Run detached (in background).
+    *   `--name`: Assign a name to the container.
+    *   `-p 8000:8000`: Map host port 8000 to container port 8000 (adjust if needed).
+    *   `--env-file`: Load environment variables from your local file.
+    *   `-v ...:/app/blueprints:ro`: Mount your local blueprints directory (read-only). **Required** if you want to use custom blueprints.
+    *   `-v ...:/app/swarm_config.json:ro`: Mount your local config file (read-only). **Required** for custom LLM/MCP settings.
+    *   `-v open_swarm_db:/app/db.sqlite3`: Use a named Docker volume for the database to persist data.
+    *   `--restart unless-stopped`: Automatically restart the container unless manually stopped.
+    *   `mhand79/open-swarm:latest`: The image name on Docker Hub.
+
+3.  **Verify API:** (Same as Docker Compose)
+    *   Models: `curl http://localhost:8000/v1/models`
+    *   Chat: `curl http://localhost:8000/v1/chat/completions ...` (Add `-H "Authorization: Bearer <key>"` if needed).
 
-2.  **Run via `swarm-cli run`:**
-    *   **How:** `swarm-cli run <blueprint_name> --instruction "Your single instruction"`
-    *   **What:** Executes a blueprint managed by `swarm-cli` (located in `~/.local/share/swarm/blueprints/`) directly in the terminal. Uses configuration from `~/.config/swarm/swarm_config.json`.
-    *   **Interactive Mode:** If you omit the `--instruction` argument (`swarm-cli run <blueprint_name>`), it will enter an interactive chat mode in the terminal.
-    *   **Use Case:** Good for testing, debugging, interactive sessions, or running specific tasks locally without the API overhead.
+---
 
-3.  **Run via `swarm-cli install`:**
-    *   **How:** `swarm-cli install <blueprint_name>`, then run `<blueprint_name> --instruction "..."`
-    *   **What:** Creates a standalone executable for a managed blueprint using PyInstaller and places it in the user's binary directory (e.g., `~/.local/bin/` or similar, ensure it's in your `PATH`).
-    *   **Use Case:** Convenient for frequently used blueprints that act like regular command-line tools.
+## Usage Modes Summary
 
-4.  **Direct Python Execution:**
-    *   **How:** `uv run python /path/to/your/blueprint_file.py --instruction "..."`
-    *   **What:** Runs a specific blueprint Python file directly. Requires manual handling of configuration loading and dependencies.
-    *   **Use Case:** Primarily for development and testing of a single blueprint file outside the managed environment.
+*   **`swarm-api` (via Docker or `manage.py runserver`):** Exposes blueprints as an OpenAI-compatible REST API. Ideal for integrations. Requires `SWARM_API_KEY` for security in non-local deployments.
+*   **`swarm-cli run` (via PyPI install):** Executes managed blueprints locally, either with a single instruction or in interactive chat mode. Good for testing and local tasks.
+*   **`swarm-cli install` (via PyPI install):** Creates standalone command-line executables from managed blueprints.
+*   **Direct Python Execution (via Git clone):** Running `uv run python <blueprint_file.py>` is mainly for development and testing individual files.
 
 ---
 
 ## Further Documentation
 
-This README provides a high-level overview and quickstart. For more detailed information, please refer to:
+This README provides a high-level overview and quickstart guides. For more detailed information, please refer to:
 
-*   **User Guide (`USERGUIDE.md`):** Detailed instructions on using `swarm-cli` commands for managing blueprints and configuration.
-*   **Development Guide (`DEVELOPMENT.md`):** Information for contributors and developers, including architecture details, testing strategies, project layout, and advanced topics like XDG paths and blueprint creation.
+*   **User Guide (`USERGUIDE.md`):** Detailed instructions on using `swarm-cli` commands for managing blueprints and configuration locally.
+*   **Development Guide (`DEVELOPMENT.md`):** Information for contributors and developers, including architecture details, testing strategies, project layout, API details, and advanced topics.
 *   **Example Blueprints (`src/swarm/blueprints/README.md`):** A list and description of the example blueprints included with the framework, showcasing various features and integration patterns.
 
 ---

{open_swarm-0.1.1743362777.dist-info → open_swarm-0.1.1743368545.dist-info}/RECORD

@@ -1,6 +1,6 @@
 swarm/__init__.py,sha256=aT-yyX84tiZhihp0RAXYTADCo9dhOnmolQVfn4_NQa8,46
 swarm/apps.py,sha256=up4C3m2JeyXeUcH-wYeReCuiOBVJ6404w9OfaRChLwM,2568
-swarm/auth.py,sha256=M_29ksMrTgs5u-iyFTkIqZNOpRoYzkcm3drIokQYS9A,2654
+swarm/auth.py,sha256=8JIk1VbBvFFwOijEJAsrx6si802ZSMGnErXvmo0izUg,5935
 swarm/consumers.py,sha256=wESLamkhbi4SEZt9k3yx6eU9ufOIZMCAL-OAXjJBGXE,5056
 swarm/messages.py,sha256=CwADrjlj-uVmm-so1xIZvN1UkEWdzSn_hu7slfhuS8w,6549
 swarm/models.py,sha256=Ix0WEYYqza2lbOEBNesikRCs3XGUPWmqQyMWzZYUaxM,1494
@@ -247,14 +247,14 @@ swarm/utils/message_utils.py,sha256=oNTD7pfmnnu_Br24pR2VEX9afIZwFLwg2HJBLXs1blY,
 swarm/utils/redact.py,sha256=L2lo927S575Ay7Jz6pUlK47Sxxzpd9IMybnDm6-WlC8,2955
 swarm/views/__init__.py,sha256=AcLk0R7Y69FhIVgJK2hZs8M_gCR-h_5iqUywz89yuHM,1223
 swarm/views/api_views.py,sha256=BbDEgI6Ftg-c-mMkE9DvRGZHIZ-WAZSfwqAB7j98WxM,1937
-swarm/views/chat_views.py,sha256=ajTVOyQpMMjr3yK7m8chX8SszsHz83uB12mt3eJo3DU,11777
+swarm/views/chat_views.py,sha256=6UUtEJKrM2k_wi9A6AfhbbvMYunjzpY22M6hOIXASjA,15695
 swarm/views/core_views.py,sha256=iGbits6HqVXE13vEkqvOBQHGS7LZb6Gg9Hcs6KjZmmk,5255
 swarm/views/message_views.py,sha256=sDUnXyqKXC8WwIIMAlWf00s2_a2T9c75Na5FvYMJwBM,1596
 swarm/views/model_views.py,sha256=aAbU4AZmrOTaPeKMWtoKK7FPYHdaN3Zbx55JfKzYTRY,2937
 swarm/views/utils.py,sha256=geX3Z5ZDKFYyXYBMilc-4qgOSjhujK3AfRtvbXgFpXk,3643
 swarm/views/web_views.py,sha256=ExQQeJpZ8CkLZQC_pXKOOmdnEy2qR3wEBP4LLp27DPU,7404
-open_swarm-0.1.1743362777.dist-info/METADATA,sha256=q3l34AHcBOzw_80TKYl3NG_RgoJMOOiwwxJ8pEN1PH8,11145
-open_swarm-0.1.1743362777.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-open_swarm-0.1.1743362777.dist-info/entry_points.txt,sha256=LudR3dBqGnglrE1n2zAeWo38Ck0m57sKPW36KfK-pzo,71
-open_swarm-0.1.1743362777.dist-info/licenses/LICENSE,sha256=BU9bwRlnOt_JDIb6OT55Q4leLZx9RArDLTFnlDIrBEI,1062
-open_swarm-0.1.1743362777.dist-info/RECORD,,
+open_swarm-0.1.1743368545.dist-info/METADATA,sha256=jhENgIwI-YqL-g0gFo8loMVMWEt1qSTGlpPFbZW0IVs,13680
+open_swarm-0.1.1743368545.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+open_swarm-0.1.1743368545.dist-info/entry_points.txt,sha256=LudR3dBqGnglrE1n2zAeWo38Ck0m57sKPW36KfK-pzo,71
+open_swarm-0.1.1743368545.dist-info/licenses/LICENSE,sha256=BU9bwRlnOt_JDIb6OT55Q4leLZx9RArDLTFnlDIrBEI,1062
+open_swarm-0.1.1743368545.dist-info/RECORD,,

swarm/auth.py

@@ -1,6 +1,8 @@
 import logging
 import os
 from rest_framework.authentication import BaseAuthentication, SessionAuthentication
+# Import BasePermission for creating custom permissions
+from rest_framework.permissions import BasePermission
 from rest_framework import exceptions
 from django.conf import settings
 from django.utils.translation import gettext_lazy as _
@@ -12,49 +14,108 @@ from django.contrib.auth import get_user_model
 logger = logging.getLogger('swarm.auth')
 User = get_user_model()
 
+# ==============================================================================
+# Authentication Classes (Determine *who* the user is)
+# ==============================================================================
+
 # --- Static Token Authentication ---
 class StaticTokenAuthentication(BaseAuthentication):
     """
-    Authenticates requests based on a static API token passed in a header.
-    Returns (AnonymousUser, token) on success to satisfy DRF's expectations
-    while signaling that a specific user isn't associated.
+    Authenticates requests based on a static API token passed in a header
+    (Authorization: Bearer <token> or X-API-Key: <token>).
+
+    Returns (AnonymousUser, token) on success. This allows permission classes
+    to check request.auth to see if token authentication succeeded, even though
+    no specific user model is associated with the token.
     """
     keyword = 'Bearer'
 
     def authenticate(self, request):
-        logger.debug("[Auth][StaticToken] StaticTokenAuthentication.authenticate called.")
+        """
+        Attempts to authenticate using a static token.
+        """
+        logger.debug("[Auth][StaticToken] Attempting static token authentication.")
+        # Retrieve the expected token from settings.
         expected_token = getattr(settings, 'SWARM_API_KEY', None)
 
+        # If no token is configured in settings, this method cannot authenticate.
         if not expected_token:
-            logger.error("[Auth][StaticToken] SWARM_API_KEY is not set in Django settings. Cannot authenticate.")
-            return None
+            logger.error("[Auth][StaticToken] SWARM_API_KEY is not set in Django settings. Cannot use static token auth.")
+            return None # Indicate authentication method did not run or failed pre-check
 
+        # Extract the provided token from standard Authorization header or custom X-API-Key header.
         provided_token = None
         auth_header = request.META.get('HTTP_AUTHORIZATION', '').split()
         if len(auth_header) == 2 and auth_header[0].lower() == self.keyword.lower():
             provided_token = auth_header[1]
-            logger.debug(f"[Auth][StaticToken] Found token in Authorization header: {provided_token[:6]}...")
+            logger.debug("[Auth][StaticToken] Found token in Authorization header.")
         else:
             provided_token = request.META.get('HTTP_X_API_KEY')
             if provided_token:
-                logger.debug(f"[Auth][StaticToken] Found token in X-API-Key header: {provided_token[:6]}...")
+                logger.debug("[Auth][StaticToken] Found token in X-API-Key header.")
 
+        # If no token was found in either header, authentication fails for this method.
         if not provided_token:
-            logger.debug("[Auth][StaticToken] No token found in headers.")
-            return None
+            logger.debug("[Auth][StaticToken] No token found in relevant headers.")
+            return None # Indicate authentication method did not find credentials
 
-        # Use constant time comparison if possible in future?
+        # Compare the provided token with the expected token.
+        # NOTE: For production, consider using a constant-time comparison function
+        #       to mitigate timing attacks if the token is highly sensitive.
         if provided_token == expected_token:
             logger.info("[Auth][StaticToken] Static token authentication successful.")
-            # *** Return AnonymousUser and the token ***
-            # This sets request.user to AnonymousUser and request.auth to the token.
+            # Return AnonymousUser and the token itself as request.auth.
+            # This signals successful authentication via token without linking to a specific User model.
             return (AnonymousUser(), provided_token)
         else:
-            logger.warning(f"[Auth][StaticToken] Invalid token provided: {provided_token[:6]}...")
+            # Token was provided but did not match. Raise AuthenticationFailed.
+            logger.warning(f"[Auth][StaticToken] Invalid static token provided.")
             raise exceptions.AuthenticationFailed(_("Invalid API Key."))
 
 # --- Custom *Synchronous* Session Authentication ---
 class CustomSessionAuthentication(SessionAuthentication):
-    """ Standard SessionAuthentication """
+    """
+    Standard Django Session Authentication provided by DRF.
+    Relies on Django's session middleware to populate request.user.
+    This class itself is synchronous, but the underlying session loading
+    needs to be handled correctly in async views (e.g., via middleware or wrappers).
+    """
+    # No override needed unless customizing session behavior.
     pass
 
+
+# ==============================================================================
+# Permission Classes (Determine *if* access is allowed)
+# ==============================================================================
+
+class HasValidTokenOrSession(BasePermission):
+    """
+    Allows access if EITHER:
+    1. Static token authentication succeeded (request.auth is not None).
+    2. Session authentication succeeded (request.user is authenticated).
+    """
+    message = 'Authentication credentials were not provided or are invalid (Requires valid API Key or active session).'
+
+    def has_permission(self, request, view):
+        """
+        Checks if the request has valid authentication via token or session.
+        """
+        # Check if static token authentication was successful.
+        # StaticTokenAuthentication returns (AnonymousUser, token), so request.auth will be the token.
+        has_valid_token = getattr(request, 'auth', None) is not None
+        if has_valid_token:
+            logger.debug("[Perm][TokenOrSession] Access granted via static token (request.auth is set).")
+            return True
+
+        # Check if session authentication was successful.
+        # request.user should be populated by SessionAuthentication/AuthMiddleware.
+        user = getattr(request, 'user', None)
+        has_valid_session = user is not None and user.is_authenticated
+        if has_valid_session:
+            logger.debug(f"[Perm][TokenOrSession] Access granted via authenticated session user: {user}")
+            return True
+
+        # If neither condition is met, deny permission.
+        logger.debug("[Perm][TokenOrSession] Access denied: No valid token (request.auth=None) and no authenticated session user.")
+        return False
+

swarm/views/chat_views.py

@@ -1,3 +1,5 @@
+
+# --- Content for src/swarm/views/chat_views.py ---
 import logging
 import json
 import uuid
@@ -12,21 +14,28 @@ from django.utils.decorators import method_decorator
 from django.views.decorators.csrf import csrf_exempt
 from django.contrib.auth.decorators import login_required
 from django.conf import settings
+from django.urls import reverse # Needed for reverse() used in tests
 
 from rest_framework import status
 from rest_framework.views import APIView
 from rest_framework.response import Response
 from rest_framework.permissions import IsAuthenticated, AllowAny
 from rest_framework.exceptions import ValidationError, PermissionDenied, NotFound, APIException, ParseError, NotAuthenticated
+from rest_framework.request import Request # Import DRF Request
 
-from asgiref.sync import sync_to_async, async_to_sync # Import async_to_sync
+# Utility to wrap sync functions for async execution
+from asgiref.sync import sync_to_async
 
 # Assuming serializers are in the same app
 from swarm.serializers import ChatCompletionRequestSerializer
 # Assuming utils are in the same app/directory level
+# Make sure these utils are async-safe or wrapped if they perform sync I/O
 from .utils import get_blueprint_instance, validate_model_access, get_available_blueprints
+# Import custom permission
+from swarm.auth import HasValidTokenOrSession # Keep this import
 
 logger = logging.getLogger(__name__)
+# Specific logger for debug prints, potentially configured differently
 print_logger = logging.getLogger('print_debug')
 
 # ==============================================================================
@@ -34,28 +43,43 @@ print_logger = logging.getLogger('print_debug')
 # ==============================================================================
 
 class HealthCheckView(APIView):
+    """ Simple health check endpoint. """
     permission_classes = [AllowAny]
-    def get(self, request, *args, **kwargs): return Response({"status": "ok"})
+    def get(self, request, *args, **kwargs):
+        """ Returns simple 'ok' status. """
+        return Response({"status": "ok"})
 
 class ChatCompletionsView(APIView):
     """
-    Handles chat completion requests, compatible with OpenAI API.
-    Permissions are now handled by DEFAULT_PERMISSION_CLASSES in settings.py.
+    Handles chat completion requests (/v1/chat/completions), compatible with OpenAI API spec.
+    Supports both streaming and non-streaming responses.
+    Uses asynchronous handling for potentially long-running blueprint operations.
     """
+    # Default serializer class for request validation.
     serializer_class = ChatCompletionRequestSerializer
+    # Default permission classes are likely set in settings.py
+    # permission_classes = [IsAuthenticated] # Example default
+
+    # --- Internal Helper Methods (Unchanged) ---
 
     async def _handle_non_streaming(self, blueprint_instance, messages: List[Dict[str, str]], request_id: str, model_name: str) -> Response:
+        """ Handles non-streaming requests. """
         logger.info(f"[ReqID: {request_id}] Processing non-streaming request for model '{model_name}'.")
         final_response_data = None; start_time = time.time()
         try:
-            # *** FIX: Remove await here. run() returns the async generator directly ***
+            # The blueprint's run method should be an async generator.
             async_generator = blueprint_instance.run(messages)
             async for chunk in async_generator:
-                if isinstance(chunk, dict) and "messages" in chunk: final_response_data = chunk["messages"]; logger.debug(f"[ReqID: {request_id}] Received final data chunk: {final_response_data}"); break
-                else: logger.warning(f"[ReqID: {request_id}] Unexpected chunk format: {chunk}")
+                # Check if the chunk contains the expected final message list.
+                if isinstance(chunk, dict) and "messages" in chunk and isinstance(chunk["messages"], list):
+                    final_response_data = chunk["messages"]
+                    logger.debug(f"[ReqID: {request_id}] Received final data chunk.")
+                    break # Stop after getting the final data
+                else:
+                    logger.warning(f"[ReqID: {request_id}] Unexpected chunk format during non-streaming run: {chunk}")
 
             if not final_response_data or not isinstance(final_response_data, list) or not final_response_data:
-                 logger.error(f"[ReqID: {request_id}] Blueprint '{model_name}' did not return valid final data structure. Got: {final_response_data}")
+                 logger.error(f"[ReqID: {request_id}] Blueprint '{model_name}' did not return a valid final message list. Got: {final_response_data}")
                  raise APIException("Blueprint did not return valid data.", code=status.HTTP_500_INTERNAL_SERVER_ERROR)
 
             if not isinstance(final_response_data[0], dict) or 'role' not in final_response_data[0]:
@@ -69,73 +93,96 @@ class ChatCompletionsView(APIView):
         except Exception as e: logger.error(f"[ReqID: {request_id}] Unexpected error during non-streaming blueprint execution: {e}", exc_info=True); raise APIException(f"Internal server error during generation: {e}", code=status.HTTP_500_INTERNAL_SERVER_ERROR) from e
 
     async def _handle_streaming(self, blueprint_instance, messages: List[Dict[str, str]], request_id: str, model_name: str) -> StreamingHttpResponse:
+        """ Handles streaming requests using SSE. """
         logger.info(f"[ReqID: {request_id}] Processing streaming request for model '{model_name}'.")
         async def event_stream():
             start_time = time.time(); chunk_index = 0
             try:
-                logger.debug(f"[ReqID: {request_id}] Getting async generator from blueprint run...");
-                # *** FIX: Remove await here. run() returns the async generator directly ***
-                async_generator = blueprint_instance.run(messages)
-                logger.debug(f"[ReqID: {request_id}] Got async generator. Starting iteration...")
+                logger.debug(f"[ReqID: {request_id}] Getting async generator from blueprint.run()..."); async_generator = blueprint_instance.run(messages); logger.debug(f"[ReqID: {request_id}] Got async generator. Starting iteration...")
                 async for chunk in async_generator:
                     logger.debug(f"[ReqID: {request_id}] Received stream chunk {chunk_index}: {chunk}")
-                    if not isinstance(chunk, dict) or "messages" not in chunk or not isinstance(chunk["messages"], list) or not chunk["messages"] or not isinstance(chunk["messages"][0], dict):
-                        logger.warning(f"[ReqID: {request_id}] Skipping invalid chunk format: {chunk}"); continue
-                    delta_content = chunk["messages"][0].get("content", "");
-                    delta = {"role": "assistant"}
+                    if not isinstance(chunk, dict) or "messages" not in chunk or not isinstance(chunk["messages"], list) or not chunk["messages"] or not isinstance(chunk["messages"][0], dict): logger.warning(f"[ReqID: {request_id}] Skipping invalid chunk format: {chunk}"); continue
+                    delta_content = chunk["messages"][0].get("content"); delta = {"role": "assistant"}
                     if delta_content is not None: delta["content"] = delta_content
-
                     response_chunk = { "id": f"chatcmpl-{request_id}", "object": "chat.completion.chunk", "created": int(time.time()), "model": model_name, "choices": [{"index": 0, "delta": delta, "logprobs": None, "finish_reason": None}] }
                     logger.debug(f"[ReqID: {request_id}] Sending SSE chunk {chunk_index}"); yield f"data: {json.dumps(response_chunk)}\n\n"; chunk_index += 1; await asyncio.sleep(0.01)
                 logger.debug(f"[ReqID: {request_id}] Finished iterating stream. Sending [DONE]."); yield "data: [DONE]\n\n"; end_time = time.time(); logger.info(f"[ReqID: {request_id}] Streaming request completed in {end_time - start_time:.2f}s.")
-            except APIException as e:
-                 logger.error(f"[ReqID: {request_id}] API error during streaming blueprint execution: {e}", exc_info=True); error_msg = f"API error during stream: {e.detail}"; error_chunk = {"error": {"message": error_msg, "type": "api_error", "code": e.status_code}}
-                 try: yield f"data: {json.dumps(error_chunk)}\n\n"; yield "data: [DONE]\n\n"
-                 except Exception as send_err: logger.error(f"[ReqID: {request_id}] Failed to send error chunk: {send_err}")
-            except Exception as e:
-                 logger.error(f"[ReqID: {request_id}] Unexpected error during streaming blueprint execution: {e}", exc_info=True); error_msg = f"Internal server error during stream: {str(e)}"; error_chunk = {"error": {"message": error_msg, "type": "internal_error"}}
-                 try: yield f"data: {json.dumps(error_chunk)}\n\n"; yield "data: [DONE]\n\n"
-                 except Exception as send_err: logger.error(f"[ReqID: {request_id}] Failed to send error chunk: {send_err}")
+            except APIException as e: logger.error(f"[ReqID: {request_id}] API error during streaming: {e}", exc_info=True); error_msg = f"API error: {e.detail}"; error_chunk = {"error": {"message": error_msg, "type": "api_error", "code": e.status_code}}; yield f"data: {json.dumps(error_chunk)}\n\n"; yield "data: [DONE]\n\n"
+            except Exception as e: logger.error(f"[ReqID: {request_id}] Unexpected error during streaming: {e}", exc_info=True); error_msg = f"Internal server error: {str(e)}"; error_chunk = {"error": {"message": error_msg, "type": "internal_error"}}; yield f"data: {json.dumps(error_chunk)}\n\n"; yield "data: [DONE]\n\n"
         return StreamingHttpResponse(event_stream(), content_type="text/event-stream")
 
+    # --- Restore Custom dispatch method (wrapping perform_authentication) ---
     @method_decorator(csrf_exempt)
     async def dispatch(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponseBase:
-        self.args = args; self.kwargs = kwargs
-        request = self.initialize_request(request, *args, **kwargs)
-        self.request = request; self.headers = self.default_response_headers
+        """
+        Override DRF's dispatch method to specifically wrap the authentication step.
+        """
+        self.args = args
+        self.kwargs = kwargs
+        drf_request: Request = self.initialize_request(request, *args, **kwargs)
+        self.request = drf_request
+        self.headers = self.default_response_headers
+
+        response = None
         try:
-            print_logger.debug(f"User before initial(): {getattr(request, 'user', 'N/A')}, Auth before initial(): {getattr(request, 'auth', 'N/A')}")
-            # Wrap sync initial() call
-            await sync_to_async(self.initial)(request, *args, **kwargs)
-            print_logger.debug(f"User after initial(): {getattr(request, 'user', 'N/A')}, Auth after initial(): {getattr(request, 'auth', 'N/A')}")
-
-            if request.method.lower() in self.http_method_names: handler = getattr(self, request.method.lower(), self.http_method_not_allowed)
-            else: handler = self.http_method_not_allowed
+            # --- Wrap ONLY perform_authentication ---
+            print_logger.debug(f"User before perform_authentication: {getattr(drf_request, 'user', 'N/A')}, Auth: {getattr(drf_request, 'auth', 'N/A')}")
+            # This forces the synchronous DB access within perform_authentication into a thread
+            await sync_to_async(self.perform_authentication)(drf_request)
+            print_logger.debug(f"User after perform_authentication: {getattr(drf_request, 'user', 'N/A')}, Auth: {getattr(drf_request, 'auth', 'N/A')}")
+            # --- End wrapping ---
+
+            # Run permission and throttle checks synchronously after auth.
+            # These checks operate on the now-populated request.user/auth attributes.
+            self.check_permissions(drf_request)
+            print_logger.debug("Permissions check passed.")
+            self.check_throttles(drf_request)
+            print_logger.debug("Throttles check passed.")
+
+            # Find and execute the handler (e.g., post).
+            if drf_request.method.lower() in self.http_method_names:
+                handler = getattr(self, drf_request.method.lower(), self.http_method_not_allowed)
+            else:
+                handler = self.http_method_not_allowed
 
+            # IMPORTANT: Await the handler if it's async (like self.post)
             if asyncio.iscoroutinefunction(handler):
-                response = await handler(request, *args, **kwargs)
+                response = await handler(drf_request, *args, **kwargs)
             else:
-                 response = await sync_to_async(handler)(request, *args, **kwargs)
-        except Exception as exc: response = self.handle_exception(exc)
-        self.response = self.finalize_response(request, response, *args, **kwargs)
+                # Wrap sync handlers if any exist (like GET, OPTIONS).
+                response = await sync_to_async(handler)(drf_request, *args, **kwargs)
+
+        except Exception as exc:
+            # Let DRF handle exceptions to generate appropriate responses
+            response = self.handle_exception(exc)
+
+        # Finalize response should now receive a valid Response/StreamingHttpResponse
+        self.response = self.finalize_response(drf_request, response, *args, **kwargs)
         return self.response
 
-    async def post(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponseBase:
-        request_id = str(uuid.uuid4()); logger.info(f"[ReqID: {request_id}] Received chat completion request.")
-        print_logger.debug(f"[ReqID: {request_id}] User at start of post: {getattr(request, 'user', 'N/A')}, Auth: {getattr(request, 'auth', 'N/A')}")
-        try:
-            request_data = request.data
-        except ParseError as e: logger.error(f"[ReqID: {request_id}] Invalid JSON body: {e.detail}"); raise e
+    # --- POST Handler (Keep sync_to_async wrappers here too) ---
+    async def post(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponseBase:
+        """
+        Handles POST requests for chat completions. Assumes dispatch has handled auth/perms.
+        """
+        request_id = str(uuid.uuid4())
+        logger.info(f"[ReqID: {request_id}] Processing POST request.")
+        print_logger.debug(f"[ReqID: {request_id}] User in post: {getattr(request, 'user', 'N/A')}, Auth: {getattr(request, 'auth', 'N/A')}")
+
+        # --- Request Body Parsing & Validation ---
+        try: request_data = request.data
+        except ParseError as e: logger.error(f"[ReqID: {request_id}] Invalid request body format: {e.detail}"); raise e
         except json.JSONDecodeError as e: logger.error(f"[ReqID: {request_id}] JSON Decode Error: {e}"); raise ParseError(f"Invalid JSON body: {e}")
 
+        # --- Serialization and Validation ---
         serializer = self.serializer_class(data=request_data)
         try:
-            print_logger.debug(f"[ReqID: {request_id}] Attempting serializer.is_valid(). Data: {request_data}")
-            # Wrap sync is_valid call
+            print_logger.debug(f"[ReqID: {request_id}] Validating request data: {request_data}")
+            # Wrap sync is_valid call as it *might* do DB lookups
             await sync_to_async(serializer.is_valid)(raise_exception=True)
-            print_logger.debug(f"[ReqID: {request_id}] Serializer is_valid() PASSED.")
-        except ValidationError as e: print_logger.error(f"[ReqID: {request_id}] Serializer validation FAILED: {e.detail}"); raise e
-        except Exception as e: print_logger.error(f"[ReqID: {request_id}] UNEXPECTED error during serializer validation: {e}", exc_info=True); raise APIException(f"Internal error during request validation: {e}", code=status.HTTP_500_INTERNAL_SERVER_ERROR) from e
+            print_logger.debug(f"[ReqID: {request_id}] Request data validation successful.")
+        except ValidationError as e: print_logger.error(f"[ReqID: {request_id}] Request data validation FAILED: {e.detail}"); raise e
+        except Exception as e: print_logger.error(f"[ReqID: {request_id}] Unexpected error during serializer validation: {e}", exc_info=True); raise APIException(f"Internal error during request validation: {e}", code=status.HTTP_500_INTERNAL_SERVER_ERROR) from e
 
         validated_data = serializer.validated_data
         model_name = validated_data['model']
@@ -143,20 +190,54 @@ class ChatCompletionsView(APIView):
         stream = validated_data.get('stream', False)
         blueprint_params = validated_data.get('params', None)
 
-        print_logger.debug(f"[ReqID: {request_id}] Validation passed. Checking model access for user {request.user} and model {model_name}")
-        # Wrap sync validate_model_access
-        access_granted = await sync_to_async(validate_model_access)(request.user, model_name)
+        # --- Model Access Validation ---
+        # This function likely performs sync DB lookups, so wrap it.
+        print_logger.debug(f"[ReqID: {request_id}] Checking model access for user '{request.user}' and model '{model_name}'")
+        try:
+            access_granted = await sync_to_async(validate_model_access)(request.user, model_name)
+        except Exception as e:
+            logger.error(f"[ReqID: {request_id}] Error during model access validation for model '{model_name}': {e}", exc_info=True)
+            raise APIException("Error checking model permissions.", code=status.HTTP_500_INTERNAL_SERVER_ERROR) from e
+
         if not access_granted:
-             logger.warning(f"[ReqID: {request_id}] User {request.user} denied access to model '{model_name}'.")
+             logger.warning(f"[ReqID: {request_id}] User '{request.user}' denied access to model '{model_name}'.")
              raise PermissionDenied(f"You do not have permission to access the model '{model_name}'.")
+        print_logger.debug(f"[ReqID: {request_id}] Model access granted.")
 
-        print_logger.debug(f"[ReqID: {request_id}] Access granted. Getting blueprint instance for {model_name}")
-        blueprint_instance = await get_blueprint_instance(model_name, params=blueprint_params)
+        # --- Get Blueprint Instance ---
+        # This function should ideally be async or sync-safe.
+        print_logger.debug(f"[ReqID: {request_id}] Getting blueprint instance for '{model_name}' with params: {blueprint_params}")
+        try:
+            blueprint_instance = await get_blueprint_instance(model_name, params=blueprint_params)
+        except Exception as e:
+             logger.error(f"[ReqID: {request_id}] Error getting blueprint instance for '{model_name}': {e}", exc_info=True)
+             raise APIException(f"Failed to load model '{model_name}': {e}", code=status.HTTP_500_INTERNAL_SERVER_ERROR) from e
 
         if blueprint_instance is None:
-            logger.error(f"[ReqID: {request_id}] Blueprint '{model_name}' not found or failed to initialize after access checks.")
+            logger.error(f"[ReqID: {request_id}] Blueprint '{model_name}' not found or failed to initialize (get_blueprint_instance returned None).")
             raise NotFound(f"The requested model (blueprint) '{model_name}' was not found or could not be initialized.")
 
-        if stream: return await self._handle_streaming(blueprint_instance, messages, request_id, model_name)
-        else: return await self._handle_non_streaming(blueprint_instance, messages, request_id, model_name)
+        # --- Handle Streaming or Non-Streaming Response ---
+        if stream:
+            return await self._handle_streaming(blueprint_instance, messages, request_id, model_name)
+        else:
+            return await self._handle_non_streaming(blueprint_instance, messages, request_id, model_name)
+
+
+# ==============================================================================
+# Simple Django Views (Example for Web UI - if ENABLE_WEBUI=True)
+# ==============================================================================
 
+@method_decorator(csrf_exempt, name='dispatch') # Apply csrf_exempt if needed
+@method_decorator(login_required, name='dispatch') # Require login
+class IndexView(View):
+    """ Renders the main chat interface page. """
+    def get(self, request):
+        """ Handles GET requests to render the index page. """
+        # Assuming get_available_blueprints is sync safe
+        available_blueprints = get_available_blueprints()
+        context = {
+            'available_blueprints': available_blueprints,
+            'user': request.user, # User should be available here
+        }
+        return render(request, 'index.html', context)