cellcog 2.1.2__tar.gz → 2.3.0__tar.gz

{cellcog-2.1.2 → cellcog-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cellcog
-Version: 2.1.2
+Version: 2.3.0
 Summary: Python SDK for CellCog - Any-to-Any AI for agents. Fire-and-forget pattern with WebSocket notifications.
 Project-URL: Homepage, https://cellcog.ai
 Project-URL: Documentation, https://cellcog.ai/developer/docs
@@ -115,7 +115,8 @@ export CELLCOG_API_KEY="sk_..."
 result = client.create_chat(
     prompt="Your task...",
     task_label="my-task",
-    chat_mode="agent",              # "agent" | "agent core" | "agent team" | "agent team max"
+    chat_mode="agent",              # "agent" | "creative" | "team" (legacy names still work)
+    chat_tier="core",               # "flash" | "core" | "max" (omit for the mode's default)
     timeout=1800,                   # 30 min default; use 3600 for complex jobs
 )
 
@@ -172,27 +173,32 @@ result = client.create_chat(
 
 Generated files auto-download to `~/.cellcog/chats/{chat_id}/` or to `GENERATE_FILE` paths if specified.
 
-## Chat Modes
+## Chat Modes & Tiers
 
-| Mode | Speed | Min Credits | Best For |
-|------|-------|-------------|----------|
-| `"agent"` | Fast | 100 | Most tasks — research, images, audio, documents |
-| `"agent core"` | Fast | 50 | Coding, co-work, terminal operations |
-| `"agent team"` | 5–60 min | 500 | Deep research & multi-angled reasoning |
-| `"agent team max"` | Slowest | 2,000 | High-stakes — legal, financial, academic |
+Every chat runs at a (mode, tier) operating point. Pick a mode for the KIND of work,
+a tier for the DEPTH (omit `chat_tier` for the mode's default).
+
+| Mode | Best For | Tiers |
+|------|----------|-------|
+| `"agent"` | Most tasks — building, research, images, audio, documents, coding/co-work | `flash` · `core` · `max` (default) |
+| `"creative"` | Design, brand, frontend craft — taste-first work | `core` (default) · `max` |
+| `"team"` | Deep multi-angled research & analysis (multi-agent) | `flash` · `core` (default) · `max` |
+
+Legacy mode names (`"agent core"`, `"agent team"`, `"agent team max"`) keep working
+forever — the server normalizes them to their historical operating points.
 
 ## 35 Skills — The Cog Family
 
 | Category | Skills |
 |----------|--------|
-| **Research & Analysis** | `research-cog` `fin-cog` `crypto-cog` `data-cog` `news-cog` |
-| **Video & Cinema** | `video-cog` `cine-cog` `insta-cog` `tube-cog` `seedance-cog` |
-| **Images & Design** | `image-cog` `brand-cog` `meme-cog` `banana-cog` `3d-cog` |
-| **Audio & Music** | `audio-cog` `music-cog` `pod-cog` |
-| **Documents & Slides** | `docs-cog` `slides-cog` `spreadsheets-cog` `resume-cog` `legal-cog` |
-| **Apps & Prototypes** | `dash-cog` `game-cog` `proto-cog` |
-| **Creative** | `comi-cog` `story-cog` `learn-cog` `travel-cog` |
-| **Development** | `code-cog` `cowork-cog` `project-cog` `think-cog` |
+| **Research & Analysis** | `deep-research-cellcog` `stock-analysis-cellcog` `crypto-research-cellcog` `data-analysis-cellcog` `news-briefing-cellcog` |
+| **Video & Cinema** | `video-generation-cellcog` `cinematic-video-cellcog` `instagram-reels-tiktok-cellcog` `youtube-video-cellcog` `seedance-video-generation-cellcog` |
+| **Images & Design** | `image-generation-cellcog` `logo-brand-identity-cellcog` `meme-generator-cellcog` `nano-banana-image-cellcog` `3d-model-generation-cellcog` |
+| **Audio & Music** | `audio-generation-cellcog` `music-generation-cellcog` `podcast-generation-cellcog` |
+| **Documents & Slides** | `pdf-document-generation-cellcog` `presentation-slides-cellcog` `excel-spreadsheet-cellcog` `resume-cover-letter-cellcog` `legal-documents-cellcog` |
+| **Apps & Prototypes** | `dashboard-web-app-cellcog` `game-asset-generation-cellcog` `ui-prototype-wireframe-cellcog` |
+| **Creative** | `comic-manga-generator-cellcog` `creative-writing-cellcog` `tutoring-education-cellcog` `travel-planning-cellcog` |
+| **Development** | `coding-agent-cellcog` `pair-programming-cellcog` `project-management-cellcog` `brainstorming-strategy-cellcog` |
 
 Browse all skills: https://cellcog.ai/skills
 

{cellcog-2.1.2 → cellcog-2.3.0}/README.md

@@ -83,7 +83,8 @@ export CELLCOG_API_KEY="sk_..."
 result = client.create_chat(
     prompt="Your task...",
     task_label="my-task",
-    chat_mode="agent",              # "agent" | "agent core" | "agent team" | "agent team max"
+    chat_mode="agent",              # "agent" | "creative" | "team" (legacy names still work)
+    chat_tier="core",               # "flash" | "core" | "max" (omit for the mode's default)
     timeout=1800,                   # 30 min default; use 3600 for complex jobs
 )
 
@@ -140,27 +141,32 @@ result = client.create_chat(
 
 Generated files auto-download to `~/.cellcog/chats/{chat_id}/` or to `GENERATE_FILE` paths if specified.
 
-## Chat Modes
+## Chat Modes & Tiers
 
-| Mode | Speed | Min Credits | Best For |
-|------|-------|-------------|----------|
-| `"agent"` | Fast | 100 | Most tasks — research, images, audio, documents |
-| `"agent core"` | Fast | 50 | Coding, co-work, terminal operations |
-| `"agent team"` | 5–60 min | 500 | Deep research & multi-angled reasoning |
-| `"agent team max"` | Slowest | 2,000 | High-stakes — legal, financial, academic |
+Every chat runs at a (mode, tier) operating point. Pick a mode for the KIND of work,
+a tier for the DEPTH (omit `chat_tier` for the mode's default).
+
+| Mode | Best For | Tiers |
+|------|----------|-------|
+| `"agent"` | Most tasks — building, research, images, audio, documents, coding/co-work | `flash` · `core` · `max` (default) |
+| `"creative"` | Design, brand, frontend craft — taste-first work | `core` (default) · `max` |
+| `"team"` | Deep multi-angled research & analysis (multi-agent) | `flash` · `core` (default) · `max` |
+
+Legacy mode names (`"agent core"`, `"agent team"`, `"agent team max"`) keep working
+forever — the server normalizes them to their historical operating points.
 
 ## 35 Skills — The Cog Family
 
 | Category | Skills |
 |----------|--------|
-| **Research & Analysis** | `research-cog` `fin-cog` `crypto-cog` `data-cog` `news-cog` |
-| **Video & Cinema** | `video-cog` `cine-cog` `insta-cog` `tube-cog` `seedance-cog` |
-| **Images & Design** | `image-cog` `brand-cog` `meme-cog` `banana-cog` `3d-cog` |
-| **Audio & Music** | `audio-cog` `music-cog` `pod-cog` |
-| **Documents & Slides** | `docs-cog` `slides-cog` `spreadsheets-cog` `resume-cog` `legal-cog` |
-| **Apps & Prototypes** | `dash-cog` `game-cog` `proto-cog` |
-| **Creative** | `comi-cog` `story-cog` `learn-cog` `travel-cog` |
-| **Development** | `code-cog` `cowork-cog` `project-cog` `think-cog` |
+| **Research & Analysis** | `deep-research-cellcog` `stock-analysis-cellcog` `crypto-research-cellcog` `data-analysis-cellcog` `news-briefing-cellcog` |
+| **Video & Cinema** | `video-generation-cellcog` `cinematic-video-cellcog` `instagram-reels-tiktok-cellcog` `youtube-video-cellcog` `seedance-video-generation-cellcog` |
+| **Images & Design** | `image-generation-cellcog` `logo-brand-identity-cellcog` `meme-generator-cellcog` `nano-banana-image-cellcog` `3d-model-generation-cellcog` |
+| **Audio & Music** | `audio-generation-cellcog` `music-generation-cellcog` `podcast-generation-cellcog` |
+| **Documents & Slides** | `pdf-document-generation-cellcog` `presentation-slides-cellcog` `excel-spreadsheet-cellcog` `resume-cover-letter-cellcog` `legal-documents-cellcog` |
+| **Apps & Prototypes** | `dashboard-web-app-cellcog` `game-asset-generation-cellcog` `ui-prototype-wireframe-cellcog` |
+| **Creative** | `comic-manga-generator-cellcog` `creative-writing-cellcog` `tutoring-education-cellcog` `travel-planning-cellcog` |
+| **Development** | `coding-agent-cellcog` `pair-programming-cellcog` `project-management-cellcog` `brainstorming-strategy-cellcog` |
 
 Browse all skills: https://cellcog.ai/skills
 

{cellcog-2.1.2 → cellcog-2.3.0}/cellcog/__init__.py

@@ -48,7 +48,7 @@ from .exceptions import (
     SDKUpgradeRequiredError,
 )
 
-__version__ = "2.1.1"
+__version__ = "2.3.0"
 __all__ = [
     "CellCogClient",
     "CellCogError",

{cellcog-2.1.2 → cellcog-2.3.0}/cellcog/chat.py

@@ -20,6 +20,48 @@ from .exceptions import (
 )
 from .files import FileProcessor
 
+# ── Mode × Tier resolution (Mode × Tier redesign, 2026-08) ──────────────────
+# Friendly SDK names -> API chat_mode values. The server accepts BOTH current
+# API values and legacy ones forever (they normalize server-side to their
+# historical operating points), so unknown strings pass through untouched and
+# the server returns a clear 400 for genuinely invalid values.
+_MODE_ALIASES = {
+    # Current modes
+    "agent": "human_in_the_loop",
+    "creative": "agent_creative",
+    "agent creative": "agent_creative",
+    "team": "agent_in_the_loop",
+    "agent team": "agent_in_the_loop",
+    # Legacy names (kept working forever; server normalizes)
+    "agent core": "agent_core",
+    "agent team max": "agent_team_max",
+}
+
+_VALID_TIERS = ("flash", "core", "max")
+
+
+def resolve_chat_mode(chat_mode: Optional[str]) -> str:
+    """Map a friendly mode name to its API value; pass raw API/unknown values through."""
+    if not chat_mode:
+        return "human_in_the_loop"
+    key = str(chat_mode).strip().lower()
+    return _MODE_ALIASES.get(key, chat_mode)
+
+
+def resolve_chat_tier(chat_tier: Optional[str]) -> Optional[str]:
+    """Normalize a tier string ('flash' | 'core' | 'max'); None passes through (server
+    applies the mode's default tier). Unknown values raise immediately — a typo'd tier
+    silently falling back to a default would misroute spend."""
+    if chat_tier is None or str(chat_tier).strip() == "":
+        return None
+    tier = str(chat_tier).strip().lower()
+    if tier not in _VALID_TIERS:
+        raise ValueError(
+            f"Invalid chat_tier: {chat_tier!r}. Use 'flash', 'core', or 'max' "
+            "(or omit it for the mode's default). Note: 'creative' has no 'flash' tier."
+        )
+    return tier
+
 
 class ChatManager:
     """
@@ -48,6 +90,7 @@ class ChatManager:
         agent_role_id: Optional[str] = None,
         hc_enabled: bool = False,
         hc_working_directory: Optional[str] = None,
+        chat_tier: Optional[str] = None,
     ) -> dict:
         """
         Create a new CellCog chat (without streaming).
@@ -55,7 +98,12 @@ class ChatManager:
         Args:
             prompt: Initial prompt (can include SHOW_FILE tags for file uploads)
             project_id: Optional CellCog project ID for document context
-            chat_mode: "agent" (fast, iterative), "agent core" (coding/co-work), "agent team" (deep reasoning), or "agent team max" (high-stakes)
+            chat_mode: "agent" (fast, iterative), "creative" (design/craft-first), or
+                "team" (deep multi-angled research). Legacy names — "agent core",
+                "agent team", "agent team max" — keep working forever (normalized
+                server-side to their historical operating points).
+            chat_tier: "flash" | "core" | "max" — depth/spend within the mode.
+                None -> the mode's default tier. "creative" has no "flash" tier.
             agent_role_id: Optional agent role ID within the project. Requires project_id.
             hc_enabled: Enable Human Computer (co-work) for this chat
             hc_working_directory: Working directory on user's machine for HC commands
@@ -69,17 +117,14 @@ class ChatManager:
         """
         self.config.require_configured()
 
-        mode_mapping = {
-            "agent team max": "agent_team_max",
-            "agent team": "agent_in_the_loop",
-            "agent core": "agent_core",
-            "agent": "human_in_the_loop",
-        }
-        api_chat_mode = mode_mapping.get(chat_mode, chat_mode)
+        api_chat_mode = resolve_chat_mode(chat_mode)
+        api_chat_tier = resolve_chat_tier(chat_tier)
 
         transformed, uploaded = self.files.transform_outgoing(prompt)
 
         data = {"message": transformed, "chat_mode": api_chat_mode}
+        if api_chat_tier:
+            data["chat_tier"] = api_chat_tier
         if project_id:
             data["project_id"] = project_id
         if agent_role_id:

{cellcog-2.1.2 → cellcog-2.3.0}/cellcog/client.py

@@ -279,6 +279,7 @@ class CellCogClient:
         chat_mode: str = "agent",
         enable_cowork: bool = False,
         cowork_working_directory: Optional[str] = None,
+        chat_tier: Optional[str] = None,
     ) -> dict:
         """
         Create a CellCog chat.
@@ -301,7 +302,10 @@ class CellCogClient:
             gateway_url: OpenClaw Gateway URL (notify_on_completion only)
             project_id: Optional CellCog project ID for document context
             agent_role_id: Optional agent role ID within the project
-            chat_mode: "agent", "agent core", "agent team", or "agent team max"
+            chat_mode: "agent", "creative", or "team". Legacy names — "agent core",
+                "agent team", "agent team max" — keep working forever.
+            chat_tier: "flash" | "core" | "max" — depth/spend within the mode.
+                None -> the mode's default tier. "creative" has no "flash" tier.
             enable_cowork: Enable co-work on user's PC
             cowork_working_directory: Working directory for co-work commands
 
@@ -369,6 +373,7 @@ class CellCogClient:
         # ── Create the chat via API ──
         api_result = self._chat.create(
             prompt, project_id, chat_mode,
+            chat_tier=chat_tier,
             agent_role_id=agent_role_id,
             hc_enabled=enable_cowork,
             hc_working_directory=cowork_working_directory,

{cellcog-2.1.2 → cellcog-2.3.0}/cellcog/docs/api_reference.md

@@ -25,10 +25,11 @@ result = client.create_chat(
     timeout: int = 1800,                  # Max wait seconds (wait mode only)
     notify_session_key: str = None,       # OpenClaw session key (notify mode only)
     gateway_url: str = None,              # OpenClaw Gateway URL (notify mode only)
-    chat_mode: str = "agent",             # "agent", "agent core", "agent team", "agent team max"
-    project_id: str = None,               # Project context (see project-cog)
+    chat_mode: str = "agent",             # "agent", "creative", "team" (legacy names still work)
+    chat_tier: str = None,                # "flash" | "core" | "max" (None = mode default; creative has no flash)
+    project_id: str = None,               # Project context (see project-management-cellcog)
     agent_role_id: str = None,            # Specialized role (requires project_id)
-    enable_cowork: bool = False,          # Direct machine access (see cowork-cog)
+    enable_cowork: bool = False,          # Direct machine access (see pair-programming-cellcog)
     cowork_working_directory: str = None, # Working dir for co-work
 )
 ```

{cellcog-2.1.2 → cellcog-2.3.0}/cellcog/files.py

@@ -66,8 +66,10 @@ class FileProcessor:
             attrs = match.group(1)
             file_path = match.group(2).strip()
 
-            # Skip empty paths and URLs — not local files
-            if not file_path or file_path.startswith(("http://", "https://")):
+            # Skip empty paths and URLs — not local files. gs:// is a CellCog
+            # storage reference (already-uploaded file); leave it untouched so it
+            # is not mistaken for a missing local file (which would raise).
+            if not file_path or file_path.startswith(("http://", "https://", "gs://")):
                 return match.group(0)
 
             # Cross-platform local file detection:
@@ -272,17 +274,25 @@ class FileProcessor:
         """
         Generate safe download path under ~/.cellcog/chats/{chat_id}/.
 
-        Handles two blob_name formats:
+        Handles these blob_name formats:
+        - gs://bucket/{chat_id}/path/to/file.ext (canonical explicit GS URL)
         - {chat_id}//home/app/path/to/file.ext  (double slash = from CellCog's /home/app/)
         - {chat_id}/path/to/file.ext             (single slash = relative path)
 
         Args:
-            blob_name: Full blob name from CellCog
+            blob_name: Full blob name (or gs:// URL) from CellCog
             chat_id: Chat ID for organizing downloads
 
         Returns:
             Local path like ~/.cellcog/chats/{chat_id}/{path}
         """
+        # Strip a canonical gs://bucket/ prefix down to the bare blob name
+        # ({chat_id}/path...) so the existing chat_id-prefix logic applies.
+        if blob_name.startswith("gs://"):
+            # gs://bucket/{chat_id}/path → drop scheme + bucket (first 3 segments)
+            parts = blob_name.split("/", 3)
+            blob_name = parts[3] if len(parts) > 3 else parts[-1]
+
         if "/" not in blob_name:
             # Malformed - use blob_name as filename
             return str(self.default_download_dir / chat_id / blob_name)

{cellcog-2.1.2 → cellcog-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cellcog"
-version = "2.1.2"
+version = "2.3.0"
 description = "Python SDK for CellCog - Any-to-Any AI for agents. Fire-and-forget pattern with WebSocket notifications."
 readme = "README.md"
 license = {text = "MIT"}

cellcog-2.3.0/tests/test_gs_url_handling.py

@@ -0,0 +1,54 @@
+"""Standalone tests for SDK gs:// SHOW_FILE handling.
+
+Run: python3 tests/test_gs_url_handling.py
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from cellcog.config import Config
+from cellcog.files import FileProcessor
+
+CHAT = "687a8aa4fcf12067f5a5b9e0"
+failed = 0
+
+
+def check(label, got, want):
+    global failed
+    ok = got == want
+    if not ok:
+        failed += 1
+        print(f"[FAIL] {label}\n       got : {got}\n       want: {want}")
+    else:
+        print(f"[OK ] {label}")
+
+
+fp = FileProcessor(Config())
+
+# --- download-path derivation strips gs://bucket/ then chat_id ---
+# Real CellCog blobs from /home/app are {chat_id}//home/app/... (double slash:
+# {chat_id}/ + the absolute /home/app/... path). The /home/app/ prefix is stripped.
+p = fp._generate_auto_download_path(f"gs://cellcog_files/{CHAT}//home/app/out.png", CHAT)
+check("gs:// download path strips scheme+bucket+chat+/home/app",
+      p, str(fp.default_download_dir / CHAT / "out.png"))
+
+# A non-/home/app relative path keeps its sub-path after the chat_id.
+p = fp._generate_auto_download_path(f"gs://cellcog_files/{CHAT}/sub/dir/file.pdf", CHAT)
+check("gs:// download path nested",
+      p, str(fp.default_download_dir / CHAT / "sub/dir/file.pdf"))
+
+# --- legacy bare blob still works (back-compat), double-slash /home/app form ---
+p = fp._generate_auto_download_path(f"{CHAT}//home/app/out.png", CHAT)
+check("legacy bare blob still derives correctly",
+      p, str(fp.default_download_dir / CHAT / "out.png"))
+
+# --- outgoing: gs:// is left untouched (not treated as missing local file) ---
+msg = f"Here <SHOW_FILE>gs://cellcog_files/{CHAT}/a.png</SHOW_FILE> done"
+transformed, uploaded = fp.transform_outgoing(msg)
+check("outgoing gs:// unchanged", transformed, msg)
+check("outgoing gs:// nothing uploaded", uploaded, [])
+
+print("\n" + ("ALL PASS" if failed == 0 else f"{failed} FAILURE(S)"))
+sys.exit(1 if failed else 0)