cellcog 2.0.0__tar.gz → 2.0.2__tar.gz

cellcog-2.0.2/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: cellcog
+Version: 2.0.2
+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
+Project-URL: Repository, https://github.com/CellCog/cellcog_python
+Project-URL: Issues, https://github.com/CellCog/cellcog_python/issues
+Author-email: CellCog <support@cellcog.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,image,multimodal,openclaw,pdf,research,video
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: websockets>=11.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CellCog Python SDK
+
+**CellCog: Any-to-Any AI for Agents** — Your sub-agent for quality work.
+
+When you need depth, accuracy, or complex deliverables — research reports, interactive apps, videos, images, podcasts, documents, spreadsheets, and more — use CellCog.
+
+## Installation
+
+```bash
+pip install cellcog
+```
+
+## Quick Start
+
+```bash
+export CELLCOG_API_KEY="sk_..."  # Get from https://cellcog.ai/profile?tab=api-keys
+```
+
+**Any agent (blocks until done):**
+
+```python
+from cellcog import CellCogClient
+
+client = CellCogClient()
+
+result = client.create_chat(
+    prompt="Research quantum computing advances in 2026",
+    task_label="quantum-research",
+    chat_mode="agent",
+)
+# Blocks until done — result contains everything
+print(result["message"])
+```
+
+**OpenClaw agents (fire-and-forget):**
+
+```python
+result = client.create_chat(
+    prompt="Research quantum computing advances in 2026",
+    notify_session_key="agent:main:main",  # OpenClaw session key
+    task_label="quantum-research",
+    chat_mode="agent",
+)
+# Returns immediately — daemon delivers results to your session
+```
+
+## How It Works
+
+**Two delivery modes:**
+
+- **Wait for Completion (default)** — Blocks until CellCog finishes and returns the full result. Works with any agent — OpenClaw, Claude Code, Cursor, or any Python environment.
+
+- **Fire-and-Forget (OpenClaw)** — Returns immediately. A background daemon monitors via WebSocket and delivers results to your OpenClaw session when done. Requires `sessions_send` on OpenClaw Gateway.
+
+All methods return the same unified shape:
+
+```python
+{
+    "chat_id": str,
+    "is_operating": bool,
+    "status": str,         # "completed" | "tracking" | "timeout" | "operating"
+    "message": str,        # Always print this in full
+}
+```
+
+## Configuration
+
+```bash
+export CELLCOG_API_KEY="sk_..."
+```
+
+**Get your API key:**
+1. Create account: https://cellcog.ai/signup
+2. Add payment: https://cellcog.ai/profile?tab=billing
+3. Get API key: https://cellcog.ai/profile?tab=api-keys
+
+## API Reference
+
+### Core Methods
+
+```python
+# Create chat — wait mode (default, universal)
+result = client.create_chat(
+    prompt="Your task...",
+    task_label="my-task",
+    chat_mode="agent",              # "agent" | "agent core" | "agent team" | "agent team max"
+    timeout=1800,                   # 30 min default; use 3600 for complex jobs
+)
+
+# Create chat — notify mode (OpenClaw only)
+result = client.create_chat(
+    prompt="Your task...",
+    notify_session_key="agent:main:main",
+    task_label="my-task",
+    chat_mode="agent",
+)
+
+# Send follow-up message
+result = client.send_message(chat_id="abc123", message="Now create a PDF summary")
+
+# Get full history
+result = client.get_history(chat_id="abc123")
+
+# Quick status check
+status = client.get_status(chat_id="abc123")
+
+# Resume waiting after timeout
+result = client.wait_for_completion(chat_id="abc123", timeout=1800)
+```
+
+### Optional Parameters
+
+```python
+result = client.create_chat(
+    prompt="...",
+    task_label="...",
+    chat_mode="agent",
+    project_id="...",                       # CellCog project for document context
+    agent_role_id="...",                    # Specialized agent role
+    enable_cowork=True,                     # Direct machine access via CellCog Desktop
+    cowork_working_directory="/Users/...",  # Working directory for co-work
+)
+```
+
+## File Handling
+
+```python
+# Send files to CellCog
+result = client.create_chat(
+    prompt='Analyze this data: <SHOW_FILE>/path/to/sales.csv</SHOW_FILE>',
+    task_label="data-analysis",
+)
+
+# Request output at specific path
+result = client.create_chat(
+    prompt='Create a report: <GENERATE_FILE>/output/report.pdf</GENERATE_FILE>',
+    task_label="report",
+)
+```
+
+Generated files auto-download to `~/.cellcog/chats/{chat_id}/` or to `GENERATE_FILE` paths if specified.
+
+## Chat Modes
+
+| 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 |
+
+## 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` `sheet-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` |
+
+Browse all skills: https://cellcog.ai/skills
+
+## Error Handling
+
+```python
+from cellcog import (
+    CellCogClient,
+    PaymentRequiredError,
+    MaxConcurrencyError,
+    GatewayConfigError,
+    SDKUpgradeRequiredError,
+)
+
+client = CellCogClient()
+
+try:
+    result = client.create_chat(...)
+except PaymentRequiredError as e:
+    print(f"Add credits: {e.billing_url}")
+except MaxConcurrencyError as e:
+    print(f"Too many parallel chats: {e.operating_count}/{e.max_parallel}")
+except GatewayConfigError as e:
+    print(f"Fix: {e.fix_command}")  # OpenClaw notify mode only
+except SDKUpgradeRequiredError as e:
+    print(f"Upgrade: pip install cellcog>={e.minimum_version}")
+```
+
+## Links
+
+- **CellCog Platform:** https://cellcog.ai
+- **Skills Catalog:** https://cellcog.ai/skills
+- **GitHub:** https://github.com/CellCog/cellcog_python
+- **ClawHub Skills:** https://clawhub.ai
+- **API Docs:** https://cellcog.ai/developer/docs
+- **Get API Key:** https://cellcog.ai/profile?tab=api-keys
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

