cortexflow-sdk 0.1.0__py3-none-any.whl

cortexflow_sdk/__init__.py

@@ -0,0 +1,38 @@
+"""cortexflow-sdk — typed interfaces for building CortexFlow plugins.
+
+Install this package (not the full ``cortexflow`` gateway) to write a
+plugin, tool, or channel adapter that CortexFlow can load::
+
+    pip install cortexflow-sdk
+
+Then subclass one of:
+
+    Plugin          — the entry point every plugin package registers
+    Tool            — a discrete capability the agent can invoke
+    ChannelAdapter  — a messaging platform integration
+
+See https://github.com/TheAmitChandra/CortexFlow for the full gateway
+and plugin-loading documentation.
+"""
+
+from cortexflow_sdk.channels import (
+    Attachment,
+    ChannelAdapter,
+    InboundMessage,
+    MessageHandler,
+)
+from cortexflow_sdk.plugins import Plugin, PluginMetadata
+from cortexflow_sdk.tools import Tool, ToolResult
+
+__all__ = [
+    "Attachment",
+    "ChannelAdapter",
+    "InboundMessage",
+    "MessageHandler",
+    "Plugin",
+    "PluginMetadata",
+    "Tool",
+    "ToolResult",
+]
+
+__version__ = "0.1.0"

cortexflow_sdk/channels.py

@@ -0,0 +1,99 @@
+"""Channel adapter abstract base class and shared data types."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+
+@dataclass
+class Attachment:
+    """A file or media attachment from a channel message."""
+
+    type: str  # "image" | "audio" | "video" | "document"
+    url: str | None = None
+    data: bytes | None = None
+    filename: str | None = None
+    mime_type: str | None = None
+
+
+@dataclass
+class InboundMessage:
+    """Normalised inbound message from any channel adapter."""
+
+    channel: str
+    sender_id: str
+    sender_name: str
+    text: str | None
+    attachments: list[Attachment] = field(default_factory=list)
+    thread_id: str | None = None
+    reply_to_id: str | None = None
+    timestamp: float = field(default_factory=time.time)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+#: A coroutine function that handles an inbound message.
+MessageHandler = Callable[[InboundMessage], Awaitable[None]]
+
+
+class ChannelAdapter(ABC):
+    """Abstract base for all platform channel adapters.
+
+    Subclasses must set ``channel_id`` as a class attribute and implement
+    ``connect``, ``disconnect``, and ``send``.
+    """
+
+    channel_id: str  # e.g. "telegram" | "discord" | "slack"
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self._handler: MessageHandler | None = None
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish connection to the platform. Raises on failure."""
+        ...
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Gracefully disconnect from the platform."""
+        ...
+
+    @abstractmethod
+    async def send(
+        self,
+        target: str,
+        text: str,
+        *,
+        reply_to: str | None = None,
+        attachments: list[Attachment] | None = None,
+    ) -> str | None:
+        """Send a message to *target* (platform-specific ID).
+
+        Returns the sent message ID if the platform provides one.
+        """
+        ...
+
+    def on_message(self, handler: MessageHandler) -> None:
+        """Register the handler that receives all inbound messages."""
+        self._handler = handler
+
+    async def _dispatch(self, message: InboundMessage) -> None:
+        """Forward *message* to the registered handler (if any)."""
+        if self._handler is not None:
+            await self._handler(message)
+
+    def get_config_schema(self) -> dict[str, Any]:
+        """Return a JSON Schema describing this adapter's config options."""
+        return {
+            "type": "object",
+            "properties": {
+                "enabled": {"type": "boolean", "default": False},
+            },
+            "required": [],
+        }
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(channel_id={self.channel_id!r})"

cortexflow_sdk/plugins.py

