chattermate-cli 0.2.0__py3-none-any.whl

chattermate_cli/__init__.py

@@ -0,0 +1,19 @@
+"""
+ChatterMate - CLI & MCP SDK
+Copyright (C) 2024 ChatterMate
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>
+"""
+
+__version__ = "0.1.0"

chattermate_cli/client.py

@@ -0,0 +1,275 @@
+"""
+ChatterMate - API Client
+Copyright (C) 2024 ChatterMate
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>
+"""
+
+from typing import Any, Callable, Dict, List, Optional
+
+import httpx
+
+API_PREFIX = "/api/v1"
+PAT_PREFIX = "cmat_"
+
+
+class ChatterMateError(Exception):
+    """Raised when the API returns an error or is unreachable."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class Client:
+    """
+    Thin HTTP wrapper around the ChatterMate API.
+
+    Supports two credentials:
+      * a Personal Access Token (``cmat_...``) — preferred for non-interactive use, and
+      * a JWT access token from ``login`` (auto-refreshed once on 401 using the refresh token).
+
+    Used by both the CLI commands and the MCP server.
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        token: Optional[str] = None,
+        refresh_token: Optional[str] = None,
+        on_tokens: Optional[Callable[[str, Optional[str]], None]] = None,
+        timeout: float = 30.0,
+    ):
+        self.api_url = api_url.rstrip("/")
+        self.token = token
+        self.refresh_token = refresh_token
+        self.on_tokens = on_tokens
+        self._http = httpx.Client(timeout=timeout)
+
+    # -- internals ---------------------------------------------------------
+
+    def _is_pat(self) -> bool:
+        return bool(self.token and self.token.startswith(PAT_PREFIX))
+
+    def _auth_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.token}"} if self.token else {}
+
+    def _refresh(self) -> bool:
+        if not self.refresh_token or self._is_pat():
+            return False
+        try:
+            resp = self._http.post(
+                f"{self.api_url}{API_PREFIX}/users/refresh",
+                cookies={"refresh_token": self.refresh_token},
+            )
+        except httpx.HTTPError:
+            return False
+        if resp.status_code != 200:
+            return False
+        data = resp.json()
+        self.token = data.get("access_token", self.token)
+        if data.get("refresh_token"):
+            self.refresh_token = data["refresh_token"]
+        if self.on_tokens:
+            self.on_tokens(self.token, self.refresh_token)
+        return True
+
+    @staticmethod
+    def _format_error(resp: httpx.Response) -> str:
+        try:
+            detail = resp.json().get("detail")
+        except Exception:
+            return resp.text or f"HTTP {resp.status_code}"
+        if isinstance(detail, list):
+            # FastAPI validation errors: list of {loc, msg, ...} — but tolerate plain strings.
+            parts = []
+            for item in detail:
+                if isinstance(item, dict):
+                    loc = ".".join(str(p) for p in item.get("loc", []) if p not in ("body",))
+                    msg = item.get("msg", "")
+                    parts.append(f"{loc}: {msg}".strip(": "))
+                else:
+                    parts.append(str(item))
+            return "; ".join(p for p in parts if p) or f"HTTP {resp.status_code}"
+        return str(detail) if detail else f"HTTP {resp.status_code}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        auth: bool = True,
+        _retry: bool = True,
+    ) -> Any:
+        url = f"{self.api_url}{API_PREFIX}{path}"
+        headers = self._auth_headers() if auth else {}
+        try:
+            resp = self._http.request(
+                method, url, json=json, params=params, data=data, headers=headers
+            )
+        except httpx.HTTPError as e:
+            raise ChatterMateError(f"Could not reach {self.api_url}: {e}") from e
+
+        if resp.status_code == 401 and auth and _retry and self._refresh():
+            return self.request(
+                method, path, json=json, params=params, data=data, auth=auth, _retry=False
+            )
+
+        if resp.status_code >= 400:
+            raise ChatterMateError(self._format_error(resp), resp.status_code)
+
+        if resp.status_code == 204 or not resp.content:
+            return None
+        ctype = resp.headers.get("content-type", "")
+        return resp.json() if "application/json" in ctype else resp.text
+
+    # -- auth --------------------------------------------------------------
+
+    def login(self, email: str, password: str) -> Dict[str, Any]:
+        data = self.request(
+            "POST", "/users/login",
+            data={"username": email, "password": password}, auth=False,
+        )
+        self.token = data.get("access_token")
+        self.refresh_token = data.get("refresh_token")
+        return data
+
+    def signup(
+        self, name: str, domain: str, admin_email: str, admin_name: str,
+        admin_password: str, timezone: str = "UTC",
+    ) -> Dict[str, Any]:
+        body = {
+            "name": name, "domain": domain, "timezone": timezone,
+            "admin_email": admin_email, "admin_name": admin_name,
+            "admin_password": admin_password,
+        }
+        data = self.request("POST", "/organizations", json=body, auth=False)
+        if isinstance(data, dict) and data.get("access_token"):
+            self.token = data.get("access_token")
+            self.refresh_token = data.get("refresh_token")
+        return data
+
+    def signup_request_otp(self, email: str) -> Dict[str, Any]:
+        """Enterprise signup step 1: request an email OTP (multi-org instances)."""
+        return self.request(
+            "POST", "/enterprise/signup/verify-email", json={"email": email}, auth=False
+        )
+
+    def signup_verify_otp(
+        self, email: str, otp: str, admin_name: str, admin_password: str,
+        organization_name: str, domain: str, colorcode: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Enterprise signup step 2: verify OTP and create the org + admin."""
+        body = {
+            "email": email, "otp": otp, "name": admin_name, "password": admin_password,
+            "organization_name": organization_name, "domain": domain,
+        }
+        if colorcode:
+            body["colorcode"] = colorcode
+        data = self.request("POST", "/enterprise/signup/verify-otp", json=body, auth=False)
+        if isinstance(data, dict) and data.get("access_token"):
+            self.token = data.get("access_token")
+            self.refresh_token = data.get("refresh_token")
+        return data
+
+    def whoami(self) -> Dict[str, Any]:
+        # No dedicated GET /me endpoint exists; an empty PATCH is a safe no-op that
+        # returns the authenticated user.
+        return self.request("PATCH", "/users/me", json={})
+
+    # -- personal access tokens -------------------------------------------
+
+    def create_pat(
+        self, name: str, scopes: Optional[List[str]] = None,
+        expires_in_days: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if scopes:
+            body["scopes"] = scopes
+        if expires_in_days is not None:
+            body["expires_in_days"] = expires_in_days
+        return self.request("POST", "/enterprise/tokens", json=body)
+
+    def list_pats(self) -> List[Dict[str, Any]]:
+        return self.request("GET", "/enterprise/tokens")
+
+    def revoke_pat(self, token_id: str) -> None:
+        return self.request("DELETE", f"/enterprise/tokens/{token_id}")
+
+    # -- agents ------------------------------------------------------------
+
+    def list_agents(self) -> Any:
+        return self.request("GET", "/agent/list")
+
+    def get_agent(self, agent_id: str) -> Any:
+        return self.request("GET", f"/agent/{agent_id}")
+
+    def create_agent(self, payload: Dict[str, Any]) -> Any:
+        return self.request("POST", "/agent", json=payload)
+
+    def update_agent(self, agent_id: str, payload: Dict[str, Any]) -> Any:
+        return self.request("PUT", f"/agent/{agent_id}", json=payload)
+
+    # -- workflows ---------------------------------------------------------
+
+    def get_workflow_for_agent(self, agent_id: str) -> Any:
+        return self.request("GET", f"/workflow/agent/{agent_id}")
+
+    def create_workflow(self, payload: Dict[str, Any]) -> Any:
+        return self.request("POST", "/workflow", json=payload)
+
+    def update_workflow(self, workflow_id: str, payload: Dict[str, Any]) -> Any:
+        return self.request("PUT", f"/workflow/{workflow_id}", json=payload)
+
+    def get_workflow_nodes(self, workflow_id: str) -> Any:
+        return self.request("GET", f"/workflow/{workflow_id}/nodes")
+
+    def update_workflow_nodes(self, workflow_id: str, payload: Dict[str, Any]) -> Any:
+        return self.request("PUT", f"/workflow/{workflow_id}/nodes", json=payload)
+
+    # -- knowledge ---------------------------------------------------------
+
+    def add_knowledge(
+        self, org_id: str, pdf_urls: Optional[List[str]] = None,
+        websites: Optional[List[str]] = None, agent_id: Optional[str] = None,
+    ) -> Any:
+        body: Dict[str, Any] = {
+            "org_id": org_id,
+            "pdf_urls": pdf_urls or [],
+            "websites": websites or [],
+        }
+        if agent_id:
+            body["agent_id"] = agent_id
+        return self.request("POST", "/knowledge/add/urls", json=body)
+
+    def list_knowledge_for_agent(self, agent_id: str) -> Any:
+        return self.request("GET", f"/knowledge/agent/{agent_id}")
+
+    def link_knowledge(self, knowledge_id: int, agent_id: str) -> Any:
+        return self.request(
+            "POST", "/knowledge/link",
+            params={"knowledge_id": knowledge_id, "agent_id": agent_id},
+        )
+
+    def unlink_knowledge(self, knowledge_id: int, agent_id: str) -> Any:
+        return self.request(
+            "DELETE", "/knowledge/unlink",
+            params={"knowledge_id": knowledge_id, "agent_id": agent_id},
+        )
+
+    def knowledge_queue_status(self, queue_id: int) -> Any:
+        return self.request("GET", f"/knowledge/queue/{queue_id}")

chattermate_cli/commands/__init__.py

@@ -0,0 +1,17 @@
+"""
+ChatterMate - CLI Commands
+Copyright (C) 2024 ChatterMate
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>
+"""

chattermate_cli/commands/agent.py

@@ -0,0 +1,122 @@
+"""
+ChatterMate - CLI Agent Commands
+Copyright (C) 2024 ChatterMate
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>
+"""
+
+from typing import List, Optional
+
+import typer
+from rich.table import Table
+
+from .. import config
+from ..context import console, get_client, output, print_error, run
+
+agent_app = typer.Typer(no_args_is_help=True, help="Create and manage AI agents.")
+
+
+@agent_app.command("list")
+def list_agents(as_json: bool = typer.Option(False, "--json", help="Output raw JSON.")):
+    """List the organization's agents."""
+    client = get_client()
+    data = run(client.list_agents)
+
+    def render(rows):
+        table = Table(title="Agents")
+        for col in ("id", "name", "type", "active"):
+            table.add_column(col)
+        for r in rows or []:
+            table.add_row(
+                str(r.get("id")), r.get("display_name") or r.get("name", ""),
+                str(r.get("agent_type", "")), "yes" if r.get("is_active") else "no",
+            )
+        console.print(table)
+
+    output(data, as_json, render)
+
+
+@agent_app.command("get")
+def get_agent(
+    agent_id: str = typer.Argument(..., help="Agent id."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON."),
+):
+    """Show a single agent."""
+    client = get_client()
+    output(run(lambda: client.get_agent(agent_id)), as_json)
+
+
+@agent_app.command("create")
+def create_agent(
+    name: str = typer.Option(..., "--name", help="Agent name."),
+    agent_type: str = typer.Option(
+        "custom", "--type",
+        help="Agent type: customer_support, sales, tech_support, general, custom (case-insensitive).",
+    ),
+    instruction: List[str] = typer.Option(
+        [], "--instruction", "-i", help="An instruction line (repeatable)."
+    ),
+    description: Optional[str] = typer.Option(None, "--description"),
+    display_name: Optional[str] = typer.Option(None, "--display-name"),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON."),
+):
+    """Create an agent. Organization is taken from your stored session."""
+    org_id = config.load_config().get("organization_id")
+    if not org_id:
+        print_error("No organization in session. Run 'chattermate login' or 'whoami' first.")
+        raise typer.Exit(code=1)
+    payload = {
+        "name": name,
+        # API enum values are lowercase (customer_support, sales, ...); normalize for convenience.
+        "agent_type": agent_type.lower(),
+        "instructions": list(instruction) or [f"You are {name}, a helpful assistant."],
+        "organization_id": org_id,
+    }
+    if description is not None:
+        payload["description"] = description
+    if display_name is not None:
+        payload["display_name"] = display_name
+    client = get_client()
+    data = run(lambda: client.create_agent(payload))
+    if not as_json:
+        console.print(f"[green]Created agent[/green] {data.get('id')} ({name})")
+    output(data, as_json)
+
+
+@agent_app.command("update")
+def update_agent(
+    agent_id: str = typer.Argument(..., help="Agent id."),
+    instruction: List[str] = typer.Option(
+        [], "--instruction", "-i", help="Replace instructions (repeatable)."
+    ),
+    display_name: Optional[str] = typer.Option(None, "--display-name"),
+    active: Optional[bool] = typer.Option(None, "--active/--inactive"),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON."),
+):
+    """Update an agent's instructions, display name, or active state."""
+    payload: dict = {}
+    if instruction:
+        payload["instructions"] = list(instruction)
+    if display_name is not None:
+        payload["display_name"] = display_name
+    if active is not None:
+        payload["is_active"] = active
+    if not payload:
+        print_error("Nothing to update. Pass --instruction, --display-name or --active/--inactive.")
+        raise typer.Exit(code=1)
+    client = get_client()
+    data = run(lambda: client.update_agent(agent_id, payload))
+    if not as_json:
+        console.print(f"[green]Updated agent[/green] {agent_id}")
+    output(data, as_json)

chattermate_cli/commands/auth.py

@@ -0,0 +1,202 @@
+"""
+ChatterMate - CLI Auth & Token Commands
+Copyright (C) 2024 ChatterMate
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>
+"""
+
+import json
+from typing import Optional
+
+import typer
+from rich.table import Table
+
+from .. import config
+from ..context import console, get_client, output, print_error, run
+
+token_app = typer.Typer(no_args_is_help=True, help="Manage personal access tokens (PATs).")
+
+
+def _store_session(client, user: dict) -> None:
+    config.update_config(
+        api_url=client.api_url,
+        access_token=client.token,
+        refresh_token=client.refresh_token,
+        user_id=str(user.get("id")) if user.get("id") else None,
+        organization_id=str(user.get("organization_id")) if user.get("organization_id") else None,
+        email=user.get("email"),
+    )
+
+
+def login(
+    email: str = typer.Option(..., "--email", "-e", prompt=True, help="Account email."),
+    password: str = typer.Option(
+        ..., "--password", "-p", prompt=True, hide_input=True, help="Account password."
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON."),
+):
+    """Log in and store JWT credentials in ~/.chattermate/config.json."""
+    client = get_client(require_auth=False)
+    data = run(lambda: client.login(email, password))
+    user = data.get("user", {}) if isinstance(data, dict) else {}
+    _store_session(client, user)
+    if as_json:
+        output(data, True)
+    else:
+        console.print(f"[green]Logged in[/green] as {user.get('email', email)}")
+        console.print("Tip: create a long-lived token for AI agents with 'chattermate token create'.")
+
+
+def signup(
+    name: str = typer.Option(..., "--name", prompt=True, help="Organization name."),
+    domain: str = typer.Option(..., "--domain", prompt=True, help="Organization domain, e.g. acme.com."),
+    admin_email: str = typer.Option(..., "--admin-email", prompt=True, help="Admin email."),
+    admin_name: str = typer.Option(..., "--admin-name", prompt=True, help="Admin full name."),
+    admin_password: str = typer.Option(
+        ..., "--admin-password", prompt=True, hide_input=True, confirmation_prompt=True,
+        help="Admin password.",
+    ),
+    timezone: str = typer.Option("UTC", "--timezone", help="Organization timezone."),
+    enterprise: bool = typer.Option(
+        False, "--enterprise",
+        help="Use the enterprise OTP signup flow (multi-org instances).",
+    ),
+    otp: Optional[str] = typer.Option(
+        None, "--otp",
+        help="OTP for --enterprise signup. If omitted you'll be prompted (localhost test OTP is 123456).",
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON."),
+):
+    """Create a new organization and admin user.
+
+    Default is community signup (single-org). Use --enterprise for the OTP-based
+    multi-org flow available on enterprise instances.
+    """
+    client = get_client(require_auth=False)
+
+    if enterprise:
+        run(lambda: client.signup_request_otp(admin_email))
+        if not otp:
+            otp = typer.prompt("Enter the OTP sent to your email (localhost test OTP: 123456)")
+        data = run(lambda: client.signup_verify_otp(
+            email=admin_email, otp=otp, admin_name=admin_name,
+            admin_password=admin_password, organization_name=name, domain=domain,
+        ))
+        user = data.get("user", {}) if isinstance(data, dict) else {}
+        if client.token:
+            _store_session(client, user or {"organization_id": None, "email": admin_email})
+    else:
+        data = run(lambda: client.signup(
+            name=name, domain=domain, admin_email=admin_email,
+            admin_name=admin_name, admin_password=admin_password, timezone=timezone,
+        ))
+        if isinstance(data, dict) and client.token:
+            _store_session(client, {
+                "id": None,
+                "organization_id": data.get("id"),
+                "email": admin_email,
+            })
+
+    if as_json:
+        output(data, True)
+    else:
+        console.print(f"[green]Organization created:[/green] {name} ({domain})")
+        if client.token:
+            console.print("You are now logged in.")
+
+
+def logout():
+    """Remove stored credentials."""
+    config.clear_auth()
+    console.print("[green]Logged out.[/green] Stored credentials removed.")
+
+
+def whoami(as_json: bool = typer.Option(False, "--json", help="Output raw JSON.")):
+    """Show the currently authenticated user."""
+    client = get_client()
+    data = run(client.whoami)
+
+    def render(d):
+        role = d.get("role") or {}
+        console.print(f"[bold]{d.get('full_name') or d.get('email')}[/bold]")
+        console.print(f"  email:        {d.get('email')}")
+        console.print(f"  user id:      {d.get('id')}")
+        console.print(f"  organization: {d.get('organization_id')}")
+        console.print(f"  role:         {role.get('name', '-')}")
+
+    output(data, as_json, render)
+
+
+@token_app.command("create")
+def token_create(
+    name: str = typer.Argument(..., help="A label for the token, e.g. 'laptop-cli'."),
+    expires_in_days: Optional[int] = typer.Option(
+        None, "--expires-in-days", help="Days until expiry. Omit for a non-expiring token."
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON."),
+):
+    """Create a Personal Access Token. The secret is shown ONCE."""
+    client = get_client()
+    data = run(lambda: client.create_pat(name=name, expires_in_days=expires_in_days))
+    if as_json:
+        output(data, True)
+        return
+    token = data.get("token", "")
+    console.print(f"[green]Created token[/green] '{name}'.")
+    console.print("[bold yellow]Store it now — it will not be shown again:[/bold yellow]")
+    console.print(f"\n  {token}\n")
+    env = {"CHATTERMATE_TOKEN": token}
+    # Only include the API URL when it isn't the default hosted endpoint.
+    if client.api_url.rstrip("/") != config.DEFAULT_API_URL.rstrip("/"):
+        env["CHATTERMATE_API_URL"] = client.api_url
+    snippet = {
+        "mcpServers": {
+            "chattermate": {
+                "command": "uvx",
+                "args": ["--from", "chattermate-cli", "chattermate-mcp"],
+                "env": env,
+            }
+        }
+    }
+    console.print("MCP client config (paste into your AI agent):")
+    console.print(json.dumps(snippet, indent=2))
+
+
+@token_app.command("list")
+def token_list(as_json: bool = typer.Option(False, "--json", help="Output raw JSON.")):
+    """List your personal access tokens."""
+    client = get_client()
+    data = run(client.list_pats)
+
+    def render(rows):
+        table = Table(title="Personal Access Tokens")
+        for col in ("id", "name", "prefix", "expires_at", "last_used_at", "active"):
+            table.add_column(col)
+        for r in rows or []:
+            table.add_row(
+                str(r.get("id")), r.get("name", ""), r.get("token_prefix", ""),
+                str(r.get("expires_at") or "never"), str(r.get("last_used_at") or "-"),
+                "yes" if r.get("is_active") else "no",
+            )
+        console.print(table)
+
+    output(data, as_json, render)
+
+
+@token_app.command("revoke")
+def token_revoke(token_id: str = typer.Argument(..., help="The token id to revoke.")):
+    """Revoke (delete) a personal access token."""
+    client = get_client()
+    run(lambda: client.revoke_pat(token_id))
+    console.print(f"[green]Revoked[/green] token {token_id}")