cellcog-2.0.2/README.md

@@ -0,0 +1,203 @@
+# CellCog Python SDK
+
+**CellCog: Any-to-Any AI for Agents** — Your sub-agent for quality work.
+
+When you need depth, accuracy, or complex deliverables — research reports, interactive apps, videos, images, podcasts, documents, spreadsheets, and more — use CellCog.
+
+## Installation
+
+```bash
+pip install cellcog
+```
+
+## Quick Start
+
+```bash
+export CELLCOG_API_KEY="sk_..."  # Get from https://cellcog.ai/profile?tab=api-keys
+```
+
+**Any agent (blocks until done):**
+
+```python
+from cellcog import CellCogClient
+
+client = CellCogClient()
+
+result = client.create_chat(
+    prompt="Research quantum computing advances in 2026",
+    task_label="quantum-research",
+    chat_mode="agent",
+)
+# Blocks until done — result contains everything
+print(result["message"])
+```
+
+**OpenClaw agents (fire-and-forget):**
+
+```python
+result = client.create_chat(
+    prompt="Research quantum computing advances in 2026",
+    notify_session_key="agent:main:main",  # OpenClaw session key
+    task_label="quantum-research",
+    chat_mode="agent",
+)
+# Returns immediately — daemon delivers results to your session
+```
+
+## How It Works
+
+**Two delivery modes:**
+
+- **Wait for Completion (default)** — Blocks until CellCog finishes and returns the full result. Works with any agent — OpenClaw, Claude Code, Cursor, or any Python environment.
+
+- **Fire-and-Forget (OpenClaw)** — Returns immediately. A background daemon monitors via WebSocket and delivers results to your OpenClaw session when done. Requires `sessions_send` on OpenClaw Gateway.
+
+All methods return the same unified shape:
+
+```python
+{
+    "chat_id": str,
+    "is_operating": bool,
+    "status": str,         # "completed" | "tracking" | "timeout" | "operating"
+    "message": str,        # Always print this in full
+}
+```
+
+## Configuration
+
+```bash
+export CELLCOG_API_KEY="sk_..."
+```
+
+**Get your API key:**
+1. Create account: https://cellcog.ai/signup
+2. Add payment: https://cellcog.ai/profile?tab=billing
+3. Get API key: https://cellcog.ai/profile?tab=api-keys
+
+## API Reference
+
+### Core Methods
+
+```python
+# Create chat — wait mode (default, universal)
+result = client.create_chat(
+    prompt="Your task...",
+    task_label="my-task",
+    chat_mode="agent",              # "agent" | "agent core" | "agent team" | "agent team max"
+    timeout=1800,                   # 30 min default; use 3600 for complex jobs
+)
+
+# Create chat — notify mode (OpenClaw only)
+result = client.create_chat(
+    prompt="Your task...",
+    notify_session_key="agent:main:main",
+    task_label="my-task",
+    chat_mode="agent",
+)
+
+# Send follow-up message
+result = client.send_message(chat_id="abc123", message="Now create a PDF summary")
+
+# Get full history
+result = client.get_history(chat_id="abc123")
+
+# Quick status check
+status = client.get_status(chat_id="abc123")
+
+# Resume waiting after timeout
+result = client.wait_for_completion(chat_id="abc123", timeout=1800)
+```
+
+### Optional Parameters
+
+```python
+result = client.create_chat(
+    prompt="...",
+    task_label="...",
+    chat_mode="agent",
+    project_id="...",                       # CellCog project for document context
+    agent_role_id="...",                    # Specialized agent role
+    enable_cowork=True,                     # Direct machine access via CellCog Desktop
+    cowork_working_directory="/Users/...",  # Working directory for co-work
+)
+```
+
+## File Handling
+
+```python
+# Send files to CellCog
+result = client.create_chat(
+    prompt='Analyze this data: <SHOW_FILE>/path/to/sales.csv</SHOW_FILE>',
+    task_label="data-analysis",
+)
+
+# Request output at specific path
+result = client.create_chat(
+    prompt='Create a report: <GENERATE_FILE>/output/report.pdf</GENERATE_FILE>',
+    task_label="report",
+)
+```
+
+Generated files auto-download to `~/.cellcog/chats/{chat_id}/` or to `GENERATE_FILE` paths if specified.
+
+## Chat Modes
+
+| 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 |
+
+## 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` `sheet-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` |
+
+Browse all skills: https://cellcog.ai/skills
+
+## Error Handling
+
+```python
+from cellcog import (
+    CellCogClient,
+    PaymentRequiredError,
+    MaxConcurrencyError,
+    GatewayConfigError,
+    SDKUpgradeRequiredError,
+)
+
+client = CellCogClient()
+
+try:
+    result = client.create_chat(...)
+except PaymentRequiredError as e:
+    print(f"Add credits: {e.billing_url}")
+except MaxConcurrencyError as e:
+    print(f"Too many parallel chats: {e.operating_count}/{e.max_parallel}")
+except GatewayConfigError as e:
+    print(f"Fix: {e.fix_command}")  # OpenClaw notify mode only
+except SDKUpgradeRequiredError as e:
+    print(f"Upgrade: pip install cellcog>={e.minimum_version}")
+```
+
+## Links
+
+- **CellCog Platform:** https://cellcog.ai
+- **Skills Catalog:** https://cellcog.ai/skills
+- **GitHub:** https://github.com/CellCog/cellcog_python
+- **ClawHub Skills:** https://clawhub.ai
+- **API Docs:** https://cellcog.ai/developer/docs
+- **Get API Key:** https://cellcog.ai/profile?tab=api-keys
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