@@ -0,0 +1,101 @@
+"""Plugin base class — the contract every CortexFlow plugin must satisfy.
+
+A plugin is a Python package installed via ``pip install <name>`` that:
+  - Declares a ``cortexflow.plugins`` entry point pointing to a Plugin subclass
+  - Provides one or more tools, channel adapters, or TTS/STT backends
+  - Declares its capabilities and required permissions upfront
+
+Plugin types:
+    "tool"      — adds Tool instances to the gateway's ToolRegistry
+    "channel"   — adds a ChannelAdapter to the gateway
+    "tts"       — alternative TTS backend
+    "stt"       — alternative STT backend
+    "memory"    — alternative memory tier
+    "generic"   — anything else (lifecycle hooks, middleware)
+
+Example plugin (in a separate package)::
+
+    # cortexflow_github/plugin.py
+    from cortexflow_sdk import Plugin, PluginMetadata
+
+    class GitHubPlugin(Plugin):
+        metadata = PluginMetadata(
+            name="cortexflow-github",
+            version="1.0.0",
+            plugin_type="tool",
+            description="GitHub integration — PRs, issues, commits",
+            permissions=["network"],
+        )
+
+        def get_tools(self):
+            from .tools import GitHubTool
+            return [GitHubTool()]
+
+    # In pyproject.toml:
+    # [project.entry-points."cortexflow.plugins"]
+    # cortexflow-github = "cortexflow_github.plugin:GitHubPlugin"
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from cortexflow_sdk.channels import ChannelAdapter
+    from cortexflow_sdk.tools import Tool
+
+
+@dataclass
+class PluginMetadata:
+    """Metadata that every plugin must declare."""
+
+    name: str
+    version: str
+    plugin_type: str  # "tool" | "channel" | "tts" | "stt" | "memory" | "generic"
+    description: str
+    permissions: list[str] = field(default_factory=list)
+    author: str = ""
+    homepage: str = ""
+
+
+class Plugin(ABC):
+    """Abstract base for all CortexFlow plugins.
+
+    Subclass this and implement the methods that apply to your plugin_type.
+    Unimplemented optional methods return empty lists/None by default.
+    """
+
+    metadata: PluginMetadata
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def on_load(self) -> None:
+        """Called once when the plugin is loaded. Perform async init here."""
+
+    async def on_unload(self) -> None:
+        """Called when the plugin is unloaded (e.g. on gateway shutdown)."""
+
+    # ------------------------------------------------------------------
+    # Type-specific contribution methods
+    # ------------------------------------------------------------------
+
+    def get_tools(self) -> list["Tool"]:
+        """Return Tool instances contributed by this plugin (type=tool)."""
+        return []
+
+    def get_channel_adapter(self) -> "ChannelAdapter | None":
+        """Return a ChannelAdapter contributed by this plugin (type=channel)."""
+        return None
+
+    def get_config_schema(self) -> dict[str, Any]:
+        """Return JSON Schema for plugin-specific config options."""
+        return {"type": "object", "properties": {}}
+
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f"Plugin({self.metadata.name!r} v{self.metadata.version}, type={self.metadata.plugin_type!r})"

cortexflow_sdk/tools.py

@@ -0,0 +1,116 @@
+"""Tool abstract base class and shared data types.
+
+A Tool is a discrete capability an agent can invoke during a pipeline run.
+Tools are:
+  - Declared with a name, description, and typed parameter schema
+  - Invoked with a plain dict of arguments
+  - Sandboxed: each tool declares what permissions it needs
+  - Stateless: tools must not store state between calls
+
+Tool authors subclass ``Tool`` and implement ``execute``.
+
+Example::
+
+    from cortexflow_sdk import Tool, ToolResult
+
+    class MyTool(Tool):
+        name = "my_tool"
+        description = "Does something useful."
+        parameters = {
+            "query": {"type": "str", "description": "The search query"},
+        }
+        permissions = ["network"]
+
+        async def execute(self, query: str) -> ToolResult:
+            result = await some_api(query)
+            return ToolResult(output=result, tool=self.name)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolResult:
+    """Returned by every tool execution."""
+
+    tool: str
+    output: Any
+    error: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+    def to_prompt_block(self) -> str:
+        """Serialise for injection into the LLM prompt."""
+        if self.error:
+            return f"[TOOL:{self.tool} ERROR] {self.error}"
+        output = str(self.output) if not isinstance(self.output, str) else self.output
+        return f"[TOOL:{self.tool}]\n{output}"
+
+
+class Tool(ABC):
+    """Abstract base for all CortexFlow tools.
+
+    Class attributes (declare on subclass):
+        name:        Unique tool identifier, snake_case.
+        description: One sentence used by the LLM to decide when to call it.
+        parameters:  Dict of {param_name: {"type": str, "description": str, "required": bool}}.
+        permissions: List of required permission strings, e.g. ["network", "filesystem:read"].
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, dict[str, Any]] = {}
+    permissions: list[str] = []
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        """Run the tool with the given arguments.
+
+        Args should match the keys declared in ``parameters``.
+        Returns a ToolResult — never raises; wrap errors in ToolResult.error.
+        """
+        ...
+
+    def get_schema(self) -> dict[str, Any]:
+        """Return JSON Schema describing the tool for LLM function calling."""
+        props: dict[str, Any] = {}
+        required: list[str] = []
+        for param_name, spec in self.parameters.items():
+            props[param_name] = {
+                "type": _py_to_json_type(spec.get("type", "str")),
+                "description": spec.get("description", ""),
+            }
+            if spec.get("required", True):
+                required.append(param_name)
+
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": props,
+                "required": required,
+            },
+        }
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name!r})"
+
+
+def _py_to_json_type(py_type: str) -> str:
+    mapping = {
+        "str": "string",
+        "int": "integer",
+        "float": "number",
+        "bool": "boolean",
+        "list": "array",
+        "dict": "object",
+    }
+    return mapping.get(py_type, "string")

cortexflow_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: cortexflow-sdk
+Version: 0.1.0
+Summary: Typed interfaces for building CortexFlow plugins, tools, and channel adapters — no gateway dependencies required.
+Author-email: Amit Chandra <amit.vervebot@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# cortexflow-sdk
+
+Typed interfaces for building [CortexFlow](https://github.com/TheAmitChandra/CortexFlow) plugins — without installing the full gateway.
+
+CortexFlow's gateway depends on FastAPI, Redis, Qdrant, and SDKs for all 14
+supported channels. None of that is needed to *write* a plugin — only to
+*run* the gateway that loads it. This package contains just the three base
+classes a plugin author needs, with zero third-party dependencies.
+
+## Install
+
+```bash
+pip install cortexflow-sdk
+```
+
+## Writing a plugin
+
+Every plugin package registers a `Plugin` subclass via a `cortexflow.plugins`
+entry point:
+
+```python
+# my_plugin/plugin.py
+from cortexflow_sdk import Plugin, PluginMetadata, Tool, ToolResult
+
+
+class WeatherTool(Tool):
+    name = "get_weather"
+    description = "Get the current weather for a city."
+    parameters = {
+        "city": {"type": "str", "description": "City name", "required": True},
+    }
+    permissions = ["network"]
+
+    async def execute(self, city: str) -> ToolResult:
+        # ... call a weather API ...
+        return ToolResult(tool=self.name, output=f"Sunny in {city}")
+
+
+class WeatherPlugin(Plugin):
+    metadata = PluginMetadata(
+        name="cortexflow-weather",
+        version="1.0.0",
+        plugin_type="tool",
+        description="Adds a get_weather tool.",
+        permissions=["network"],
+    )
+
+    def get_tools(self):
+        return [WeatherTool()]
+```
+
+```toml
+# my_plugin/pyproject.toml
+[project.entry-points."cortexflow.plugins"]
+cortexflow-weather = "my_plugin.plugin:WeatherPlugin"
+```
+
+Once published to PyPI and installed alongside the CortexFlow gateway,
+`cortex plugin add cortexflow-weather` discovers and loads it.
+
+## Plugin types
+
+| `plugin_type` | Implement | Contributes |
+|---|---|---|
+| `tool` | `get_tools()` | One or more `Tool` instances |
+| `channel` | `get_channel_adapter()` | A `ChannelAdapter` instance |
+| `tts` / `stt` / `memory` | — | Loaded by name; see gateway docs |
+| `generic` | `on_load()` / `on_unload()` | Lifecycle hooks only |
+
+## Writing a channel adapter plugin
+
+```python
+from cortexflow_sdk import ChannelAdapter, InboundMessage
+
+
+class MyChannelAdapter(ChannelAdapter):
+    channel_id = "my_channel"
+
+    async def connect(self) -> None: ...
+    async def disconnect(self) -> None: ...
+    async def send(self, target, text, *, reply_to=None, attachments=None):
+        ...
+
+    async def _on_platform_event(self, raw_event: dict) -> None:
+        await self._dispatch(InboundMessage(
+            channel=self.channel_id,
+            sender_id=raw_event["user_id"],
+            sender_name=raw_event["user_name"],
+            text=raw_event["text"],
+        ))
+```
+
+## License
+
+MIT

cortexflow_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cortexflow_sdk/__init__.py,sha256=4UWcL5iE_qeZ_Fz7b6SaUoQq87qgkFWc_qNQLeGk0CU,976
+cortexflow_sdk/channels.py,sha256=iJ2kJYnYlu4B7cEPHf8Ur4ntum8oPXlV0SWxEU0kuvg,2907
+cortexflow_sdk/plugins.py,sha256=NgNAQFuiTmVYIaFKQMfiSQKu2p8icDfYCmgl9wBeOPA,3471
+cortexflow_sdk/tools.py,sha256=YCIznkTA_uZ52cEnSih981gnb5uJGZHzr7s6JdZamO0,3597
+cortexflow_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=7Dz5G7L1S2nxC1KQDChyyWKVx4NDmJJDf-KNruUtrHk,1069
+cortexflow_sdk-0.1.0.dist-info/METADATA,sha256=aBz71SglE4-H0_lNjQzNa_TKAeZFsVy44s3LTjlWXlc,3168
+cortexflow_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cortexflow_sdk-0.1.0.dist-info/top_level.txt,sha256=mpyjX-TvTeBifQZpJ5vUoKg-wn4pG902vhcio7YjWHw,15
+cortexflow_sdk-0.1.0.dist-info/RECORD,,

cortexflow_sdk-0.1.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
+

cortexflow_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Chandra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cortexflow_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cortexflow_sdk