create-tether-app 0.1.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "create-tether-app",
+  "version": "0.1.0",
+  "description": "CLI tool for scaffolding Tether AI/ML desktop applications",
+  "type": "module",
+  "bin": {
+    "create-tether-app": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist template",
+    "prepublishOnly": "rm -rf template && cp -r ../../template ./template && pnpm build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.0",
+    "ora": "^8.0.0",
+    "validate-npm-package-name": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.11.0",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cli",
+    "tauri",
+    "react",
+    "python",
+    "ai",
+    "ml",
+    "scaffold",
+    "create"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FabianUB/tether.git",
+    "directory": "packages/create-tether-app"
+  },
+  "homepage": "https://github.com/FabianUB/tether#readme",
+  "bugs": {
+    "url": "https://github.com/FabianUB/tether/issues"
+  }
+}

package/template/.env.example

@@ -0,0 +1,18 @@
+# Python Backend Configuration
+TETHER_HOST=127.0.0.1
+TETHER_PORT=8000
+
+# LLM Backend: local, openai, or mock
+TETHER_LLM_BACKEND=local
+
+# For local LLM (llama-cpp-python)
+TETHER_MODEL_PATH=./models/your-model.gguf
+TETHER_CONTEXT_LENGTH=4096
+
+# For OpenAI API
+OPENAI_API_KEY=sk-your-api-key
+TETHER_OPENAI_MODEL=gpt-4o-mini
+
+# Model parameters
+TETHER_DEFAULT_TEMPERATURE=0.7
+TETHER_DEFAULT_MAX_TOKENS=1024

package/template/README.md.template