{cellcog-2.0.0 → cellcog-2.0.2}/cellcog/__init__.py

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

{cellcog-2.0.0 → cellcog-2.0.2}/cellcog/docs/api_reference.md

@@ -13,13 +13,18 @@ client = CellCogClient(config_path=None)
 
 ### create_chat()
 
-Create a new CellCog task. Returns immediately — results delivered via daemon.
+Create a new CellCog task. Two delivery modes:
+- `wait_for_completion` (default): Blocks until done. Works with any agent.
+- `notify_on_completion`: Returns immediately. OpenClaw only.
 
 ```python
 result = client.create_chat(
     prompt: str,                          # Task description (required)
-    notify_session_key: str,              # Where to deliver results (required)
-    task_label: str,                      # Human-readable label (required)
+    task_label: str = "",                 # Human-readable label
+    delivery: str = "wait_for_completion",# "wait_for_completion" or "notify_on_completion"
+    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)
     agent_role_id: str = None,            # Specialized role (requires project_id)
@@ -28,31 +33,43 @@ result = client.create_chat(
 )
 ```
 
-**Returns:** `{"chat_id": str, "status": "tracking", "listeners": int, "explanation": str}`
+**Returns (all modes):**
+```python
+{
+    "chat_id": str,        # CellCog chat ID
+    "is_operating": bool,  # True = still working, False = done
+    "status": str,         # "completed" | "tracking" | "timeout"
+    "message": str,        # THE printable message — always print in full
+}
+```
 
 **Raises:**
 - `PaymentRequiredError` (402) — insufficient credits
 - `MaxConcurrencyError` (429) — too many parallel chats
 - `AccountDisabledError` (403) — account flagged or disabled
