codini 0.2.0__py3-none-any.whl

codini/__init__.py

@@ -0,0 +1,298 @@
+"""
+Codini Python SDK
+
+Official Python SDK for the Codini AI API.
+Build, manage, and execute AI flows programmatically.
+
+    pip install codini
+
+Usage:
+    from codini import CodiniClient
+
+    codini = CodiniClient("your-api-key")
+    result = codini.sync_execute(1, input="Hello")
+"""
+
+from __future__ import annotations
+
+import time
+import json
+from typing import Any, Optional
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+
+
+class CodiniAPIError(Exception):
+    """Raised when the Codini API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"Codini API error ({status_code}): {message}")
+
+
+def _request(base_url: str, headers: dict, path: str, method: str = "GET", body: Any = None) -> Any:
+    url = f"{base_url}{path}"
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+
+    req = Request(url, data=data, headers=headers, method=method)
+
+    try:
+        with urlopen(req) as resp:
+            content = resp.read().decode("utf-8")
+            if content:
+                return json.loads(content)
+            return {}
+    except HTTPError as e:
+        error_body = e.read().decode("utf-8")
+        try:
+            error_data = json.loads(error_body)
+            msg = error_data.get("message") or error_data.get("error") or e.reason
+        except (json.JSONDecodeError, ValueError):
+            msg = e.reason
+        raise CodiniAPIError(e.code, msg) from None
+
+
+class ProjectsAPI:
+    """Manage projects that contain flows."""
+
+    def __init__(self, base_url: str, headers: dict):
+        self._base_url = base_url
+        self._headers = headers
+
+    def _req(self, path: str, method: str = "GET", body: Any = None) -> Any:
+        return _request(self._base_url, self._headers, path, method, body)
+
+    def list(self) -> dict:
+        """List all projects."""
+        return self._req("/projects/list/", "GET")
+
+    def create(self, name: str, description: str = "") -> dict:
+        """Create a new project."""
+        return self._req("/projects/create/", "POST", {"name": name, "description": description})
+
+    def get(self, project_id: int) -> dict:
+        """Get project details including its flows."""
+        return self._req(f"/projects/{project_id}/", "GET")
+
+    def update(self, project_id: int, name: str = None, description: str = None) -> dict:
+        """Update project name and/or description."""
+        body = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        return self._req(f"/projects/{project_id}/update/", "POST", body)
+
+    def delete(self, project_id: int) -> dict:
+        """Delete a project and all its flows."""
+        return self._req(f"/projects/{project_id}/delete/", "DELETE")
+
+
+class FlowsAPI:
+    """Manage flows — CRUD, programmatic building, and node catalog."""
+
+    def __init__(self, base_url: str, headers: dict):
+        self._base_url = base_url
+        self._headers = headers
+
+    def _req(self, path: str, method: str = "GET", body: Any = None) -> Any:
+        return _request(self._base_url, self._headers, path, method, body)
+
+    def list(self, project_id: int = None) -> dict:
+        """List flows. Pass project_id to filter, or omit for all flows."""
+        body = {"project_id": project_id} if project_id else None
+        return self._req("/flows/list/", "POST", body)
+
+    def get(self, flow_id: int) -> dict:
+        """Get full flow details including nodes and edges."""
+        return self._req(f"/flows/{flow_id}/", "POST")
+
+    def create(self, name: str, project_id: int, description: str = "") -> dict:
+        """Create a new empty flow within a project."""
+        return self._req("/flows/create/", "POST", {
+            "name": name,
+            "project_id": project_id,
+            "description": description,
+        })
+
+    def update_details(self, flow_id: int, name: str = None, description: str = None) -> dict:
+        """Update flow name and/or description."""
+        body = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        return self._req(f"/flows/{flow_id}/update-details/", "POST", body)
+
+    def save(self, flow_id: int, nodes: list, edges: list, name: str = None, description: str = None, ui_state: dict = None) -> dict:
+        """Save full flow state — replaces all nodes and edges."""
+        body: dict[str, Any] = {"nodes": nodes, "edges": edges}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if ui_state is not None:
+            body["ui_state"] = ui_state
+        return self._req(f"/flows/{flow_id}/update/", "POST", body)
+
+    def delete(self, flow_id: int) -> dict:
+        """Delete a flow."""
+        return self._req(f"/flows/{flow_id}/delete/", "DELETE")
+
+    def add_nodes(self, flow_id: int, nodes: list[dict]) -> dict:
+        """
+        Programmatically add nodes to a flow. Appends without deleting existing nodes.
+
+        Each node: {"type": "create-agent", "position": {"x": 0, "y": 0}, "params": {"name": "...", ...}}
+
+        Returns created node IDs.
+        """
+        return self._req("/flows/create-api/", "POST", {
+            "flow_id": flow_id,
+            "nodes": nodes,
+            "edges": [],
+        })
+
+    def add_edges(self, flow_id: int, edges: list[dict]) -> dict:
+        """
+        Programmatically add edges between existing nodes.
+
+        Each edge: {"source": "node-id", "target": "node-id", "sourceHandle": "...", "targetHandle": "..."}
+        """
+        return self._req("/flows/create-api/", "POST", {
+            "flow_id": flow_id,
+            "nodes": [],
+            "edges": edges,
+        })
+
+    def build(self, flow_id: int, nodes: list[dict], edges: list[dict]) -> dict:
+        """Add both nodes and edges in a single call."""
+        return self._req("/flows/create-api/", "POST", {
+            "flow_id": flow_id,
+            "nodes": nodes,
+            "edges": edges,
+        })
+
+    def list_node_types(self) -> list:
+        """List all available node types with their categories."""
+        return self._req("/flow-nodes/types", "GET")
+
+    def get_node_definitions(self, node_types: list[str]) -> list:
+        """Fetch full definitions for specific node types."""
+        return self._req("/flow-nodes/select-types", "POST", {
+            "node_types": node_types,
+        })
+
+
+class SecretsAPI:
+    """Store and retrieve credentials for use in flow nodes."""
+
+    def __init__(self, base_url: str, headers: dict):
+        self._base_url = base_url
+        self._headers = headers
+
+    def _req(self, path: str, method: str = "GET", body: Any = None) -> Any:
+        return _request(self._base_url, self._headers, path, method, body)
+
+    def list(self) -> dict:
+        """List all secrets."""
+        return self._req("/secrets/", "POST")
+
+    def create(self, secret_name: str, secret_data: str) -> dict:
+        """Create or update a secret."""
+        return self._req("/secrets/create/", "POST", {
+            "secret_name": secret_name,
+            "secret_data": secret_data,
+        })
+
+    def get(self, secret_name: str) -> dict:
+        """Retrieve a secret value by name."""
+        return self._req(f"/secrets/{secret_name}/", "GET")
+
+    def delete(self, secret_name: str) -> dict:
+        """Delete a secret by name."""
+        return self._req(f"/secrets/{secret_name}/delete/", "DELETE")
+
+
+class CodiniClient:
+    """
+    Codini API client — server-side, requires an API key.
+
+    Usage:
+        codini = CodiniClient("your-api-key")
+
+        # Execute flows
+        result = codini.sync_execute(1, input="Hello")
+
+        # Manage projects and flows
+        codini.projects.create("My App")
+        codini.flows.build(flow_id, nodes, edges)
+
+        # Store secrets
+        codini.secrets.create("my_key", "my_value")
+    """
+
+    def __init__(self, api_key: str, base_url: str = "http://api.codini.ai.local/api/v1"):
+        self._base_url = base_url
+        self._headers = {
+            "Content-Type": "application/json",
+            "Authorization": api_key,
+        }
+
+        self.projects = ProjectsAPI(base_url, self._headers)
+        self.flows = FlowsAPI(base_url, self._headers)
+        self.secrets = SecretsAPI(base_url, self._headers)
+
+    def _req(self, path: str, method: str = "GET", body: Any = None) -> Any:
+        return _request(self._base_url, self._headers, path, method, body)
+
+    # ---- Tickets ----
+
+    def create_ticket(self, **kwargs) -> dict:
+        """
+        Create an execution ticket for client use.
+
+        Required: flow_id
+        Optional: use_websocket, allowed_flows, rpm, max_runs,
+                  max_credits_usage, expires_in_seconds, single_use,
+                  input, variables, webhook_url, webhook_events_subscribed,
+                  webhook_secret, metadata
+        """
+        return self._req("/execution-tickets/create/", "POST", kwargs)
+
+    # ---- Execution ----
+
+    def sync_execute(self, flow_id: int, input: str = None, variables: dict = None, timeout: int = None) -> dict:
+        """Execute a flow synchronously — blocks until complete."""
+        body: dict[str, Any] = {}
+        if input is not None:
+            body["input"] = input
+        if variables is not None:
+            body["variables"] = variables
+        if timeout is not None:
+            body["timeout"] = timeout
+        return self._req(f"/flows/{flow_id}/execute-sync/", "POST", body)
+
+    def async_execute(self, flow_id: int, input: str = None, variables: dict = None) -> dict:
+        """Execute a flow asynchronously — returns immediately with a run_id."""
+        body: dict[str, Any] = {}
+        if input is not None:
+            body["input"] = input
+        if variables is not None:
+            body["variables"] = variables
+        return self._req(f"/flows/{flow_id}/execute/", "POST", body)
+
+    def get_run_status(self, run_id: int) -> dict:
+        """Get the status of a run."""
+        return self._req(f"/runs/{run_id}/", "GET")
+
+    def poll_run_status(self, run_id: int, interval: float = 2.0, max_attempts: int = 150) -> dict:
+        """Poll a run until it completes or fails."""
+        for _ in range(max_attempts):
+            result = self.get_run_status(run_id)
+            status = result.get("data", {}).get("run_status")
+            if status in ("COMPLETED", "FAILED"):
+                return result
+            time.sleep(interval)
+        raise TimeoutError(f"Polling timed out after {max_attempts} attempts for run {run_id}")

codini-0.2.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: codini
+Version: 0.2.0
+Summary: Official Python SDK for the Codini AI API
+License: ISC
+Project-URL: Homepage, https://codini.ai
+Project-URL: Repository, https://github.com/codini/codini-python
+Project-URL: Documentation, https://www.npmjs.com/package/codini
+Keywords: codini,ai,sdk,api,flows,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# codini
+
+Official Python SDK for the [Codini AI](https://codini.ai) API.
+
+Build, manage, and execute AI flows programmatically. Zero dependencies.
+
+## Install
+
+```bash
+pip install codini
+```
+
+## Quick Start
+
+```python
+from codini import CodiniClient
+
+codini = CodiniClient("your-api-key")
+
+# Execute a flow
+result = codini.sync_execute(1, input="Hello")
+print(result["data"]["output"])
+
+# Build a flow programmatically
+project = codini.projects.create("My App")
+flow = codini.flows.create("Chat Agent", project["data"]["id"])
+
+nodes = codini.flows.add_nodes(flow["data"]["id"], [
+    {"type": "onMessageTrigger", "position": {"x": 0, "y": 200}},
+    {"type": "create-agent", "position": {"x": 300, "y": 200}, "params": {
+        "name": "Assistant", "model": "gpt-4o", "type": "auto",
+        "role description": "Helpful assistant"
+    }},
+    {"type": "replyToChat", "position": {"x": 600, "y": 200}},
+])
+
+trigger, agent, reply = nodes["data"]["nodes"]
+codini.flows.add_edges(flow["data"]["id"], [
+    {"source": trigger["id"], "target": agent["id"]},
+    {"source": agent["id"], "target": reply["id"]},
+])
+```
+
+## API
+
+### Execution
+
+```python
+codini.create_ticket(flow_id=1, use_websocket=True)
+codini.sync_execute(flow_id, input="Hello", variables={"lang": "en"})
+codini.async_execute(flow_id, input="Hello")
+codini.get_run_status(run_id)
+codini.poll_run_status(run_id, interval=2.0, max_attempts=150)
+```
+
+### Projects
+
+```python
+codini.projects.list()
+codini.projects.create("My App", description="Optional")
+codini.projects.get(project_id)
+codini.projects.update(project_id, name="New Name")
+codini.projects.delete(project_id)
+```
+
+### Flows
+
+```python
+codini.flows.list()                    # All flows
+codini.flows.list(project_id=38)       # Flows in a project
+codini.flows.get(flow_id)
+codini.flows.create("My Flow", project_id=38)
+codini.flows.update_details(flow_id, name="New Name")
+codini.flows.delete(flow_id)
+
+# Programmatic building
+codini.flows.add_nodes(flow_id, [{...}])
+codini.flows.add_edges(flow_id, [{...}])
+codini.flows.build(flow_id, nodes, edges)
+
+# Node catalog
+codini.flows.list_node_types()
+codini.flows.get_node_definitions(["create-agent", "chat-memory"])
+
+# Full canvas save
+codini.flows.save(flow_id, nodes=[...], edges=[...])
+```
+
+### Secrets
+
+```python
+codini.secrets.list()
+codini.secrets.create("my_key", "my_value")
+codini.secrets.get("my_key")
+codini.secrets.delete("my_key")
+```
+
+## Zero Dependencies
+
+Uses only Python standard library (`urllib`, `json`). No `requests` needed.
+
+## Requirements
+
+Python 3.8+
+
+## License
+
+ISC

codini-0.2.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+codini/__init__.py,sha256=QRzNlfn6o5AavXj801bIlKsq38Z8io9CCTQiGYHzvn4,10815
+codini-0.2.0.dist-info/METADATA,sha256=EYz_IntizJyouwxLCKIA1r6C-tffVntEFgx_Mnc60Ac,3398
+codini-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codini-0.2.0.dist-info/top_level.txt,sha256=R-mw0grWxVWM9zmD5KX9MjWO5DLGTrPeEq10WymgtYw,7
+codini-0.2.0.dist-info/RECORD,,

codini-0.2.0.dist-info/WHEEL

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

codini-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+codini