@@ -0,0 +1,123 @@
+# {{PROJECT_NAME}}
+
+A desktop AI/ML application built with [Tether](https://github.com/your-org/tether).
+
+## Requirements
+
+| Tool | Version | Installation |
+|------|---------|--------------|
+| Node.js | 18+ | [nodejs.org](https://nodejs.org/) |
+| pnpm | 8+ | `npm install -g pnpm` |
+| Python | 3.11+ | [python.org](https://www.python.org/) |
+| uv | latest | [docs.astral.sh/uv](https://docs.astral.sh/uv/) |
+| Rust | latest | [rustup.rs](https://rustup.rs/) |
+
+For Ollama backend (default):
+- [Ollama](https://ollama.com/) installed and running
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development (frontend + backend)
+pnpm dev:all
+```
+
+Open http://localhost:5173 in your browser.
+
+## Commands
+
+### Development
+
+| Command | Description | Port |
+|---------|-------------|------|
+| `pnpm dev` | Start frontend only (Vite) | 5173 |
+| `pnpm dev:py` | Start Python backend only | 8000 |
+| `pnpm dev:all` | Start both frontend and backend | 5173 + 8000 |
+| `pnpm tauri:dev` | Start as desktop app (with hot reload) | — |
+
+### Building
+
+| Command | Description |
+|---------|-------------|
+| `pnpm build` | Build frontend only (→ `dist/`) |
+| `pnpm python:build` | Build Python sidecar (→ `binaries/`) |
+| `pnpm tauri:build` | Build Tauri shell (requires frontend + sidecar) |
+| `pnpm build:app` | **Build everything** (runs all three above in sequence) |
+
+The final app will be in `src-tauri/target/release/bundle/`.
+
+## Configuration
+
+Copy `.env.example` to `.env`:
+
+```bash
+cp .env.example .env
+```
+
+### Ollama (Default)
+
+1. Install [Ollama](https://ollama.com/)
+2. Pull a model:
+   ```bash
+   ollama pull llama3.2
+   ```
+3. Start Ollama:
+   ```bash
+   ollama serve
+   ```
+
+### Local LLM (Embedded)
+
+1. Download a GGUF model from [Hugging Face](https://huggingface.co/models?library=gguf)
+2. Set in `.env`:
+   ```
+   TETHER_LLM_BACKEND=local
+   TETHER_MODEL_PATH=./models/your-model.gguf
+   ```
+
+### OpenAI API (Experimental)
+
+> **Note:** OpenAI support is experimental and not thoroughly tested.
+
+1. Get an API key from [OpenAI](https://platform.openai.com/)
+2. Set in `.env`:
+   ```
+   TETHER_LLM_BACKEND=openai
+   OPENAI_API_KEY=sk-...
+   ```
+
+## Supported Models
+
+| Backend | Models | Notes |
+|---------|--------|-------|
+| **Ollama** | llama3.2, gemma3, qwen3, deepseek-r1, mistral, etc. | See [ollama.com/library](https://ollama.com/library) |
+| **Local LLM** | Any GGUF model | See [Hugging Face GGUF models](https://huggingface.co/models?library=gguf) |
+| **OpenAI** | gpt-4o, gpt-4o-mini, gpt-4-turbo | Experimental |
+
+### Thinking Models
+
+Models with reasoning capabilities (like `deepseek-r1`, `qwen3`) support "thinking mode" which shows the model's reasoning process. This is automatically enabled when available.
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── frontend/             # React frontend
+│   ├── components/       # React components
+│   ├── hooks/            # Custom hooks
+│   └── App.tsx           # Main app component
+├── backend/              # Python backend
+│   ├── app/              # FastAPI application
+│   │   ├── routes/       # API endpoints
+│   │   └── services/     # Business logic
+│   └── scripts/          # Build scripts
+└── src-tauri/            # Tauri (Rust) shell
+    └── src/              # Rust source code
+```
+
+## License
+
+MIT License

package/template/backend/app/__init__.py.template

@@ -0,0 +1,5 @@
+"""
+{{PROJECT_NAME}} Python backend.
+"""
+
+__version__ = "0.1.0"

package/template/backend/app/main.py

@@ -0,0 +1,66 @@
+"""
+FastAPI application entry point.
+"""
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.routes import health, chat, models
+from app.services.llm import get_llm_service
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Application lifespan manager."""
+    # Startup: Initialize LLM service
+    llm_service = get_llm_service()
+    await llm_service.initialize()
+    app.state.llm_service = llm_service
+
+    yield
+
+    # Shutdown: Cleanup
+    await llm_service.cleanup()
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="Tether Backend",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    # Configure CORS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Include routers
+    app.include_router(health.router)
+    app.include_router(chat.router)
+    app.include_router(models.router)
+
+    return app
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    import argparse
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="Tether Backend API Server")
+    parser.add_argument("--port", type=int, default=8000, help="Port to run the server on")
+    parser.add_argument("--host", type=str, default="127.0.0.1", help="Host to bind to")
+    args = parser.parse_args()
+
+    uvicorn.run(app, host=args.host, port=args.port)

package/template/backend/app/routes/__init__.py

@@ -0,0 +1,3 @@
+"""
+API routes.
+"""

package/template/backend/app/routes/chat.py

@@ -0,0 +1,151 @@
+"""
+Chat completion endpoints.
+"""
+
+import re
+from typing import Literal, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+
+class ChatMessage(BaseModel):
+    role: Literal["user", "assistant", "system"]
+    content: str
+    images: Optional[list[str]] = Field(
+        default=None, description="Base64-encoded images for vision models"
+    )
+    timestamp: Optional[int] = None
+
+
+class ChatRequest(BaseModel):
+    message: str = Field(..., description="The user's message")
+    images: Optional[list[str]] = Field(
+        default=None, description="Base64-encoded images for vision models"
+    )
+    history: Optional[list[ChatMessage]] = Field(
+        default=None, description="Previous messages in the conversation"
+    )
+    model: Optional[str] = Field(default=None, description="Model to use")
+    temperature: Optional[float] = Field(
+        default=0.7, ge=0.0, le=2.0, description="Sampling temperature"
+    )
+    max_tokens: Optional[int] = Field(
+        default=None, ge=1, description="Maximum tokens to generate"
+    )
+    think: Optional[bool] = Field(
+        default=True, description="Enable thinking mode for reasoning models"
+    )
+
+
+class ChatResponse(BaseModel):
+    response: str = Field(..., description="The assistant's response")
+    thinking: Optional[str] = Field(
+        default=None, description="Model's reasoning/thinking content (for thinking models)"
+    )
+    tokens_used: Optional[int] = Field(
+        default=None, description="Number of tokens used"
+    )
+    model: Optional[str] = Field(default=None, description="Model used")
+    finish_reason: Optional[Literal["stop", "length", "error"]] = Field(
+        default="stop", description="Reason for completion"
+    )
+
+
+def parse_thinking_content(text: str) -> tuple[str, Optional[str]]:
+    """
+    Parse thinking content from model response.
+
+    Thinking models like Qwen3 wrap reasoning in <think>...</think> tags.
+
+    Returns:
+        Tuple of (response_without_thinking, thinking_content)
+    """
+    # Match <think>...</think> tags (case insensitive, multiline)
+    think_pattern = re.compile(r"<think>(.*?)</think>", re.DOTALL | re.IGNORECASE)
+
+    thinking_parts = think_pattern.findall(text)
+
+    if not thinking_parts:
+        return text, None
+
+    # Remove thinking tags from response
+    response = think_pattern.sub("", text).strip()
+
+    # Combine all thinking parts (in case there are multiple)
+    thinking = "\n\n".join(part.strip() for part in thinking_parts)
+
+    return response, thinking
+
+
+router = APIRouter()
+
+
+@router.post("/chat", response_model=ChatResponse)
+async def chat(request: Request, body: ChatRequest) -> ChatResponse:
+    """Generate a chat completion."""
+    llm_service = getattr(request.app.state, "llm_service", None)
+
+    if llm_service is None or not llm_service.is_ready():
+        raise HTTPException(status_code=503, detail="LLM service not available")
+
+    try:
+        # Build messages list for chat API
+        # Note: We don't include images from history because:
+        # 1. Non-vision models can't handle them (Ollama converts to [img-0] placeholders)
+        # 2. Vision models typically can't "remember" images from earlier turns anyway
+        messages = []
+        if body.history:
+            for msg in body.history:
+                # Strip images from history - only text content
+                messages.append({"role": msg.role, "content": msg.content})
+
+        # Add current message with optional images (only current turn gets images)
+        current_msg = {"role": "user", "content": body.message}
+        if body.images:
+            current_msg["images"] = body.images
+        messages.append(current_msg)
+
+        # Check if current message has images (vision models don't support thinking)
+        has_images = bool(body.images)
+        # Disable thinking for vision requests (not supported by Ollama)
+        use_thinking = False if has_images else (body.think if body.think is not None else True)
+
+        # Use chat API if available (supports thinking models), fallback to complete
+        if hasattr(llm_service, "chat"):
+            result = await llm_service.chat(
+                messages,
+                temperature=body.temperature or 0.7,
+                max_tokens=body.max_tokens,
+                think=use_thinking,
+            )
+            # chat() returns dict with 'content' and 'thinking'
+            if isinstance(result, dict):
+                response = result.get("content", "")
+                thinking = result.get("thinking")
+            else:
+                # Fallback if chat returns string
+                response, thinking = parse_thinking_content(result)
+        else:
+            # Fallback for services without chat method
+            prompt = body.message
+            if body.history:
+                history_text = "\n".join(
+                    f"{msg.role}: {msg.content}" for msg in body.history
+                )
+                prompt = f"{history_text}\nuser: {body.message}\nassistant:"
+            raw_response = await llm_service.complete(
+                prompt,
+                temperature=body.temperature or 0.7,
+                max_tokens=body.max_tokens,
+            )
+            response, thinking = parse_thinking_content(raw_response)
+
+        return ChatResponse(
+            response=response,
+            thinking=thinking,
+            model=llm_service.model_name,
+            finish_reason="stop",
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

package/template/backend/app/routes/health.py

@@ -0,0 +1,28 @@
+"""
+Health check endpoint.
+"""
+
+from fastapi import APIRouter, Request
+from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+    status: str
+    model_loaded: bool
+    version: str
+
+
+router = APIRouter()
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health(request: Request) -> HealthResponse:
+    """Health check endpoint."""
+    llm_service = getattr(request.app.state, "llm_service", None)
+    model_loaded = llm_service.is_ready() if llm_service else False
+
+    return HealthResponse(
+        status="healthy",
+        model_loaded=model_loaded,
+        version="0.1.0",
+    )

package/template/backend/app/routes/models.py

@@ -0,0 +1,126 @@
+"""
+Model discovery and switching endpoints.
+"""
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from app.services.llm import discover_ollama, get_ollama_base_url
+
+
+class ModelsResponse(BaseModel):
+    available: bool
+    current_model: str | None
+    models: list[str]
+    backend: str
+    error: str | None = None
+
+
+class SwitchModelRequest(BaseModel):
+    model: str = Field(..., description="Model name to switch to")
+
+
+class SwitchModelResponse(BaseModel):
+    success: bool
+    previous_model: str | None
+    current_model: str
+    message: str
+
+
+router = APIRouter()
+
+
+@router.get("/models", response_model=ModelsResponse)
+async def list_models(request: Request) -> ModelsResponse:
+    """
+    List available models.
+
+    For Ollama backend, discovers available models from the Ollama API.
+    For other backends, returns the configured model.
+    """
+    llm_service = getattr(request.app.state, "llm_service", None)
+
+    if not llm_service:
+        return ModelsResponse(
+            available=False,
+            current_model=None,
+            models=[],
+            backend="none",
+            error="No LLM service configured",
+        )
+
+    backend = llm_service.service_type
+
+    # For Ollama, use discovery
+    if backend == "ollama":
+        discovery = await discover_ollama(get_ollama_base_url())
+        return ModelsResponse(
+            available=discovery.available,
+            current_model=llm_service.model_name if llm_service.is_ready() else None,
+            models=discovery.models,
+            backend=backend,
+            error=discovery.error,
+        )
+
+    # For other backends, return the configured model
+    return ModelsResponse(
+        available=llm_service.is_ready(),
+        current_model=llm_service.model_name,
+        models=[llm_service.model_name] if llm_service.is_ready() else [],
+        backend=backend,
+    )
+
+
+@router.post("/models/switch", response_model=SwitchModelResponse)
+async def switch_model(request: Request, body: SwitchModelRequest) -> SwitchModelResponse:
+    """
+    Switch to a different model.
+
+    For Ollama backend, switches to the specified model.
+    Other backends may not support runtime model switching.
+    """
+    llm_service = getattr(request.app.state, "llm_service", None)
+
+    if not llm_service:
+        raise HTTPException(status_code=503, detail="No LLM service configured")
+
+    if not llm_service.is_ready():
+        raise HTTPException(status_code=503, detail="LLM service not ready")
+
+    backend = llm_service.service_type
+    previous_model = llm_service.model_name
+
+    # For Ollama, we can switch models at runtime
+    if backend == "ollama":
+        # Verify the model exists
+        discovery = await discover_ollama(get_ollama_base_url())
+        if not discovery.available:
+            raise HTTPException(status_code=503, detail="Ollama not available")
+
+        # Check if model is in available models (exact match or base name match)
+        model_found = any(
+            body.model == m or body.model == m.split(":")[0]
+            for m in discovery.models
+        )
+
+        if not model_found:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Model '{body.model}' not found. Available: {', '.join(discovery.models)}",
+            )
+
+        # Switch the model
+        llm_service._model = body.model
+
+        return SwitchModelResponse(
+            success=True,
+            previous_model=previous_model,
+            current_model=body.model,
+            message=f"Switched from {previous_model} to {body.model}",
+        )
+
+    # Other backends don't support runtime switching
+    raise HTTPException(
+        status_code=400,
+        detail=f"Backend '{backend}' does not support runtime model switching",
+    )

package/template/backend/app/services/__init__.py

@@ -0,0 +1,3 @@
+"""
+Application services.
+"""