+- `GatewayConfigError` — sessions_send blocked (notify mode only)
 
 ### send_message()
 
-Continue an existing conversation.
+Continue an existing conversation. Same delivery modes as `create_chat()`.
 
 ```python
 result = client.send_message(
     chat_id: str,                         # Existing chat (required)
     message: str,                         # Follow-up message (required)
-    notify_session_key: str,              # Where to deliver results (required)
-    task_label: str,                      # Label for this message (required)
+    task_label: str = None,               # Label for this message
+    delivery: str = "wait_for_completion",# "wait_for_completion" or "notify_on_completion"
+    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)
 )
 ```
 
-**Returns:** `{"chat_id": str, "status": "tracking", "listeners": int, "explanation": str}`
+**Returns:** Same `{chat_id, is_operating, status, message}` shape.
 
 ### wait_for_completion()
 
-Block until a chat finishes operating.
+Block until a chat finishes operating. Use to resume waiting after a timeout.
 
 ```python
 completion = client.wait_for_completion(
@@ -61,39 +78,36 @@ completion = client.wait_for_completion(
 )
 ```
 
-**Returns:**
-```python
-{
-    "chat_id": str,
-    "is_operating": bool,       # False = done, True = timeout reached
-    "status": str,              # "completed" | "waiting"
-    "status_message": str
-}
-```
+**Returns:** Same `{chat_id, is_operating, status, message}` shape.
+- `status: "completed"` — chat finished, `message` contains full results
+- `status: "timeout"` — still working, `message` contains progress
 
-### get_status()
+### get_history()
 
-Quick status check (no message content).
+Full chat history. Use when original delivery was missed or for manual inspection.
 
 ```python
-status = client.get_status(chat_id: str)
+result = client.get_history(
+    chat_id: str,
+    download_files: bool = True,
+)
 ```
 
-**Returns:** `{"is_operating": bool, ...}`
+**Returns:** Same `{chat_id, is_operating, status, message}` shape with full history.
 
-### get_history()
+### get_status()
 
-Full chat history with formatted messages.
+Quick status check (no message content).
 
 ```python
-result = client.get_history(chat_id: str)
+status = client.get_status(chat_id: str)
 ```
 
-**Returns:** `{"is_operating": bool, "formatted_output": str, "messages": list}`
+**Returns:** `{"is_operating": bool, "status": str, "name": str, ...}`
 
 ### delete_chat()
 
-Permanently delete a chat and all server-side data.
+Permanently delete a chat and all server-side data (~15 seconds).
 
 ```python
 result = client.delete_chat(chat_id: str)
@@ -141,7 +155,7 @@ Check if CellCog Desktop is connected.
 
 ```python
 status = client.get_desktop_status()
-# {"connected": bool, ...}
+# {"connected": bool, "system_info": {...} | None, ...}
 ```
 
 ### get_desktop_download_urls()
@@ -150,7 +164,7 @@ Get platform-specific download URLs and install commands.
 
 ```python
 info = client.get_desktop_download_urls()
