format
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ UserContext if valid header found, None otherwise
+ """
+ auth_header = request.headers.get("Authorization", "")
+
+ if auth_header.startswith("Bearer "):
+ token = auth_header[7:]
+ # Attempt to decode JWT claims
+ claims = decode_jwt_claims(token)
+ if claims:
+ username = claims.get("username") or claims.get("sub", "")
+ actor_id = claims.get("actor_id") or claims.get("actor")
+ # Default actor_id to @username if not provided
+ if not actor_id and username:
+ actor_id = f"@{username}"
+ return UserContext(
+ username=username,
+ actor_id=actor_id or "",
+ token=token,
+ )
+
+ return None
+
+
+def decode_jwt_claims(token: str) -> Optional[dict]:
+ """
+ Decode JWT claims without verification.
+
+ This is useful for extracting user info from a token
+ when full verification is handled elsewhere.
+
+ Args:
+ token: JWT token string
+
+ Returns:
+ Claims dict if valid JWT format, None otherwise
+ """
+ try:
+ parts = token.split(".")
+ if len(parts) != 3:
+ return None
+
+ # Decode payload (second part)
+ payload = parts[1]
+ # Add padding if needed
+ padding = 4 - len(payload) % 4
+ if padding != 4:
+ payload += "=" * padding
+
+ return json.loads(base64.urlsafe_b64decode(payload))
+ except (json.JSONDecodeError, ValueError):
+ return None
+
+
+def create_auth_dependency(
+ token_validator: Optional[Callable[[str], Awaitable[Optional[dict]]]] = None,
+ allow_cookie: bool = True,
+ allow_header: bool = True,
+):
+ """
+ Create a customized auth dependency for a specific server.
+
+ Args:
+ token_validator: Optional async function to validate tokens with backend
+ allow_cookie: Whether to check cookies for auth
+ allow_header: Whether to check Authorization header
+
+ Returns:
+ FastAPI dependency function
+ """
+ async def get_current_user(request: Request) -> Optional[UserContext]:
+ ctx = None
+
+ # Try header first (API clients)
+ if allow_header:
+ ctx = get_user_from_header(request)
+ if ctx and token_validator:
+ # Validate token with backend
+ validated = await token_validator(ctx.token)
+ if not validated:
+ ctx = None
+
+ # Fall back to cookie (browser)
+ if ctx is None and allow_cookie:
+ ctx = get_user_from_cookie(request)
+
+ return ctx
+
+ return get_current_user
+
+
+async def require_auth(request: Request) -> UserContext:
+ """
+ Dependency that requires authentication.
+
+ Raises HTTPException 401 if not authenticated.
+ Use with Depends() in route handlers.
+
+ Example:
+ @app.get("/protected")
+ async def protected_route(user: UserContext = Depends(require_auth)):
+ return {"user": user.username}
+ """
+ # Try header first
+ ctx = get_user_from_header(request)
+ if ctx is None:
+ ctx = get_user_from_cookie(request)
+
+ if ctx is None:
+ # Check Accept header to determine response type
+ accept = request.headers.get("accept", "")
+ if "text/html" in accept:
+ raise HTTPException(
+ status_code=302,
+ headers={"Location": "/login"}
+ )
+ raise HTTPException(
+ status_code=401,
+ detail="Authentication required"
+ )
+
+ return ctx
+
+
+def require_owner(resource_owner_field: str = "username"):
+ """
+ Dependency factory that requires the user to own the resource.
+
+ Args:
+ resource_owner_field: Field name on the resource that contains owner username
+
+ Returns:
+ Dependency function
+
+ Example:
+ @app.delete("/items/{item_id}")
+ async def delete_item(
+ item: Item = Depends(get_item),
+ user: UserContext = Depends(require_owner("created_by"))
+ ):
+ ...
+ """
+ async def check_ownership(
+ request: Request,
+ user: UserContext = Depends(require_auth),
+ ) -> UserContext:
+ # The actual ownership check must be done in the route
+ # after fetching the resource
+ return user
+
+ return check_ownership
+
+
+def set_auth_cookie(response: Any, user: UserContext, max_age: int = 86400 * 30) -> None:
+ """
+ Set authentication cookie on response.
+
+ Args:
+ response: FastAPI response object
+ user: User context to store
+ max_age: Cookie max age in seconds (default 30 days)
+ """
+ cookie_data = {
+ "username": user.username,
+ "actor_id": user.actor_id,
+ }
+ if user.email:
+ cookie_data["email"] = user.email
+ data = json.dumps(cookie_data)
+ cookie_value = base64.b64encode(data.encode()).decode()
+
+ response.set_cookie(
+ key="artdag_session",
+ value=cookie_value,
+ max_age=max_age,
+ httponly=True,
+ samesite="lax",
+ secure=True, # Require HTTPS in production
+ )
+
+
+def clear_auth_cookie(response: Any) -> None:
+ """Clear authentication cookie."""
+ response.delete_cookie(key="artdag_session")
diff --git a/common/artdag_common/middleware/content_negotiation.py b/common/artdag_common/middleware/content_negotiation.py
new file mode 100644
index 0000000..aaa47c8
--- /dev/null
+++ b/common/artdag_common/middleware/content_negotiation.py
@@ -0,0 +1,174 @@
+"""
+Content negotiation utilities.
+
+Helps determine what response format the client wants.
+"""
+
+from enum import Enum
+from typing import Optional
+
+from fastapi import Request
+
+
+class ContentType(Enum):
+ """Response content types."""
+ HTML = "text/html"
+ JSON = "application/json"
+ ACTIVITY_JSON = "application/activity+json"
+ XML = "application/xml"
+
+
+def wants_html(request: Request) -> bool:
+ """
+ Check if the client wants HTML response.
+
+ Returns True if:
+ - Accept header contains text/html
+ - Accept header contains application/xhtml+xml
+ - No Accept header (browser default)
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ True if HTML is preferred
+ """
+ accept = request.headers.get("accept", "")
+
+ # No accept header usually means browser
+ if not accept:
+ return True
+
+ # Check for HTML preferences
+ if "text/html" in accept:
+ return True
+ if "application/xhtml" in accept:
+ return True
+
+ return False
+
+
+def wants_json(request: Request) -> bool:
+ """
+ Check if the client wants JSON response.
+
+ Returns True if:
+ - Accept header contains application/json
+ - Accept header does NOT contain text/html
+ - Request has .json suffix (convention)
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ True if JSON is preferred
+ """
+ accept = request.headers.get("accept", "")
+
+ # Explicit JSON preference
+ if "application/json" in accept:
+ # But not if HTML is also requested (browsers often send both)
+ if "text/html" not in accept:
+ return True
+
+ # Check URL suffix convention
+ if request.url.path.endswith(".json"):
+ return True
+
+ return False
+
+
+def wants_activity_json(request: Request) -> bool:
+ """
+ Check if the client wants ActivityPub JSON-LD response.
+
+ Used for federation with other ActivityPub servers.
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ True if ActivityPub format is preferred
+ """
+ accept = request.headers.get("accept", "")
+
+ if "application/activity+json" in accept:
+ return True
+ if "application/ld+json" in accept:
+ return True
+
+ return False
+
+
+def get_preferred_type(request: Request) -> ContentType:
+ """
+ Determine the preferred content type from Accept header.
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ ContentType enum value
+ """
+ if wants_activity_json(request):
+ return ContentType.ACTIVITY_JSON
+ if wants_json(request):
+ return ContentType.JSON
+ return ContentType.HTML
+
+
+def is_htmx_request(request: Request) -> bool:
+ """
+ Check if this is an HTMX request (partial page update).
+
+ HTMX requests set the HX-Request header.
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ True if this is an HTMX request
+ """
+ return request.headers.get("HX-Request") == "true"
+
+
+def get_htmx_target(request: Request) -> Optional[str]:
+ """
+ Get the HTMX target element ID.
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ Target element ID or None
+ """
+ return request.headers.get("HX-Target")
+
+
+def get_htmx_trigger(request: Request) -> Optional[str]:
+ """
+ Get the HTMX trigger element ID.
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ Trigger element ID or None
+ """
+ return request.headers.get("HX-Trigger")
+
+
+def is_ios_request(request: Request) -> bool:
+ """
+ Check if request is from iOS device.
+
+ Useful for video format selection (iOS prefers MP4).
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ True if iOS user agent detected
+ """
+ user_agent = request.headers.get("user-agent", "").lower()
+ return "iphone" in user_agent or "ipad" in user_agent
diff --git a/common/artdag_common/models/__init__.py b/common/artdag_common/models/__init__.py
new file mode 100644
index 0000000..d0d43c7
--- /dev/null
+++ b/common/artdag_common/models/__init__.py
@@ -0,0 +1,25 @@
+"""
+Shared Pydantic models for Art-DAG servers.
+"""
+
+from .requests import (
+ PaginationParams,
+ PublishRequest,
+ StorageConfigRequest,
+ MetadataUpdateRequest,
+)
+from .responses import (
+ PaginatedResponse,
+ ErrorResponse,
+ SuccessResponse,
+)
+
+__all__ = [
+ "PaginationParams",
+ "PublishRequest",
+ "StorageConfigRequest",
+ "MetadataUpdateRequest",
+ "PaginatedResponse",
+ "ErrorResponse",
+ "SuccessResponse",
+]
diff --git a/common/artdag_common/models/requests.py b/common/artdag_common/models/requests.py
new file mode 100644
index 0000000..1c34d45
--- /dev/null
+++ b/common/artdag_common/models/requests.py
@@ -0,0 +1,74 @@
+"""
+Request models shared across L1 and L2 servers.
+"""
+
+from typing import Optional, List, Dict, Any
+from pydantic import BaseModel, Field
+
+from ..constants import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+
+
+class PaginationParams(BaseModel):
+ """Common pagination parameters."""
+ page: int = Field(default=1, ge=1, description="Page number (1-indexed)")
+ limit: int = Field(
+ default=DEFAULT_PAGE_SIZE,
+ ge=1,
+ le=MAX_PAGE_SIZE,
+ description="Items per page"
+ )
+
+ @property
+ def offset(self) -> int:
+ """Calculate offset for database queries."""
+ return (self.page - 1) * self.limit
+
+
+class PublishRequest(BaseModel):
+ """Request to publish content to L2/storage."""
+ name: str = Field(..., min_length=1, max_length=255)
+ description: Optional[str] = Field(default=None, max_length=2000)
+ tags: List[str] = Field(default_factory=list)
+ storage_id: Optional[str] = Field(default=None, description="Target storage provider")
+
+
+class MetadataUpdateRequest(BaseModel):
+ """Request to update content metadata."""
+ name: Optional[str] = Field(default=None, max_length=255)
+ description: Optional[str] = Field(default=None, max_length=2000)
+ tags: Optional[List[str]] = Field(default=None)
+ metadata: Optional[Dict[str, Any]] = Field(default=None)
+
+
+class StorageConfigRequest(BaseModel):
+ """Request to configure a storage provider."""
+ provider_type: str = Field(..., description="Provider type (pinata, web3storage, local, etc.)")
+ name: str = Field(..., min_length=1, max_length=100)
+ api_key: Optional[str] = Field(default=None)
+ api_secret: Optional[str] = Field(default=None)
+ endpoint: Optional[str] = Field(default=None)
+ config: Optional[Dict[str, Any]] = Field(default_factory=dict)
+ is_default: bool = Field(default=False)
+
+
+class RecipeRunRequest(BaseModel):
+ """Request to run a recipe."""
+ recipe_id: str = Field(..., description="Recipe content hash or ID")
+ inputs: Dict[str, str] = Field(..., description="Map of input name to content hash")
+ features: List[str] = Field(
+ default=["beats", "energy"],
+ description="Analysis features to extract"
+ )
+
+
+class PlanRequest(BaseModel):
+ """Request to generate an execution plan."""
+ recipe_yaml: str = Field(..., description="Recipe YAML content")
+ input_hashes: Dict[str, str] = Field(..., description="Map of input name to content hash")
+ features: List[str] = Field(default=["beats", "energy"])
+
+
+class ExecutePlanRequest(BaseModel):
+ """Request to execute a generated plan."""
+ plan_json: str = Field(..., description="JSON-serialized execution plan")
+ run_id: Optional[str] = Field(default=None, description="Optional run ID for tracking")
diff --git a/common/artdag_common/models/responses.py b/common/artdag_common/models/responses.py
new file mode 100644
index 0000000..447e70c
--- /dev/null
+++ b/common/artdag_common/models/responses.py
@@ -0,0 +1,96 @@
+"""
+Response models shared across L1 and L2 servers.
+"""
+
+from typing import Optional, List, Dict, Any, Generic, TypeVar
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+ """Generic paginated response."""
+ data: List[Any] = Field(default_factory=list)
+ pagination: Dict[str, Any] = Field(default_factory=dict)
+
+ @classmethod
+ def create(
+ cls,
+ items: List[Any],
+ page: int,
+ limit: int,
+ total: int,
+ ) -> "PaginatedResponse":
+ """Create a paginated response."""
+ return cls(
+ data=items,
+ pagination={
+ "page": page,
+ "limit": limit,
+ "total": total,
+ "has_more": page * limit < total,
+ "total_pages": (total + limit - 1) // limit,
+ }
+ )
+
+
+class ErrorResponse(BaseModel):
+ """Standard error response."""
+ error: str = Field(..., description="Error message")
+ detail: Optional[str] = Field(default=None, description="Detailed error info")
+ code: Optional[str] = Field(default=None, description="Error code")
+
+
+class SuccessResponse(BaseModel):
+ """Standard success response."""
+ success: bool = Field(default=True)
+ message: Optional[str] = Field(default=None)
+ data: Optional[Dict[str, Any]] = Field(default=None)
+
+
+class RunStatus(BaseModel):
+ """Run execution status."""
+ run_id: str
+ status: str = Field(..., description="pending, running, completed, failed")
+ recipe: Optional[str] = None
+ plan_id: Optional[str] = None
+ output_hash: Optional[str] = None
+ output_ipfs_cid: Optional[str] = None
+ total_steps: int = 0
+ cached_steps: int = 0
+ completed_steps: int = 0
+ error: Optional[str] = None
+
+
+class CacheItemResponse(BaseModel):
+ """Cached content item response."""
+ content_hash: str
+ media_type: Optional[str] = None
+ size: Optional[int] = None
+ name: Optional[str] = None
+ description: Optional[str] = None
+ tags: List[str] = Field(default_factory=list)
+ ipfs_cid: Optional[str] = None
+ created_at: Optional[str] = None
+
+
+class RecipeResponse(BaseModel):
+ """Recipe response."""
+ recipe_id: str
+ name: str
+ description: Optional[str] = None
+ inputs: List[Dict[str, Any]] = Field(default_factory=list)
+ outputs: List[str] = Field(default_factory=list)
+ node_count: int = 0
+ created_at: Optional[str] = None
+
+
+class StorageProviderResponse(BaseModel):
+ """Storage provider configuration response."""
+ storage_id: str
+ provider_type: str
+ name: str
+ is_default: bool = False
+ is_connected: bool = False
+ usage_bytes: Optional[int] = None
+ pin_count: int = 0
diff --git a/common/artdag_common/rendering.py b/common/artdag_common/rendering.py
new file mode 100644
index 0000000..e5edacf
--- /dev/null
+++ b/common/artdag_common/rendering.py
@@ -0,0 +1,160 @@
+"""
+Jinja2 template rendering system for Art-DAG servers.
+
+Provides a unified template environment that can load from:
+1. The shared artdag_common/templates directory
+2. App-specific template directories
+
+Usage:
+ from artdag_common import create_jinja_env, render
+
+ # In app initialization
+ templates = create_jinja_env("app/templates")
+
+ # In route handler
+ return render(templates, "runs/detail.html", request, run=run, user=user)
+"""
+
+from pathlib import Path
+from typing import Any, Optional, Union
+
+from fastapi import Request
+from fastapi.responses import HTMLResponse
+from jinja2 import Environment, ChoiceLoader, FileSystemLoader, PackageLoader, select_autoescape
+
+from .constants import (
+ TAILWIND_CDN,
+ HTMX_CDN,
+ CYTOSCAPE_CDN,
+ DAGRE_CDN,
+ CYTOSCAPE_DAGRE_CDN,
+ TAILWIND_CONFIG,
+ NODE_COLORS,
+ STATUS_COLORS,
+)
+
+
+def create_jinja_env(*template_dirs: Union[str, Path]) -> Environment:
+ """
+ Create a Jinja2 environment with the shared templates and optional app-specific dirs.
+
+ Args:
+ *template_dirs: Additional template directories to search (app-specific)
+
+ Returns:
+ Configured Jinja2 Environment
+
+ Example:
+ env = create_jinja_env("/app/templates", "/app/custom")
+ """
+ loaders = []
+
+ # Add app-specific directories first (higher priority)
+ for template_dir in template_dirs:
+ path = Path(template_dir)
+ if path.exists():
+ loaders.append(FileSystemLoader(str(path)))
+
+ # Add shared templates from this package (lower priority, fallback)
+ loaders.append(PackageLoader("artdag_common", "templates"))
+
+ env = Environment(
+ loader=ChoiceLoader(loaders),
+ autoescape=select_autoescape(["html", "xml"]),
+ trim_blocks=True,
+ lstrip_blocks=True,
+ )
+
+ # Add global context available to all templates
+ env.globals.update({
+ "TAILWIND_CDN": TAILWIND_CDN,
+ "HTMX_CDN": HTMX_CDN,
+ "CYTOSCAPE_CDN": CYTOSCAPE_CDN,
+ "DAGRE_CDN": DAGRE_CDN,
+ "CYTOSCAPE_DAGRE_CDN": CYTOSCAPE_DAGRE_CDN,
+ "TAILWIND_CONFIG": TAILWIND_CONFIG,
+ "NODE_COLORS": NODE_COLORS,
+ "STATUS_COLORS": STATUS_COLORS,
+ })
+
+ # Add custom filters
+ env.filters["truncate_hash"] = truncate_hash
+ env.filters["format_size"] = format_size
+ env.filters["status_color"] = status_color
+
+ return env
+
+
+def render(
+ env: Environment,
+ template_name: str,
+ request: Request,
+ status_code: int = 200,
+ **context: Any,
+) -> HTMLResponse:
+ """
+ Render a template to an HTMLResponse.
+
+ Args:
+ env: Jinja2 environment
+ template_name: Template file path (e.g., "runs/detail.html")
+ request: FastAPI request object
+ status_code: HTTP status code (default 200)
+ **context: Template context variables
+
+ Returns:
+ HTMLResponse with rendered content
+ """
+ template = env.get_template(template_name)
+ html = template.render(request=request, **context)
+ return HTMLResponse(html, status_code=status_code)
+
+
+def render_fragment(
+ env: Environment,
+ template_name: str,
+ **context: Any,
+) -> str:
+ """
+ Render a template fragment to a string (for HTMX partial updates).
+
+ Args:
+ env: Jinja2 environment
+ template_name: Template file path
+ **context: Template context variables
+
+ Returns:
+ Rendered HTML string
+ """
+ template = env.get_template(template_name)
+ return template.render(**context)
+
+
+# Custom Jinja2 filters
+
+def truncate_hash(value: str, length: int = 16) -> str:
+ """Truncate a hash to specified length with ellipsis."""
+ if not value:
+ return ""
+ if len(value) <= length:
+ return value
+ return f"{value[:length]}..."
+
+
+def format_size(size_bytes: Optional[int]) -> str:
+ """Format file size in human-readable form."""
+ if size_bytes is None:
+ return "Unknown"
+ if size_bytes < 1024:
+ return f"{size_bytes} B"
+ elif size_bytes < 1024 * 1024:
+ return f"{size_bytes / 1024:.1f} KB"
+ elif size_bytes < 1024 * 1024 * 1024:
+ return f"{size_bytes / (1024 * 1024):.1f} MB"
+ else:
+ return f"{size_bytes / (1024 * 1024 * 1024):.1f} GB"
+
+
+def status_color(status: str) -> str:
+ """Get Tailwind CSS class for a status."""
+ return STATUS_COLORS.get(status, STATUS_COLORS["pending"])
diff --git a/common/artdag_common/templates/_base.html b/common/artdag_common/templates/_base.html
new file mode 100644
index 0000000..deeb67b
--- /dev/null
+++ b/common/artdag_common/templates/_base.html
@@ -0,0 +1,91 @@
+
+
+
+
+
+ {% block title %}Art-DAG{% endblock %}
+
+
+
+
+
+
+
+
+
+
+
+ {% block head %}{% endblock %}
+
+
+
+
+
+ {% block header %}
+ {# Coop-style header: sky banner with title, nav-tree, auth-menu, cart-mini #}
+
+
+
+ {# Cart mini #}
+ {% block cart_mini %}{% endblock %}
+
+ {# Site title #}
+
+
+ {# Desktop nav: nav-tree + auth-menu #}
+
+
+
+ {# Mobile auth #}
+
+ {% block auth_menu_mobile %}{% endblock %}
+
+
Card content here
+ {% endcall %}
+#}
+
+{% macro card(title=None, class="") %}
+
+ {% if title %}
+
{{ title }}
+ {% endif %}
+
+ {{ caller() if caller else "" }}
+
+
+
{{ value }}
+
{{ title }}
+
+ {% if title %}
+
{{ title }}
+ {% endif %}
+
+ {% for label, value in items %}
+
+
- {{ label }}
+ - {{ value }}
+
+ {% endfor %}
+
+
+ {% for type in types %}
+
+
+ {{ type }}
+
+ {% endfor %}
+
+
+ Cached
+
+
+{% endmacro %}
diff --git a/common/artdag_common/templates/components/media_preview.html b/common/artdag_common/templates/components/media_preview.html
new file mode 100644
index 0000000..ec810ae
--- /dev/null
+++ b/common/artdag_common/templates/components/media_preview.html
@@ -0,0 +1,98 @@
+{#
+Media preview component for videos, images, and audio.
+
+Usage:
+ {% from "components/media_preview.html" import media_preview, video_player, image_preview, audio_player %}
+
+ {{ media_preview(content_hash, media_type, title="Preview") }}
+ {{ video_player(src="/cache/abc123/mp4", poster="/cache/abc123/thumb") }}
+#}
+
+{% macro media_preview(content_hash, media_type, title=None, class="", show_download=True) %}
+
+ {% if title %}
+
+
{{ title }}
+
+ {% endif %}
+
+
+ {% if media_type == "video" %}
+ {{ video_player("/cache/" + content_hash + "/mp4") }}
+ {% elif media_type == "image" %}
+ {{ image_preview("/cache/" + content_hash + "/raw") }}
+ {% elif media_type == "audio" %}
+ {{ audio_player("/cache/" + content_hash + "/raw") }}
+ {% else %}
+
+
+
Preview not available
+
+ {% endif %}
+
+
+ {% if show_download %}
+
+ {% endif %}
+
+{% endmacro %}
+
+{% macro audio_player(src, class="") %}
+
+
+
+ {% if media_type == "image" %}
+
+ {% elif media_type == "video" %}
+
+ {% elif media_type == "audio" %}
+
+ {% else %}
+
+ {% endif %}
+
+ |
+
+
+ Loading more...
+
+ |
+
+{% endif %}
+{% endmacro %}
+
+{% macro page_links(current_page, total_pages, base_url, class="") %}
+
+{% endmacro %}
+
+{% macro page_info(page, limit, total) %}
+
+ Showing {{ (page - 1) * limit + 1 }}-{{ [page * limit, total] | min }} of {{ total }}
+
+{% endmacro %}
diff --git a/common/artdag_common/templates/components/table.html b/common/artdag_common/templates/components/table.html
new file mode 100644
index 0000000..1c00fc4
--- /dev/null
+++ b/common/artdag_common/templates/components/table.html
@@ -0,0 +1,51 @@
+{#
+Table component with dark theme styling.
+
+Usage:
+ {% from "components/table.html" import table, table_row %}
+
+ {% call table(columns=["Name", "Status", "Actions"]) %}
+ {% for item in items %}
+ {{ table_row([item.name, item.status, actions_html]) }}
+ {% endfor %}
+ {% endcall %}
+#}
+
+{% macro table(columns, class="", id="") %}
+
+
+
+
+ {% for col in columns %}
+ | {{ col }} |
+ {% endfor %}
+
+
+
+ {{ caller() }}
+
+
+
+ {% for cell in cells %}
+ |
+ {% if href and loop.first %}
+ {{ cell }}
+ {% else %}
+ {{ cell | safe }}
+ {% endif %}
+ |
+ {% endfor %}
+
+{% endmacro %}
+
+{% macro empty_row(colspan, message="No items found") %}
+
+ |
+ {{ message }}
+ |
+
+{% endmacro %}
diff --git a/common/artdag_common/utils/__init__.py b/common/artdag_common/utils/__init__.py
new file mode 100644
index 0000000..192edfa
--- /dev/null
+++ b/common/artdag_common/utils/__init__.py
@@ -0,0 +1,19 @@
+"""
+Utility functions shared across Art-DAG servers.
+"""
+
+from .pagination import paginate, get_pagination_params
+from .media import detect_media_type, get_media_extension, is_streamable
+from .formatting import format_date, format_size, truncate_hash, format_duration
+
+__all__ = [
+ "paginate",
+ "get_pagination_params",
+ "detect_media_type",
+ "get_media_extension",
+ "is_streamable",
+ "format_date",
+ "format_size",
+ "truncate_hash",
+ "format_duration",
+]
diff --git a/common/artdag_common/utils/formatting.py b/common/artdag_common/utils/formatting.py
new file mode 100644
index 0000000..3dcc3a8
--- /dev/null
+++ b/common/artdag_common/utils/formatting.py
@@ -0,0 +1,165 @@
+"""
+Formatting utilities for display.
+"""
+
+from datetime import datetime
+from typing import Optional, Union
+
+
+def format_date(
+ value: Optional[Union[str, datetime]],
+ length: int = 10,
+ include_time: bool = False,
+) -> str:
+ """
+ Format a date/datetime for display.
+
+ Args:
+ value: Date string or datetime object
+ length: Length to truncate to (default 10 for YYYY-MM-DD)
+ include_time: Whether to include time portion
+
+ Returns:
+ Formatted date string
+ """
+ if value is None:
+ return ""
+
+ if isinstance(value, str):
+ # Parse ISO format string
+ try:
+ if "T" in value:
+ dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+ else:
+ return value[:length]
+ except ValueError:
+ return value[:length]
+ else:
+ dt = value
+
+ if include_time:
+ return dt.strftime("%Y-%m-%d %H:%M")
+ return dt.strftime("%Y-%m-%d")
+
+
+def format_size(size_bytes: Optional[int]) -> str:
+ """
+ Format file size in human-readable form.
+
+ Args:
+ size_bytes: Size in bytes
+
+ Returns:
+ Human-readable size string (e.g., "1.5 MB")
+ """
+ if size_bytes is None:
+ return "Unknown"
+ if size_bytes < 0:
+ return "Unknown"
+ if size_bytes == 0:
+ return "0 B"
+
+ units = ["B", "KB", "MB", "GB", "TB"]
+ unit_index = 0
+ size = float(size_bytes)
+
+ while size >= 1024 and unit_index < len(units) - 1:
+ size /= 1024
+ unit_index += 1
+
+ if unit_index == 0:
+ return f"{int(size)} {units[unit_index]}"
+ return f"{size:.1f} {units[unit_index]}"
+
+
+def truncate_hash(value: str, length: int = 16, suffix: str = "...") -> str:
+ """
+ Truncate a hash or long string with ellipsis.
+
+ Args:
+ value: String to truncate
+ length: Maximum length before truncation
+ suffix: Suffix to add when truncated
+
+ Returns:
+ Truncated string
+ """
+ if not value:
+ return ""
+ if len(value) <= length:
+ return value
+ return f"{value[:length]}{suffix}"
+
+
+def format_duration(seconds: Optional[float]) -> str:
+ """
+ Format duration in human-readable form.
+
+ Args:
+ seconds: Duration in seconds
+
+ Returns:
+ Human-readable duration string (e.g., "2m 30s")
+ """
+ if seconds is None or seconds < 0:
+ return "Unknown"
+
+ if seconds < 1:
+ return f"{int(seconds * 1000)}ms"
+
+ if seconds < 60:
+ return f"{seconds:.1f}s"
+
+ minutes = int(seconds // 60)
+ remaining_seconds = int(seconds % 60)
+
+ if minutes < 60:
+ if remaining_seconds:
+ return f"{minutes}m {remaining_seconds}s"
+ return f"{minutes}m"
+
+ hours = minutes // 60
+ remaining_minutes = minutes % 60
+
+ if remaining_minutes:
+ return f"{hours}h {remaining_minutes}m"
+ return f"{hours}h"
+
+
+def format_count(count: int) -> str:
+ """
+ Format a count with abbreviation for large numbers.
+
+ Args:
+ count: Number to format
+
+ Returns:
+ Formatted string (e.g., "1.2K", "3.5M")
+ """
+ if count < 1000:
+ return str(count)
+ if count < 1000000:
+ return f"{count / 1000:.1f}K"
+ if count < 1000000000:
+ return f"{count / 1000000:.1f}M"
+ return f"{count / 1000000000:.1f}B"
+
+
+def format_percentage(value: float, decimals: int = 1) -> str:
+ """
+ Format a percentage value.
+
+ Args:
+ value: Percentage value (0-100 or 0-1)
+ decimals: Number of decimal places
+
+ Returns:
+ Formatted percentage string
+ """
+ # Assume 0-1 if less than 1
+ if value <= 1:
+ value *= 100
+
+ if decimals == 0:
+ return f"{int(value)}%"
+ return f"{value:.{decimals}f}%"
diff --git a/common/artdag_common/utils/media.py b/common/artdag_common/utils/media.py
new file mode 100644
index 0000000..ef0eaee
--- /dev/null
+++ b/common/artdag_common/utils/media.py
@@ -0,0 +1,166 @@
+"""
+Media type detection and handling utilities.
+"""
+
+from pathlib import Path
+from typing import Optional
+import mimetypes
+
+# Initialize mimetypes database
+mimetypes.init()
+
+# Media type categories
+VIDEO_TYPES = {"video/mp4", "video/webm", "video/quicktime", "video/x-msvideo", "video/avi"}
+IMAGE_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml"}
+AUDIO_TYPES = {"audio/mpeg", "audio/wav", "audio/ogg", "audio/flac", "audio/aac", "audio/mp3"}
+
+# File extension mappings
+EXTENSION_TO_CATEGORY = {
+ # Video
+ ".mp4": "video",
+ ".webm": "video",
+ ".mov": "video",
+ ".avi": "video",
+ ".mkv": "video",
+ # Image
+ ".jpg": "image",
+ ".jpeg": "image",
+ ".png": "image",
+ ".gif": "image",
+ ".webp": "image",
+ ".svg": "image",
+ # Audio
+ ".mp3": "audio",
+ ".wav": "audio",
+ ".ogg": "audio",
+ ".flac": "audio",
+ ".aac": "audio",
+ ".m4a": "audio",
+}
+
+
+def detect_media_type(path: Path) -> str:
+ """
+ Detect the media category for a file.
+
+ Args:
+ path: Path to the file
+
+ Returns:
+ Category string: "video", "image", "audio", or "unknown"
+ """
+ if not path:
+ return "unknown"
+
+ # Try extension first
+ ext = path.suffix.lower()
+ if ext in EXTENSION_TO_CATEGORY:
+ return EXTENSION_TO_CATEGORY[ext]
+
+ # Try mimetypes
+ mime_type, _ = mimetypes.guess_type(str(path))
+ if mime_type:
+ if mime_type in VIDEO_TYPES or mime_type.startswith("video/"):
+ return "video"
+ if mime_type in IMAGE_TYPES or mime_type.startswith("image/"):
+ return "image"
+ if mime_type in AUDIO_TYPES or mime_type.startswith("audio/"):
+ return "audio"
+
+ return "unknown"
+
+
+def get_mime_type(path: Path) -> str:
+ """
+ Get the MIME type for a file.
+
+ Args:
+ path: Path to the file
+
+ Returns:
+ MIME type string or "application/octet-stream"
+ """
+ mime_type, _ = mimetypes.guess_type(str(path))
+ return mime_type or "application/octet-stream"
+
+
+def get_media_extension(media_type: str) -> str:
+ """
+ Get the typical file extension for a media type.
+
+ Args:
+ media_type: Media category or MIME type
+
+ Returns:
+ File extension with dot (e.g., ".mp4")
+ """
+ if media_type == "video":
+ return ".mp4"
+ if media_type == "image":
+ return ".png"
+ if media_type == "audio":
+ return ".mp3"
+
+ # Try as MIME type
+ ext = mimetypes.guess_extension(media_type)
+ return ext or ""
+
+
+def is_streamable(path: Path) -> bool:
+ """
+ Check if a file type is streamable (video/audio).
+
+ Args:
+ path: Path to the file
+
+ Returns:
+ True if the file can be streamed
+ """
+ media_type = detect_media_type(path)
+ return media_type in ("video", "audio")
+
+
+def needs_conversion(path: Path, target_format: str = "mp4") -> bool:
+ """
+ Check if a video file needs format conversion.
+
+ Args:
+ path: Path to the file
+ target_format: Target format (default mp4)
+
+ Returns:
+ True if conversion is needed
+ """
+ media_type = detect_media_type(path)
+ if media_type != "video":
+ return False
+
+ ext = path.suffix.lower().lstrip(".")
+ return ext != target_format
+
+
+def get_video_src(
+ content_hash: str,
+ original_path: Optional[Path] = None,
+ is_ios: bool = False,
+) -> str:
+ """
+ Get the appropriate video source URL.
+
+ For iOS devices, prefer MP4 format.
+
+ Args:
+ content_hash: Content hash for the video
+ original_path: Optional original file path
+ is_ios: Whether the client is iOS
+
+ Returns:
+ URL path for the video source
+ """
+ if is_ios:
+ return f"/cache/{content_hash}/mp4"
+
+ if original_path and original_path.suffix.lower() in (".mp4", ".webm"):
+ return f"/cache/{content_hash}/raw"
+
+ return f"/cache/{content_hash}/mp4"
diff --git a/common/artdag_common/utils/pagination.py b/common/artdag_common/utils/pagination.py
new file mode 100644
index 0000000..f892f95
--- /dev/null
+++ b/common/artdag_common/utils/pagination.py
@@ -0,0 +1,85 @@
+"""
+Pagination utilities.
+"""
+
+from typing import List, Any, Tuple, Optional
+
+from fastapi import Request
+
+from ..constants import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+
+
+def get_pagination_params(request: Request) -> Tuple[int, int]:
+ """
+ Extract pagination parameters from request query string.
+
+ Args:
+ request: FastAPI request
+
+ Returns:
+ Tuple of (page, limit)
+ """
+ try:
+ page = int(request.query_params.get("page", 1))
+ page = max(1, page)
+ except ValueError:
+ page = 1
+
+ try:
+ limit = int(request.query_params.get("limit", DEFAULT_PAGE_SIZE))
+ limit = max(1, min(limit, MAX_PAGE_SIZE))
+ except ValueError:
+ limit = DEFAULT_PAGE_SIZE
+
+ return page, limit
+
+
+def paginate(
+ items: List[Any],
+ page: int = 1,
+ limit: int = DEFAULT_PAGE_SIZE,
+) -> Tuple[List[Any], dict]:
+ """
+ Paginate a list of items.
+
+ Args:
+ items: Full list of items
+ page: Page number (1-indexed)
+ limit: Items per page
+
+ Returns:
+ Tuple of (paginated items, pagination info dict)
+ """
+ total = len(items)
+ start = (page - 1) * limit
+ end = start + limit
+
+ paginated = items[start:end]
+
+ return paginated, {
+ "page": page,
+ "limit": limit,
+ "total": total,
+ "has_more": end < total,
+ "total_pages": (total + limit - 1) // limit if total > 0 else 1,
+ }
+
+
+def calculate_offset(page: int, limit: int) -> int:
+ """Calculate database offset from page and limit."""
+ return (page - 1) * limit
+
+
+def build_pagination_info(
+ page: int,
+ limit: int,
+ total: int,
+) -> dict:
+ """Build pagination info dictionary."""
+ return {
+ "page": page,
+ "limit": limit,
+ "total": total,
+ "has_more": page * limit < total,
+ "total_pages": (total + limit - 1) // limit if total > 0 else 1,
+ }
diff --git a/common/pyproject.toml b/common/pyproject.toml
new file mode 100644
index 0000000..8205b9b
--- /dev/null
+++ b/common/pyproject.toml
@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "artdag-common"
+version = "0.1.3"
+description = "Shared components for Art-DAG L1 and L2 servers"
+requires-python = ">=3.10"
+dependencies = [
+ "fastapi>=0.100.0",
+ "jinja2>=3.1.0",
+ "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+ "pytest>=7.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["artdag_common"]