chattermate-cli 0.2.0__tar.gz

chattermate_cli-0.2.0/LICENSE

@@ -0,0 +1,18 @@
+ChatterMate CLI (chattermate-cli)
+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/>.
+
+The full text of the GNU Affero General Public License v3.0 is available at:
+https://www.gnu.org/licenses/agpl-3.0.txt

chattermate_cli-0.2.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: chattermate-cli
+Version: 0.2.0
+Summary: ChatterMate CLI and MCP server — sign up, authenticate, and configure agents, workflows and knowledge from the terminal or an AI agent.
+Author: ChatterMate
+License: AGPL-3.0-or-later
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: mcp>=1.2
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: respx>=0.21; extra == "test"
+Dynamic: license-file
+
+# ChatterMate CLI & MCP server
+
+`chattermate-cli` provides a command-line client and an MCP (Model Context Protocol)
+server for ChatterMate. A human can sign up, log in and configure agents, workflows and
+knowledge from the terminal; an AI agent can do the same through the MCP server.
+
+This is an **enterprise** feature and depends on the enterprise backend's Personal Access
+Tokens (PATs).
+
+## Install
+
+```bash
+pip install -e .            # from this directory, for development
+# or, once published:
+pipx install chattermate-cli
+```
+
+Console scripts installed: `chattermate` (alias `cmate`) and `chattermate-mcp`.
+
+## Configure the API endpoint
+
+By default the CLI talks to the hosted API at `https://api.chattermate.chat`. To target a
+local or self-hosted backend, set `CHATTERMATE_API_URL=http://localhost:8000` (or pass
+`--api-url`). Resolution order: `--api-url` flag → `CHATTERMATE_API_URL` env → stored config →
+`https://api.chattermate.chat`.
+
+## Quick start (human)
+
+```bash
+# Create an organization + admin (community signup), or log in to an existing one
+chattermate signup
+chattermate login --email you@acme.com
+
+chattermate whoami
+
+# Mint a long-lived Personal Access Token for CI / AI agents (shown once!)
+chattermate token create laptop-cli
+chattermate token list
+chattermate token revoke <token-id>
+
+# Configure resources
+chattermate agent list
+chattermate agent create --name "Support" --type CUSTOMER_SUPPORT -i "Be concise"
+chattermate workflow get <agent-id>
+chattermate workflow create --agent-id <agent-id> --name "Onboarding"
+chattermate knowledge add-url --website https://docs.acme.com --agent-id <agent-id>
+chattermate knowledge status <queue-id>
+```
+
+Every command accepts `--json` for machine-readable output.
+
+## Authentication
+
+Two credentials are supported:
+
+- **Personal Access Token** (`cmat_...`) — preferred for non-interactive use. Pass it via
+  the `CHATTERMATE_TOKEN` environment variable. Long-lived and revocable.
+- **JWT login** — `chattermate login` stores access + refresh tokens in
+  `~/.chattermate/config.json` (mode `600`) and refreshes automatically.
+
+## MCP server (AI agents)
+
+`chattermate-mcp` is a stdio MCP server. Point your MCP client at it with a PAT:
+
+```json
+{
+  "mcpServers": {
+    "chattermate": {
+      "command": "uvx",
+      "args": ["--from", "chattermate-cli", "chattermate-mcp"],
+      "env": {
+        "CHATTERMATE_TOKEN": "cmat_...",
+        "CHATTERMATE_API_URL": "https://your-chattermate-host"
+      }
+    }
+  }
+}
+```
+
+`chattermate token create` prints a ready-to-paste version of this snippet.
+
+### Tools
+
+Read-only: `whoami`, `list_agents`, `get_agent`, `get_workflow`, `get_workflow_nodes`,
+`list_knowledge`, `get_ingestion_status`.
+
+Mutating: `create_agent`, `update_agent`, `create_workflow`, `update_workflow`,
+`update_workflow_nodes`, `add_knowledge_url`, `link_knowledge`, `unlink_knowledge`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest tests/
+```

chattermate_cli-0.2.0/README.md

@@ -0,0 +1,95 @@
+# ChatterMate CLI & MCP server
+
+`chattermate-cli` provides a command-line client and an MCP (Model Context Protocol)
+server for ChatterMate. A human can sign up, log in and configure agents, workflows and
+knowledge from the terminal; an AI agent can do the same through the MCP server.
+
+This is an **enterprise** feature and depends on the enterprise backend's Personal Access
+Tokens (PATs).
+
+## Install
+
+```bash
+pip install -e .            # from this directory, for development
+# or, once published:
+pipx install chattermate-cli
+```
+
+Console scripts installed: `chattermate` (alias `cmate`) and `chattermate-mcp`.
+
+## Configure the API endpoint
+
+By default the CLI talks to the hosted API at `https://api.chattermate.chat`. To target a
+local or self-hosted backend, set `CHATTERMATE_API_URL=http://localhost:8000` (or pass
+`--api-url`). Resolution order: `--api-url` flag → `CHATTERMATE_API_URL` env → stored config →
+`https://api.chattermate.chat`.
+
+## Quick start (human)
+
+```bash
+# Create an organization + admin (community signup), or log in to an existing one
+chattermate signup
+chattermate login --email you@acme.com
+
+chattermate whoami
+
+# Mint a long-lived Personal Access Token for CI / AI agents (shown once!)
+chattermate token create laptop-cli
+chattermate token list
+chattermate token revoke <token-id>
+
+# Configure resources
+chattermate agent list
+chattermate agent create --name "Support" --type CUSTOMER_SUPPORT -i "Be concise"
+chattermate workflow get <agent-id>
+chattermate workflow create --agent-id <agent-id> --name "Onboarding"
+chattermate knowledge add-url --website https://docs.acme.com --agent-id <agent-id>
+chattermate knowledge status <queue-id>
+```
+
+Every command accepts `--json` for machine-readable output.
+
+## Authentication
+
+Two credentials are supported:
+
+- **Personal Access Token** (`cmat_...`) — preferred for non-interactive use. Pass it via
+  the `CHATTERMATE_TOKEN` environment variable. Long-lived and revocable.
+- **JWT login** — `chattermate login` stores access + refresh tokens in
+  `~/.chattermate/config.json` (mode `600`) and refreshes automatically.
+
+## MCP server (AI agents)
+
+`chattermate-mcp` is a stdio MCP server. Point your MCP client at it with a PAT:
+
+```json
+{
+  "mcpServers": {
+    "chattermate": {
+      "command": "uvx",
+      "args": ["--from", "chattermate-cli", "chattermate-mcp"],
+      "env": {
+        "CHATTERMATE_TOKEN": "cmat_...",
+        "CHATTERMATE_API_URL": "https://your-chattermate-host"
+      }
+    }
+  }
+}
+```
+
+`chattermate token create` prints a ready-to-paste version of this snippet.
+
+### Tools
+
+Read-only: `whoami`, `list_agents`, `get_agent`, `get_workflow`, `get_workflow_nodes`,
+`list_knowledge`, `get_ingestion_status`.
+
+Mutating: `create_agent`, `update_agent`, `create_workflow`, `update_workflow`,
+`update_workflow_nodes`, `add_knowledge_url`, `link_knowledge`, `unlink_knowledge`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest tests/
+```

chattermate_cli-0.2.0/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-0.2.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-0.2.0/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-0.2.0/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)