-# {"platforms": {"darwin": {...}, "linux": {...}, "windows": {...}}}
+# {"mac": {"url": str, "install_commands": [...]}, "windows": {...}, "linux": {...}, "post_install": str}
 ```
 
 ---
@@ -161,6 +175,7 @@ info = client.get_desktop_download_urls()
 
 ```python
 projects = client.list_projects()
+# {"projects": [{"id", "name", "is_admin", "context_tree_id", ...}]}
 ```
 
 ### create_project()
@@ -178,7 +193,7 @@ project = client.get_project(project_id: str)
 ### update_project()
 
 ```python
-project = client.update_project(project_id: str, name: str = None, instructions: str = None)
+result = client.update_project(project_id: str, name: str = None, instructions: str = None)
 ```
 
 ### delete_project()
@@ -205,7 +220,6 @@ docs = client.list_documents(context_tree_id: str)
 result = client.upload_document(
     context_tree_id: str,
     file_path: str,
-    target_path: str = None,
     brief_context: str = None,
 )
 ```
@@ -216,6 +230,13 @@ result = client.upload_document(
 result = client.delete_document(context_tree_id: str, file_id: str)
 ```
 
+### bulk_delete_documents()
+
+```python
+result = client.bulk_delete_documents(context_tree_id: str, file_ids: list)
+# {"deleted": int, "failed": int, "results": {...}}
+```
+
 ### get_context_tree_markdown()
 
 ```python
@@ -225,7 +246,21 @@ tree = client.get_context_tree_markdown(context_tree_id: str, include_long_descr
 ### get_document_signed_urls()
 
 ```python
-urls = client.get_document_signed_urls(context_tree_id: str, file_ids: list)
+urls = client.get_document_signed_urls(context_tree_id: str, file_ids: list, expiration_hours: int = 1)
+# {"urls": {file_id: url_or_null}, "errors": {file_id: error_msg}}
+```
+
+### get_document_signed_urls_by_path()
+
+Get signed URLs using file paths from the context tree markdown (no file IDs needed).
+
+```python
+urls = client.get_document_signed_urls_by_path(
+    context_tree_id: str,
+    file_paths: list,
+    expiration_hours: int = 1,
+)
+# {"urls": {path: url_or_null}, "errors": {path: error_msg}}
 ```
 
 ---
@@ -238,7 +273,7 @@ urls = client.get_document_signed_urls(context_tree_id: str, file_ids: list)
 result = client.create_ticket(
     type: str,              # "support", "feedback", "feature_request", "bug_report"
     title: str,
-    description: str = "",
+    description: str,
     chat_id: str = None,
     tags: list = None,
     priority: str = "medium",  # "low", "medium", "high", "critical"
@@ -247,6 +282,22 @@ result = client.create_ticket(
 
 ---
 
+## Documentation
+
+### get_support_docs()
+
+```python
+docs = client.get_support_docs()  # Returns markdown string
+```
+
+### get_api_reference()
+
+```python
+docs = client.get_api_reference()  # Returns markdown string
+```
+
+---
+
 ## Exception Classes
 
 ```python
@@ -258,7 +309,10 @@ from cellcog.exceptions import (
     PaymentRequiredError,      # Insufficient credits (includes top_ups, billing_url)
     MaxConcurrencyError,       # Too many parallel chats
     AccountDisabledError,      # Account flagged or disabled
-    UpgradeRequiredError,      # SDK version too old
+    SDKUpgradeRequiredError,   # SDK version too old
+    GatewayConfigError,        # sessions_send blocked on OpenClaw Gateway
+    FileUploadError,           # File upload failed
+    FileDownloadError,         # File download failed
 )
 ```
 
@@ -274,3 +328,7 @@ from cellcog.exceptions import (
 - `max_parallel`: Maximum allowed with current balance
 - `effective_balance`: Current credit balance
 - `credits_per_slot`: Credits per additional slot (500)
+
+### GatewayConfigError Attributes
+- `gateway_url`: The Gateway URL that was checked
+- `fix_command`: The exact command to run to fix the issue