vcursor-cli 1.0.0__py3-none-any.whl

vcursor/__init__.py

@@ -0,0 +1,25 @@
+"""VCursor SDK - Generate videos from text, images, and URLs using AI."""
+
+from vcursor.client import VCursor, VCursorAsync
+from vcursor.types import (
+    SubmitRequest,
+    SubmitResponse,
+    TaskProgress,
+    AgentSubmitRequest,
+    AgentProgress,
+    CategoryUsage,
+    ConcurrencyStatus,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "VCursor",
+    "VCursorAsync",
+    "SubmitRequest",
+    "SubmitResponse",
+    "TaskProgress",
+    "AgentSubmitRequest",
+    "AgentProgress",
+    "CategoryUsage",
+    "ConcurrencyStatus",
+]

vcursor/cli.py

@@ -0,0 +1,322 @@
+"""VCursor CLI - Python entry point.
+
+Provides the same core commands as the Node.js CLI:
+  vcursor "a cat playing piano"
+  vcursor --agent "create a commercial"
+  vcursor login
+  vcursor whoami
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+from vcursor.client import VCursor, VCursorError, ConcurrencyLimitError, _load_config, DEFAULT_SERVER
+
+CONFIG_DIR = Path.home() / ".vcursor"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def _save_config(config: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(config, indent=2) + "\n")
+    CONFIG_FILE.chmod(0o600)
+
+
+def _resolve_server(args: argparse.Namespace) -> str:
+    return getattr(args, "server", None) or os.environ.get("VCURSOR_SERVER") or _load_config().get("server") or DEFAULT_SERVER
+
+
+def _resolve_api_key(args: argparse.Namespace) -> str | None:
+    return getattr(args, "api_key", None) or os.environ.get("VCURSOR_API_KEY") or _load_config().get("apiKey")
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def cmd_login(args: argparse.Namespace) -> None:
+    server = _resolve_server(args)
+    api_key = getattr(args, "api_key", None)
+    if not api_key:
+        print(f"Server: {server}")
+        api_key = getpass.getpass("API Key: ")
+    if not api_key:
+        print("No API key provided.")
+        sys.exit(1)
+
+    # Validate
+    import httpx
+    try:
+        resp = httpx.post(
+            f"{server.rstrip('/')}/api/cli/validate",
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            json={},
+            timeout=15,
+        )
+        if resp.status_code != 200:
+            print(f"Validation failed: {resp.text}")
+            sys.exit(1)
+    except Exception as e:
+        print(f"Connection error: {e}")
+        sys.exit(1)
+
+    config = _load_config()
+    config["server"] = server
+    config["apiKey"] = api_key
+    _save_config(config)
+    print("Logged in successfully.")
+
+
+def cmd_logout(_args: argparse.Namespace) -> None:
+    config = _load_config()
+    config.pop("apiKey", None)
+    _save_config(config)
+    print("Logged out.")
+
+
+def cmd_whoami(args: argparse.Namespace) -> None:
+    server = _resolve_server(args)
+    api_key = _resolve_api_key(args)
+    if not api_key:
+        print("Not authenticated. Run: vcursor login")
+        sys.exit(1)
+
+    import httpx
+    try:
+        resp = httpx.post(
+            f"{server.rstrip('/')}/api/cli/validate",
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            json={},
+            timeout=15,
+        )
+        data = resp.json()
+        if resp.status_code == 200:
+            print(f"Authenticated as: {data.get('email', data.get('name', 'unknown'))}")
+            print(f"Server: {server}")
+        else:
+            print(f"Auth failed: {data.get('message', resp.status_code)}")
+    except Exception as e:
+        print(f"Connection error: {e}")
+        sys.exit(1)
+
+
+def cmd_generate(args: argparse.Namespace) -> None:
+    api_key = _resolve_api_key(args)
+    if not api_key:
+        print("Not authenticated. Run: vcursor login")
+        sys.exit(1)
+
+    prompt = " ".join(args.inputs)
+    if not prompt:
+        print("No prompt provided.")
+        sys.exit(1)
+
+    max_conc = int(args.max_concurrency) if args.max_concurrency else None
+    client = VCursor(
+        api_key=api_key,
+        server=_resolve_server(args),
+        max_concurrency=max_conc,
+    )
+
+    try:
+        if args.agent:
+            _run_agent(client, prompt, args)
+        else:
+            _run_standard(client, prompt, args)
+    except ConcurrencyLimitError as e:
+        window_label = "" if e.tier == "free" else "/hr"
+        print(f"Rate limit reached: {e.used}/{e.rate_limit} {e.category} requests{window_label} (tier: {e.tier})")
+        if e.tier == "free":
+            print("Upgrade your plan to get more requests.")
+        else:
+            print("Wait for your quota to reset, then try again.")
+        sys.exit(1)
+    except VCursorError as e:
+        print(f"Error ({e.status}): {e}")
+        sys.exit(1)
+    finally:
+        client.close()
+
+
+def _run_standard(client: VCursor, prompt: str, args: argparse.Namespace) -> None:
+    print(f"Submitting: {prompt[:120]}{'...' if len(prompt) > 120 else ''}")
+
+    kwargs = {}
+    if args.mode:
+        kwargs["submission_mode"] = args.mode
+
+    resp = client.submit(prompt, **kwargs)
+
+    if resp.chat_response:
+        print(f"\n{resp.chat_response}")
+        return
+    if resp.plan:
+        print(f"\nPlan:\n{resp.plan}")
+        return
+    if not resp.task_id:
+        print("No task ID returned.")
+        sys.exit(1)
+
+    print(f"Task: {resp.task_id} (mode: {resp.mode or 'auto'})")
+
+    def _on_progress(p):
+        d = p.data
+        bar_len = 30
+        filled = int(bar_len * d.progress / 100)
+        bar = "█" * filled + "░" * (bar_len - filled)
+        eta = f" ~{int(d.remaining_process_time)}s" if d.remaining_process_time > 0 else ""
+        print(f"\r  [{bar}] {d.progress:.0f}% {d.status}{eta}  ", end="", flush=True)
+
+    result = client.wait_for_completion(resp.task_id, on_progress=_on_progress)
+    print()
+
+    if result.data.status == "completed":
+        print("Completed!")
+        if result.data.products.url:
+            print(f"  Output: {result.data.products.url}")
+        if result.data.products.audio_url:
+            print(f"  Audio:  {result.data.products.audio_url}")
+        if result.data.products.refined_prompt:
+            print(f"  Refined: {result.data.products.refined_prompt}")
+    else:
+        print(f"Task failed: {result.data.detail or result.data.status}")
+        sys.exit(1)
+
+    if args.json:
+        print(json.dumps({"code": result.code, "data": {"status": result.data.status}}, indent=2))
+
+
+def _run_agent(client: VCursor, prompt: str, args: argparse.Namespace) -> None:
+    print(f"Submitting agent task: {prompt[:120]}{'...' if len(prompt) > 120 else ''}")
+
+    resp = client.submit_agent(prompt)
+    task_id = resp.get("task_id")
+    if not task_id:
+        print("No task ID returned.")
+        sys.exit(1)
+
+    print(f"Agent task: {task_id}")
+
+    def _on_progress(p):
+        bar_len = 30
+        filled = int(bar_len * p.progress / 100)
+        bar = "█" * filled + "░" * (bar_len - filled)
+        stage = p.current_stage or p.status
+        print(f"\r  [{bar}] {p.progress:.0f}% {stage}  ", end="", flush=True)
+
+    result = client.wait_for_agent_completion(task_id, on_progress=_on_progress)
+    print()
+
+    if result.status == "completed":
+        print("Agent task completed!")
+        if result.video_url:
+            print(f"  Video:  {result.video_url}")
+        if result.assets_url:
+            print(f"  Assets: {result.assets_url}")
+    else:
+        print(f"Agent task failed: {result.error_message or result.status}")
+        sys.exit(1)
+
+
+def cmd_concurrency(args: argparse.Namespace) -> None:
+    """Show current concurrency status."""
+    api_key = _resolve_api_key(args)
+    if not api_key:
+        print("Not authenticated. Run: vcursor login")
+        sys.exit(1)
+
+    client = VCursor(api_key=api_key, server=_resolve_server(args))
+    try:
+        status = client.check_concurrency()
+        window_label = "lifetime" if status.tier == "free" else f"{status.window_hours}h window"
+        print(f"Tier:      {status.tier} ({window_label})")
+        if status.summary:
+            s = status.summary["standard"]
+            a = status.summary["agent"]
+            print(f"Standard:  {s.used}/{s.limit} used, {s.remaining} remaining")
+            print(f"Agent:     {a.used}/{a.limit} used, {a.remaining} remaining")
+        if status.bypass_enabled:
+            print("Bypass:    enabled (admin/test)")
+    except VCursorError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="vcursor",
+        description="VCursor CLI - Generate videos from text, images, and URLs using AI",
+    )
+    parser.add_argument("-v", "--version", action="version", version="vcursor 1.0.0")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # login
+    login_p = sub.add_parser("login", help="Authenticate with your VCursor API key")
+    login_p.add_argument("--server", help="Server URL")
+    login_p.add_argument("--api-key", help="API key (non-interactive)")
+
+    # logout
+    sub.add_parser("logout", help="Remove stored API key")
+
+    # whoami
+    whoami_p = sub.add_parser("whoami", help="Show current authenticated user")
+    whoami_p.add_argument("--server", help="Server URL")
+
+    # concurrency
+    conc_p = sub.add_parser("concurrency", help="Show concurrency limit status")
+    conc_p.add_argument("--server", help="Server URL")
+    conc_p.add_argument("--api-key", help="API key")
+
+    # generate (default)
+    gen_p = sub.add_parser("generate", help="Generate video from prompt")
+    gen_p.add_argument("inputs", nargs="+", help="Text prompt, file paths, or URLs")
+    gen_p.add_argument("--agent", action="store_true", help="Use agent mode")
+    gen_p.add_argument("--mode", help="Force a specific mode")
+    gen_p.add_argument("--max-concurrency", help="Max concurrent tasks (client-side)")
+    gen_p.add_argument("--server", help="Server URL")
+    gen_p.add_argument("--api-key", help="API key")
+    gen_p.add_argument("--json", action="store_true", help="Output raw JSON")
+
+    args = parser.parse_args()
+
+    # If no subcommand but there are remaining args, treat as generate
+    if args.command is None:
+        # Re-parse with generate as implicit default
+        remaining = sys.argv[1:]
+        if remaining and not remaining[0].startswith("-"):
+            gen_args = gen_p.parse_args(remaining)
+            cmd_generate(gen_args)
+            return
+        parser.print_help()
+        return
+
+    if args.command == "login":
+        cmd_login(args)
+    elif args.command == "logout":
+        cmd_logout(args)
+    elif args.command == "whoami":
+        cmd_whoami(args)
+    elif args.command == "concurrency":
+        cmd_concurrency(args)
+    elif args.command == "generate":
+        cmd_generate(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

vcursor/client.py

@@ -0,0 +1,372 @@
+"""VCursor API client for Python - sync and async."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+from vcursor.types import (
+    AgentProgress,
+    AgentSubmitRequest,
+    ConcurrencyStatus,
+    SubmitRequest,
+    SubmitResponse,
+    TaskProgress,
+)
+
+DEFAULT_SERVER = "https://www.cli.vcursor.com"
+CONFIG_PATH = Path.home() / ".vcursor" / "config.json"
+
+
+class VCursorError(Exception):
+    """Error returned by the VCursor API."""
+
+    def __init__(self, message: str, status: int, data: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.status = status
+        self.data = data
+
+
+class ConcurrencyLimitError(VCursorError):
+    """Raised when the user has exceeded their concurrency limit."""
+
+    def __init__(self, message: str, data: dict[str, Any] | None = None):
+        super().__init__(message, 429, data)
+        self.used: int = (data or {}).get("used", 0)
+        self.rate_limit: int = (data or {}).get("rateLimit", 0)
+        self.category: str = (data or {}).get("category", "standard")
+        self.tier: str = (data or {}).get("tier", "free")
+
+
+def _load_config() -> dict[str, Any]:
+    """Load config from ~/.vcursor/config.json."""
+    try:
+        return json.loads(CONFIG_PATH.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def _resolve_server(server: str | None = None) -> str:
+    return server or os.environ.get("VCURSOR_SERVER") or _load_config().get("server") or DEFAULT_SERVER
+
+
+def _resolve_api_key(api_key: str | None = None) -> str | None:
+    return api_key or os.environ.get("VCURSOR_API_KEY") or _load_config().get("apiKey")
+
+
+# ---------------------------------------------------------------------------
+# Synchronous client
+# ---------------------------------------------------------------------------
+
+class VCursor:
+    """Synchronous VCursor API client.
+
+    Usage::
+
+        from vcursor import VCursor
+
+        client = VCursor(api_key="vk-...")
+        resp = client.submit("a cat playing piano")
+        result = client.wait_for_completion(resp.task_id)
+        print(result.data.products.url)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        server: str | None = None,
+        max_concurrency: int | None = None,
+        timeout: float = 60.0,
+    ):
+        self.server = _resolve_server(server).rstrip("/")
+        self.api_key = _resolve_api_key(api_key)
+        self.max_concurrency = max_concurrency
+        self._client = httpx.Client(timeout=timeout)
+
+    def _headers(self) -> dict[str, str]:
+        h: dict[str, str] = {"Content-Type": "application/json"}
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    def _request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
+        url = f"{self.server}{path}"
+        resp = self._client.request(method, url, headers=self._headers(), json=body)
+        data = resp.json()
+        if not resp.is_success:
+            msg = data.get("message") or data.get("error") or f"HTTP {resp.status_code}"
+            if resp.status_code == 429:
+                raise ConcurrencyLimitError(msg, data)
+            raise VCursorError(msg, resp.status_code, data)
+        return data
+
+    # --- Concurrency ---
+
+    def check_concurrency(self, category: str = "standard") -> ConcurrencyStatus:
+        """Check current rate limit usage and limits.
+
+        Args:
+            category: 'standard' or 'agent'.
+        """
+        data = self._request("POST", "/api/concurrency/check", {"category": category})
+        return ConcurrencyStatus.from_dict(data)
+
+    def _enforce_concurrency(self, category: str = "standard") -> None:
+        """Pre-flight rate limit guard. Raises ConcurrencyLimitError if over limit."""
+        status = self.check_concurrency(category)
+        effective_limit = self.max_concurrency if self.max_concurrency is not None else status.limit
+        if not status.bypass_enabled and status.used >= effective_limit:
+            window_label = "" if status.tier == "free" else "/hr"
+            raise ConcurrencyLimitError(
+                f"Rate limit reached: {status.used}/{effective_limit} {category} requests{window_label}",
+                {
+                    "used": status.used,
+                    "rateLimit": effective_limit,
+                    "category": category,
+                    "tier": status.tier,
+                },
+            )
+
+    # --- Standard mode ---
+
+    def submit(self, prompt: str, **kwargs: Any) -> SubmitResponse:
+        """Submit a standard video generation task.
+
+        Args:
+            prompt: Text prompt.
+            **kwargs: Additional fields for SubmitRequest (media_keys, reference_urls, etc.).
+
+        Returns:
+            SubmitResponse with task_id for polling.
+        """
+        self._enforce_concurrency("standard")
+        req = SubmitRequest(prompt=prompt, **kwargs)
+        data = self._request("POST", "/api/task/submit_anything", req.to_dict())
+        return SubmitResponse.from_dict(data)
+
+    def get_progress(self, task_id: str) -> TaskProgress:
+        """Get progress for a standard task."""
+        data = self._request("GET", f"/api/task/progress/{task_id}")
+        return TaskProgress.from_dict(data)
+
+    def cancel_task(self, task_id: str) -> dict[str, str]:
+        """Cancel a running task."""
+        return self._request("GET", f"/api/task/abort/{task_id}")
+
+    def wait_for_completion(
+        self,
+        task_id: str,
+        poll_interval: float = 2.0,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+    ) -> TaskProgress:
+        """Poll until a standard task completes or fails.
+
+        Args:
+            task_id: Task ID to poll.
+            poll_interval: Seconds between polls.
+            on_progress: Optional callback invoked on each poll.
+
+        Returns:
+            Final TaskProgress.
+        """
+        while True:
+            progress = self.get_progress(task_id)
+            if on_progress:
+                on_progress(progress)
+            if progress.data.status in ("completed", "failed"):
+                return progress
+            time.sleep(poll_interval)
+
+    # --- Agent mode ---
+
+    def submit_agent(self, message: str, **kwargs: Any) -> dict[str, str]:
+        """Submit an agent mode task.
+
+        Args:
+            message: Agent prompt.
+            **kwargs: Additional fields for AgentSubmitRequest.
+
+        Returns:
+            Dict with task_id and status.
+        """
+        self._enforce_concurrency("agent")
+        req = AgentSubmitRequest(message=message, **kwargs)
+        return self._request("POST", "/api/direct/submit", req.to_dict())
+
+    def get_agent_progress(self, task_id: str) -> AgentProgress:
+        """Get progress for an agent task."""
+        data = self._request("GET", f"/api/direct/progress/{task_id}")
+        return AgentProgress.from_dict(data)
+
+    def cancel_agent_task(self, task_id: str) -> dict[str, str]:
+        """Cancel an agent task."""
+        return self._request("DELETE", f"/api/direct/cancel/{task_id}")
+
+    def wait_for_agent_completion(
+        self,
+        task_id: str,
+        poll_interval: float = 3.0,
+        on_progress: Callable[[AgentProgress], None] | None = None,
+    ) -> AgentProgress:
+        """Poll until an agent task completes or fails."""
+        while True:
+            progress = self.get_agent_progress(task_id)
+            if on_progress:
+                on_progress(progress)
+            if progress.status in ("completed", "error"):
+                return progress
+            time.sleep(poll_interval)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> VCursor:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+class VCursorAsync:
+    """Async VCursor API client.
+
+    Usage::
+
+        import asyncio
+        from vcursor import VCursorAsync
+
+        async def main():
+            async with VCursorAsync(api_key="vk-...") as client:
+                resp = await client.submit("a cat playing piano")
+                result = await client.wait_for_completion(resp.task_id)
+                print(result.data.products.url)
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        server: str | None = None,
+        max_concurrency: int | None = None,
+        timeout: float = 60.0,
+    ):
+        self.server = _resolve_server(server).rstrip("/")
+        self.api_key = _resolve_api_key(api_key)
+        self.max_concurrency = max_concurrency
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    def _headers(self) -> dict[str, str]:
+        h: dict[str, str] = {"Content-Type": "application/json"}
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    async def _request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
+        url = f"{self.server}{path}"
+        resp = await self._client.request(method, url, headers=self._headers(), json=body)
+        data = resp.json()
+        if not resp.is_success:
+            msg = data.get("message") or data.get("error") or f"HTTP {resp.status_code}"
+            if resp.status_code == 429:
+                raise ConcurrencyLimitError(msg, data)
+            raise VCursorError(msg, resp.status_code, data)
+        return data
+
+    # --- Concurrency ---
+
+    async def check_concurrency(self, category: str = "standard") -> ConcurrencyStatus:
+        data = await self._request("POST", "/api/concurrency/check", {"category": category})
+        return ConcurrencyStatus.from_dict(data)
+
+    async def _enforce_concurrency(self, category: str = "standard") -> None:
+        status = await self.check_concurrency(category)
+        effective_limit = self.max_concurrency if self.max_concurrency is not None else status.limit
+        if not status.bypass_enabled and status.used >= effective_limit:
+            window_label = "" if status.tier == "free" else "/hr"
+            raise ConcurrencyLimitError(
+                f"Rate limit reached: {status.used}/{effective_limit} {category} requests{window_label}",
+                {
+                    "used": status.used,
+                    "rateLimit": effective_limit,
+                    "category": category,
+                    "tier": status.tier,
+                },
+            )
+
+    # --- Standard mode ---
+
+    async def submit(self, prompt: str, **kwargs: Any) -> SubmitResponse:
+        await self._enforce_concurrency("standard")
+        req = SubmitRequest(prompt=prompt, **kwargs)
+        data = await self._request("POST", "/api/task/submit_anything", req.to_dict())
+        return SubmitResponse.from_dict(data)
+
+    async def get_progress(self, task_id: str) -> TaskProgress:
+        data = await self._request("GET", f"/api/task/progress/{task_id}")
+        return TaskProgress.from_dict(data)
+
+    async def cancel_task(self, task_id: str) -> dict[str, str]:
+        return await self._request("GET", f"/api/task/abort/{task_id}")
+
+    async def wait_for_completion(
+        self,
+        task_id: str,
+        poll_interval: float = 2.0,
+        on_progress: Callable[[TaskProgress], None] | None = None,
+    ) -> TaskProgress:
+        import asyncio
+        while True:
+            progress = await self.get_progress(task_id)
+            if on_progress:
+                on_progress(progress)
+            if progress.data.status in ("completed", "failed"):
+                return progress
+            await asyncio.sleep(poll_interval)
+
+    # --- Agent mode ---
+
+    async def submit_agent(self, message: str, **kwargs: Any) -> dict[str, str]:
+        await self._enforce_concurrency("agent")
+        req = AgentSubmitRequest(message=message, **kwargs)
+        return await self._request("POST", "/api/direct/submit", req.to_dict())
+
+    async def get_agent_progress(self, task_id: str) -> AgentProgress:
+        data = await self._request("GET", f"/api/direct/progress/{task_id}")
+        return AgentProgress.from_dict(data)
+
+    async def cancel_agent_task(self, task_id: str) -> dict[str, str]:
+        return await self._request("DELETE", f"/api/direct/cancel/{task_id}")
+
+    async def wait_for_agent_completion(
+        self,
+        task_id: str,
+        poll_interval: float = 3.0,
+        on_progress: Callable[[AgentProgress], None] | None = None,
+    ) -> AgentProgress:
+        import asyncio
+        while True:
+            progress = await self.get_agent_progress(task_id)
+            if on_progress:
+                on_progress(progress)
+            if progress.status in ("completed", "error"):
+                return progress
+            await asyncio.sleep(poll_interval)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> VCursorAsync:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

vcursor/types.py

@@ -0,0 +1,222 @@
+"""Type definitions for the VCursor SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class SubmitRequest:
+    """Request to submit a standard video generation task."""
+    prompt: str
+    media_keys: list[str] | None = None
+    reference_urls: list[str] | None = None
+    submission_mode: str | None = None  # 'plan' | 'execute' | 'ask'
+    plan_id: str | None = None
+    plan_data: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"prompt": self.prompt}
+        if self.media_keys:
+            d["media_keys"] = self.media_keys
+        if self.reference_urls:
+            d["reference_urls"] = self.reference_urls
+        if self.submission_mode:
+            d["submission_mode"] = self.submission_mode
+        if self.plan_id:
+            d["plan_id"] = self.plan_id
+        if self.plan_data:
+            d["plan_data"] = self.plan_data
+        return d
+
+
+@dataclass
+class SubmitResponse:
+    """Response from task submission."""
+    code: int
+    message: str
+    task_id: str | None = None
+    mode: str | None = None
+    chat_response: str | None = None
+    plan: str | None = None
+    plan_id: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SubmitResponse:
+        return cls(
+            code=data.get("code", 0),
+            message=data.get("message", ""),
+            task_id=data.get("task_id"),
+            mode=data.get("mode"),
+            chat_response=data.get("chat_response"),
+            plan=data.get("plan"),
+            plan_id=data.get("plan_id"),
+        )
+
+
+@dataclass
+class TaskProducts:
+    """Products from a completed task."""
+    url: str | None = None
+    thumbnail_url: str | None = None
+    audio_url: str | None = None
+    upload_completed: bool = False
+    refined_prompt: str | None = None
+    aspect_ratio: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TaskProducts:
+        return cls(
+            url=data.get("url"),
+            thumbnail_url=data.get("thumbnail_url"),
+            audio_url=data.get("audio_url"),
+            upload_completed=data.get("upload_completed", False),
+            refined_prompt=data.get("refined_prompt"),
+            aspect_ratio=data.get("aspect_ratio"),
+        )
+
+
+@dataclass
+class TaskProgressData:
+    """Inner data of task progress."""
+    task_id: str
+    status: str  # 'pending' | 'processing' | 'completed' | 'failed' | 'temporal_error'
+    progress: float = 0.0
+    queuing_time: float = 0.0
+    remaining_process_time: float = 0.0
+    total_process_time: float = 0.0
+    products: TaskProducts = field(default_factory=TaskProducts)
+    detail: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TaskProgressData:
+        return cls(
+            task_id=data.get("task_id", ""),
+            status=data.get("status", "pending"),
+            progress=data.get("progress", 0.0),
+            queuing_time=data.get("queuing_time", 0.0),
+            remaining_process_time=data.get("remaining_process_time", 0.0),
+            total_process_time=data.get("total_process_time", 0.0),
+            products=TaskProducts.from_dict(data.get("products", {})),
+            detail=data.get("detail"),
+        )
+
+
+@dataclass
+class TaskProgress:
+    """Full task progress response."""
+    code: int
+    message: str
+    data: TaskProgressData = field(default_factory=lambda: TaskProgressData(task_id="", status="pending"))
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> TaskProgress:
+        return cls(
+            code=raw.get("code", 0),
+            message=raw.get("message", ""),
+            data=TaskProgressData.from_dict(raw.get("data", {})),
+        )
+
+
+@dataclass
+class AgentSubmitRequest:
+    """Request to submit an agent mode task."""
+    message: str
+    duration: str | None = None
+    aspect_ratio: str | None = None
+    model_name: str | None = None
+    voiceover: str | None = None
+    subtitles: str | None = None
+    bgm: str | None = None
+    sound_effects: str | None = None
+    visual_style: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"message": self.message}
+        for key in ("duration", "aspect_ratio", "model_name", "voiceover",
+                     "subtitles", "bgm", "sound_effects", "visual_style"):
+            val = getattr(self, key)
+            if val is not None:
+                d[key] = val
+        return d
+
+
+@dataclass
+class AgentProgress:
+    """Agent task progress."""
+    task_id: str
+    status: str  # 'pending' | 'processing' | 'completed' | 'error'
+    progress: float = 0.0
+    current_stage: str | None = None
+    estimated_time_remaining: float | None = None
+    video_url: str | None = None
+    assets_url: str | None = None
+    error_message: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentProgress:
+        return cls(
+            task_id=data.get("task_id", ""),
+            status=data.get("status", "pending"),
+            progress=data.get("progress", 0.0),
+            current_stage=data.get("current_stage"),
+            estimated_time_remaining=data.get("estimated_time_remaining"),
+            video_url=data.get("video_url"),
+            assets_url=data.get("assets_url"),
+            error_message=data.get("error_message"),
+        )
+
+
+@dataclass
+class CategoryUsage:
+    """Usage for a single task category (standard or agent)."""
+    used: int
+    limit: int | float
+    remaining: int | float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CategoryUsage:
+        return cls(
+            used=data.get("used", 0),
+            limit=data.get("limit", 0),
+            remaining=data.get("remaining", 0),
+        )
+
+
+@dataclass
+class ConcurrencyStatus:
+    """Rate limit status for the current user.
+
+    Includes separate quotas for standard and agent requests.
+    """
+    allowed: bool
+    limit: int | float
+    used: int
+    remaining: int | float
+    category: str  # 'standard' | 'agent'
+    tier: str
+    bypass_enabled: bool = False
+    window_hours: int = 1
+    reset_at: str | None = None
+    summary: dict[str, CategoryUsage] | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ConcurrencyStatus:
+        summary_raw = data.get("summary", {})
+        summary = {
+            "standard": CategoryUsage.from_dict(summary_raw.get("standard", {})),
+            "agent": CategoryUsage.from_dict(summary_raw.get("agent", {})),
+        } if summary_raw else None
+        return cls(
+            allowed=data.get("allowed", False),
+            limit=data.get("limit", 0),
+            used=data.get("used", 0),
+            remaining=data.get("remaining", 0),
+            category=data.get("category", "standard"),
+            tier=data.get("tier", "free"),
+            bypass_enabled=data.get("bypassEnabled", False),
+            window_hours=data.get("windowHours", 1),
+            reset_at=data.get("resetAt"),
+            summary=summary,
+        )

vcursor_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: vcursor-cli
+Version: 1.0.0
+Summary: VCursor SDK & CLI - Generate videos from text, images, and URLs using AI
+Author-email: Julius <support@vcursor.com>
+License: MIT
+Project-URL: Homepage, https://cli.vcursor.com
+Project-URL: Repository, https://github.com/JThh/vcursor
+Project-URL: Documentation, https://cli.vcursor.com/docs
+Keywords: video,ai,generation,cli,vcursor,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# VCursor Python SDK & CLI
+
+Generate videos from text, images, and URLs using AI.
+
+## Installation
+
+```bash
+pip install vcursor
+```
+
+## Quick Start
+
+### As a library (embedded in code)
+
+```python
+from vcursor import VCursor
+
+client = VCursor(api_key="vk-...")
+
+# Submit a video generation task
+resp = client.submit("a cat playing piano in a jazz club")
+
+# Wait for completion with progress callback
+result = client.wait_for_completion(
+    resp.task_id,
+    on_progress=lambda p: print(f"{p.data.progress}%")
+)
+
+print(result.data.products.url)
+```
+
+### Async usage
+
+```python
+import asyncio
+from vcursor import VCursorAsync
+
+async def main():
+    async with VCursorAsync(api_key="vk-...") as client:
+        resp = await client.submit("sunset timelapse over mountains")
+        result = await client.wait_for_completion(resp.task_id)
+        print(result.data.products.url)
+
+asyncio.run(main())
+```
+
+### Concurrency limiting
+
+The server enforces per-user rate limits based on subscription tier:
+
+| Tier | Standard Requests | Agent Requests | Window    |
+|------|-------------------|----------------|-----------|
+| Free | 3                 | 1              | Lifetime  |
+| Pro  | 30/hr             | 5/hr           | Rolling 1h|
+| Plus | 120/hr            | 15/hr          | Rolling 1h|
+
+```python
+# Check current rate limit status
+status = client.check_concurrency("standard")
+print(f"Standard: {status.summary['standard'].used}/{status.summary['standard'].limit}")
+print(f"Agent:    {status.summary['agent'].used}/{status.summary['agent'].limit}")
+
+# Client-side limit (capped at server limit)
+client = VCursor(api_key="vk-...", max_concurrency=10)
+```
+
+### As a CLI
+
+```bash
+# Authenticate
+vcursor login
+
+# Generate a video
+vcursor generate "a cat playing piano"
+
+# Agent mode
+vcursor generate --agent "create a 30s commercial"
+
+# Check concurrency status
+vcursor concurrency
+
+# With concurrency limit
+vcursor generate --max-concurrency 2 "sunset timelapse"
+```
+
+## API Reference
+
+### `VCursor` / `VCursorAsync`
+
+| Method                    | Description                            |
+|---------------------------|----------------------------------------|
+| `submit(prompt, **kw)`   | Submit a standard video generation task |
+| `get_progress(task_id)`  | Get task progress                      |
+| `wait_for_completion()`  | Poll until task completes              |
+| `cancel_task(task_id)`   | Cancel a running task                  |
+| `submit_agent(message)`  | Submit an agent mode task              |
+| `get_agent_progress()`   | Get agent task progress                |
+| `wait_for_agent_completion()` | Poll until agent task completes   |
+| `check_concurrency()`    | Check concurrency limit status         |
+
+## Configuration
+
+Config is stored in `~/.vcursor/config.json` (shared with the Node.js CLI).
+
+Environment variables:
+- `VCURSOR_API_KEY` - API key
+- `VCURSOR_SERVER` - Server URL
+
+## License
+
+MIT

vcursor_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+vcursor/__init__.py,sha256=tk56HRKYr179Gt5CdYS7W3ECKAnleSq845XCXFNTXJo,524
+vcursor/cli.py,sha256=QM1Zt73b_ROfvYnfST-1p7lCoaTocoCb0ONkJedQPSI,10618
+vcursor/client.py,sha256=fxkAD0La3__iFWgjuXZIjBwBBUqfwHt0R5uNcUK7jwE,13218
+vcursor/types.py,sha256=FCKUw-EcQGryf3KUoCMODNK8pjfMWILtBqn-Kcb1zik,7082
+vcursor_cli-1.0.0.dist-info/METADATA,sha256=WDoZV0X_kuGt5Q64q13rR9DSlt1YUsf0_L6CMThuqSA,4078
+vcursor_cli-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+vcursor_cli-1.0.0.dist-info/entry_points.txt,sha256=ZKxaj1P8-RJJ9OrxgeNDdEaj1nzWG22bKwMr8Qar5pY,45
+vcursor_cli-1.0.0.dist-info/top_level.txt,sha256=-CtKsgji6iMgfMKcDMmkMtb4msDBj0xG0i0Dmywccfs,8
+vcursor_cli-1.0.0.dist-info/RECORD,,

vcursor_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vcursor_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vcursor = vcursor.cli:main

vcursor_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vcursor