cortexflow-sdk 0.1.0__tar.gz

cortexflow_sdk-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,95 @@
+# 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/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cortexflow-sdk"
+version = "0.1.0"
+description = "Typed interfaces for building CortexFlow plugins, tools, and channel adapters — no gateway dependencies required."
+authors = [{ name = "Amit Chandra", email = "amit.vervebot@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

cortexflow_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cortexflow_sdk-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/cortexflow_sdk.egg-info/PKG-INFO

@@ -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/src/cortexflow_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/cortexflow_sdk/__init__.py
+src/cortexflow_sdk/channels.py
+src/cortexflow_sdk/plugins.py
+src/cortexflow_sdk/tools.py
+src/cortexflow_sdk.egg-info/PKG-INFO
+src/cortexflow_sdk.egg-info/SOURCES.txt
+src/cortexflow_sdk.egg-info/dependency_links.txt
+src/cortexflow_sdk.egg-info/requires.txt
+src/cortexflow_sdk.egg-info/top_level.txt
+tests/test_channels.py
+tests/test_plugins.py
+tests/test_tools.py

cortexflow_sdk-0.1.0/src/cortexflow_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cortexflow_sdk-0.1.0/src/cortexflow_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8.2.0
+pytest-asyncio>=0.23.0

cortexflow_sdk-0.1.0/src/cortexflow_sdk.egg-info/top_level.txt

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

cortexflow_sdk-0.1.0/tests/test_channels.py

@@ -0,0 +1,92 @@
+"""Unit tests for cortexflow_sdk.channels — ChannelAdapter / InboundMessage."""
+
+from __future__ import annotations
+
+import pytest
+from cortexflow_sdk import Attachment, ChannelAdapter, InboundMessage
+
+
+def test_inbound_message_defaults():
+    msg = InboundMessage(channel="x", sender_id="u1", sender_name="Alice", text="hi")
+    assert msg.attachments == []
+    assert msg.thread_id is None
+    assert msg.raw == {}
+    assert msg.timestamp > 0
+
+
+def test_attachment_defaults():
+    att = Attachment(type="image")
+    assert att.url is None
+    assert att.data is None
+
+
+class _EchoAdapter(ChannelAdapter):
+    channel_id = "echo"
+
+    def __init__(self, config):
+        super().__init__(config)
+        self.sent: list[tuple[str, str]] = []
+        self.connected = False
+
+    async def connect(self) -> None:
+        self.connected = True
+
+    async def disconnect(self) -> None:
+        self.connected = False
+
+    async def send(self, target, text, *, reply_to=None, attachments=None):
+        self.sent.append((target, text))
+        return "msg-1"
+
+
+@pytest.mark.asyncio
+async def test_subclassed_adapter_connect_disconnect():
+    adapter = _EchoAdapter({"enabled": True})
+    await adapter.connect()
+    assert adapter.connected is True
+    await adapter.disconnect()
+    assert adapter.connected is False
+
+
+@pytest.mark.asyncio
+async def test_subclassed_adapter_send_returns_message_id():
+    adapter = _EchoAdapter({})
+    result = await adapter.send("user-1", "hello")
+    assert result == "msg-1"
+    assert adapter.sent == [("user-1", "hello")]
+
+
+@pytest.mark.asyncio
+async def test_on_message_handler_receives_dispatched_message():
+    adapter = _EchoAdapter({})
+    received: list[InboundMessage] = []
+
+    async def handler(msg: InboundMessage) -> None:
+        received.append(msg)
+
+    adapter.on_message(handler)
+    msg = InboundMessage(channel="echo", sender_id="u1", sender_name="Bob", text="hi")
+    await adapter._dispatch(msg)
+
+    assert received == [msg]
+
+
+@pytest.mark.asyncio
+async def test_dispatch_without_handler_is_noop():
+    adapter = _EchoAdapter({})
+    msg = InboundMessage(channel="echo", sender_id="u1", sender_name="Bob", text="hi")
+    await adapter._dispatch(msg)  # must not raise
+
+
+def test_default_config_schema():
+    schema = _EchoAdapter({}).get_config_schema()
+    assert schema["properties"]["enabled"]["default"] is False
+
+
+def test_adapter_repr_includes_channel_id():
+    assert repr(_EchoAdapter({})) == "_EchoAdapter(channel_id='echo')"
+
+
+def test_channel_adapter_is_abstract():
+    with pytest.raises(TypeError):
+        ChannelAdapter({})  # type: ignore[abstract]

cortexflow_sdk-0.1.0/tests/test_plugins.py

@@ -0,0 +1,90 @@
+"""Unit tests for cortexflow_sdk.plugins — Plugin / PluginMetadata."""
+
+from __future__ import annotations
+
+import pytest
+from cortexflow_sdk import ChannelAdapter, Plugin, PluginMetadata, Tool, ToolResult
+
+
+def test_plugin_metadata_defaults():
+    meta = PluginMetadata(name="x", version="1.0", plugin_type="generic", description="d")
+    assert meta.permissions == []
+    assert meta.author == ""
+    assert meta.homepage == ""
+
+
+class _NoopPlugin(Plugin):
+    metadata = PluginMetadata(
+        name="noop", version="0.1", plugin_type="generic", description="Does nothing.",
+    )
+
+
+@pytest.mark.asyncio
+async def test_default_lifecycle_hooks_are_noops():
+    p = _NoopPlugin()
+    await p.on_load()
+    await p.on_unload()  # neither should raise
+
+
+def test_default_get_tools_returns_empty_list():
+    assert _NoopPlugin().get_tools() == []
+
+
+def test_default_get_channel_adapter_returns_none():
+    assert _NoopPlugin().get_channel_adapter() is None
+
+
+def test_default_get_config_schema():
+    assert _NoopPlugin().get_config_schema() == {"type": "object", "properties": {}}
+
+
+def test_plugin_repr():
+    assert repr(_NoopPlugin()) == "Plugin('noop' v0.1, type='generic')"
+
+
+class _GreetTool(Tool):
+    name = "greet"
+    description = "Greets someone."
+    parameters = {"name": {"type": "str", "description": "Name", "required": True}}
+
+    async def execute(self, name: str) -> ToolResult:
+        return ToolResult(tool=self.name, output=f"Hello, {name}!")
+
+
+class _ToolPlugin(Plugin):
+    metadata = PluginMetadata(
+        name="greeter", version="1.0", plugin_type="tool", description="Adds a greet tool.",
+    )
+
+    def get_tools(self):
+        return [_GreetTool()]
+
+
+def test_tool_plugin_contributes_tool():
+    tools = _ToolPlugin().get_tools()
+    assert len(tools) == 1
+    assert tools[0].name == "greet"
+
+
+class _StubChannelAdapter(ChannelAdapter):
+    channel_id = "stub"
+
+    async def connect(self) -> None: ...
+    async def disconnect(self) -> None: ...
+    async def send(self, target, text, *, reply_to=None, attachments=None):
+        return None
+
+
+class _ChannelPlugin(Plugin):
+    metadata = PluginMetadata(
+        name="stub-channel", version="1.0", plugin_type="channel", description="Adds a stub channel.",
+    )
+
+    def get_channel_adapter(self):
+        return _StubChannelAdapter({})
+
+
+def test_channel_plugin_contributes_adapter():
+    adapter = _ChannelPlugin().get_channel_adapter()
+    assert adapter is not None
+    assert adapter.channel_id == "stub"

cortexflow_sdk-0.1.0/tests/test_tools.py

@@ -0,0 +1,73 @@
+"""Unit tests for cortexflow_sdk.tools — Tool / ToolResult."""
+
+from __future__ import annotations
+
+import pytest
+from cortexflow_sdk import Tool, ToolResult
+
+
+def test_tool_result_success_when_no_error():
+    r = ToolResult(tool="t", output="ok")
+    assert r.success is True
+
+
+def test_tool_result_failure_when_error_set():
+    r = ToolResult(tool="t", output=None, error="boom")
+    assert r.success is False
+
+
+def test_to_prompt_block_success():
+    r = ToolResult(tool="echo", output="hello")
+    assert r.to_prompt_block() == "[TOOL:echo]\nhello"
+
+
+def test_to_prompt_block_error():
+    r = ToolResult(tool="echo", output=None, error="failed")
+    assert r.to_prompt_block() == "[TOOL:echo ERROR] failed"
+
+
+def test_to_prompt_block_stringifies_non_string_output():
+    r = ToolResult(tool="calc", output=42)
+    assert r.to_prompt_block() == "[TOOL:calc]\n42"
+
+
+class _EchoTool(Tool):
+    name = "echo"
+    description = "Echoes the input."
+    parameters = {
+        "text": {"type": "str", "description": "Text to echo", "required": True},
+        "loud": {"type": "bool", "description": "Shout it", "required": False},
+    }
+    permissions = ["network"]
+
+    async def execute(self, text: str, loud: bool = False) -> ToolResult:
+        return ToolResult(tool=self.name, output=text.upper() if loud else text)
+
+
+@pytest.mark.asyncio
+async def test_subclassed_tool_executes():
+    tool = _EchoTool()
+    result = await tool.execute(text="hi", loud=True)
+    assert result.output == "HI"
+
+
+def test_get_schema_marks_required_params():
+    schema = _EchoTool().get_schema()
+    assert schema["name"] == "echo"
+    assert "text" in schema["parameters"]["required"]
+    assert "loud" not in schema["parameters"]["required"]
+
+
+def test_get_schema_maps_python_types_to_json_types():
+    schema = _EchoTool().get_schema()
+    assert schema["parameters"]["properties"]["loud"]["type"] == "boolean"
+    assert schema["parameters"]["properties"]["text"]["type"] == "string"
+
+
+def test_tool_repr_includes_name():
+    assert repr(_EchoTool()) == "_EchoTool(name='echo')"
+
+
+def test_tool_is_abstract():
+    with pytest.raises(TypeError):
+        Tool()  # type: ignore[abstract]