ninetrix-sdk 0.1.0__tar.gz

ninetrix_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]   # trigger when you publish a GitHub Release
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi          # optional: require manual approval in GitHub UI
+    permissions:
+      id-token: write          # needed for trusted publishing (no token required)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+        working-directory: .   # sdk/ is the repo root
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses PyPI Trusted Publishing — no API token needed at all

ninetrix_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: ninetrix-sdk
+Version: 0.1.0
+Summary: Python SDK for Ninetrix — define agent tools in code
+Project-URL: Homepage, https://ninetrix.io
+Project-URL: Repository, https://github.com/Ninetrix-ai/ninetrix
+Project-URL: Documentation, https://ninetrix.io/docs
+License: Apache-2.0
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ninetrix-sdk
+
+Python SDK for [Ninetrix](https://ninetrix.io) — define AI agent tools in code.
+
+## Phase 1: `@Tool` decorator
+
+Connect any Python function to a Ninetrix agent. The function is auto-discovered by `ninetrix build`, bundled into the Docker image, and dispatched at runtime alongside MCP tools.
+
+```bash
+pip install ninetrix-sdk
+```
+
+---
+
+## Quick start
+
+**1. Define your tools**
+
+```python
+# tools/db_tools.py
+from ninetrix import Tool
+
+@Tool
+def query_customers(sql: str, limit: int = 100) -> list[dict]:
+    """Execute a read-only SQL query against the customer database.
+
+    Args:
+        sql: A valid SELECT statement.
+        limit: Maximum rows to return.
+    """
+    return db.execute(sql, limit=limit)
+
+
+@Tool
+def send_notification(channel: str, message: str) -> bool:
+    """Send a message to an internal Slack channel.
+
+    Args:
+        channel: Destination channel (e.g. "#ops").
+        message: Notification text.
+    """
+    return slack.post(channel, message)
+```
+
+**2. Reference in `agentfile.yaml`**
+
+```yaml
+agents:
+  my-agent:
+    metadata:
+      role: Operations assistant
+      goal: Answer questions and send alerts using internal tools
+
+    runtime:
+      provider: anthropic
+      model: claude-sonnet-4-6
+
+    tools:
+      - name: web_search
+        source: mcp://brave-search        # MCP tool — unchanged
+
+      - name: db_tools
+        source: ./tools/db_tools.py       # Python tool file — NEW
+```
+
+**3. Build and run**
+
+```bash
+ninetrix build    # discovers @Tool functions, bundles them into the image
+ninetrix run      # agent can now call query_customers and send_notification
+```
+
+---
+
+## How it works
+
+| Step | What happens |
+|------|-------------|
+| `ninetrix build` | Scans `source: ./...py` entries, imports the file, extracts `@Tool` schemas |
+| Dockerfile | Copies the `.py` files into the image, installs `ninetrix-sdk` |
+| Container start | Imports the tool files, registers functions in the local registry |
+| LLM call | Agent receives local tool schemas alongside MCP tool schemas |
+| Tool dispatch | When the LLM calls a local tool, the Python function is invoked directly |
+
+---
+
+## `@Tool` API
+
+### Bare decorator
+
+```python
+@Tool
+def my_function(param: str, count: int = 5) -> str:
+    """One-line description used as the tool description.
+
+    Args:
+        param: Injected into the tool's parameter schema.
+        count: Optional param — not required, default shown to LLM.
+    """
+    ...
+```
+
+### Decorator factory (with overrides)
+
+```python
+@Tool(name="custom_name", description="Override the docstring description.")
+def my_function(param: str) -> str:
+    ...
+```
+
+### Supported parameter types
+
+| Python type | JSON Schema |
+|------------|------------|
+| `str` | `{"type": "string"}` |
+| `int` | `{"type": "integer"}` |
+| `float` | `{"type": "number"}` |
+| `bool` | `{"type": "boolean"}` |
+| `list[str]` | `{"type": "array", "items": {"type": "string"}}` |
+| `dict` | `{"type": "object"}` |
+| `Optional[str]` | `{"type": "string"}` (not required) |
+| `Literal["a","b"]` | `{"type": "string", "enum": ["a","b"]}` |
+
+Parameters without defaults → `required`. Parameters with defaults → optional (default shown in schema).
+
+---
+
+## Multiple tool files
+
+```yaml
+tools:
+  - name: db_tools
+    source: ./tools/db_tools.py
+
+  - name: api_tools
+    source: ./tools/api_tools.py
+
+  - name: web_search
+    source: mcp://brave-search
+```
+
+---
+
+## Testing your tools
+
+Tools are plain Python functions — test them directly:
+
+```python
+# tests/test_db_tools.py
+from tools.db_tools import query_customers
+
+def test_query_customers():
+    result = query_customers("SELECT id FROM customers LIMIT 1")
+    assert isinstance(result, list)
+```
+
+To inspect the generated schema:
+
+```python
+from ninetrix import _registry
+from tools import db_tools  # triggers @Tool registrations
+
+td = _registry.get("query_customers")
+print(td.to_anthropic_schema())
+```
+
+---
+
+## Roadmap
+
+- **Phase 1** ✅ — `@Tool` decorator, build discovery, runtime dispatch
+- **Phase 2** — `Agent(...)` class + `@Workflow` decorator for Python-first agent definition
+- **Phase 3** — Durable execution: checkpoint every workflow step, resume on crash
+
+---
+
+## License
+
+Apache 2.0
+

ninetrix_sdk-0.1.0/README.md

@@ -0,0 +1,180 @@
+# ninetrix-sdk
+
+Python SDK for [Ninetrix](https://ninetrix.io) — define AI agent tools in code.
+
+## Phase 1: `@Tool` decorator
+
+Connect any Python function to a Ninetrix agent. The function is auto-discovered by `ninetrix build`, bundled into the Docker image, and dispatched at runtime alongside MCP tools.
+
+```bash
+pip install ninetrix-sdk
+```
+
+---
+
+## Quick start
+
+**1. Define your tools**
+
+```python
+# tools/db_tools.py
+from ninetrix import Tool
+
+@Tool
+def query_customers(sql: str, limit: int = 100) -> list[dict]:
+    """Execute a read-only SQL query against the customer database.
+
+    Args:
+        sql: A valid SELECT statement.
+        limit: Maximum rows to return.
+    """
+    return db.execute(sql, limit=limit)
+
+
+@Tool
+def send_notification(channel: str, message: str) -> bool:
+    """Send a message to an internal Slack channel.
+
+    Args:
+        channel: Destination channel (e.g. "#ops").
+        message: Notification text.
+    """
+    return slack.post(channel, message)
+```
+
+**2. Reference in `agentfile.yaml`**
+
+```yaml
+agents:
+  my-agent:
+    metadata:
+      role: Operations assistant
+      goal: Answer questions and send alerts using internal tools
+
+    runtime:
+      provider: anthropic
+      model: claude-sonnet-4-6
+
+    tools:
+      - name: web_search
+        source: mcp://brave-search        # MCP tool — unchanged
+
+      - name: db_tools
+        source: ./tools/db_tools.py       # Python tool file — NEW
+```
+
+**3. Build and run**
+
+```bash
+ninetrix build    # discovers @Tool functions, bundles them into the image
+ninetrix run      # agent can now call query_customers and send_notification
+```
+
+---
+
+## How it works
+
+| Step | What happens |
+|------|-------------|
+| `ninetrix build` | Scans `source: ./...py` entries, imports the file, extracts `@Tool` schemas |
+| Dockerfile | Copies the `.py` files into the image, installs `ninetrix-sdk` |
+| Container start | Imports the tool files, registers functions in the local registry |
+| LLM call | Agent receives local tool schemas alongside MCP tool schemas |
+| Tool dispatch | When the LLM calls a local tool, the Python function is invoked directly |
+
+---
+
+## `@Tool` API
+
+### Bare decorator
+
+```python
+@Tool
+def my_function(param: str, count: int = 5) -> str:
+    """One-line description used as the tool description.
+
+    Args:
+        param: Injected into the tool's parameter schema.
+        count: Optional param — not required, default shown to LLM.
+    """
+    ...
+```
+
+### Decorator factory (with overrides)
+
+```python
+@Tool(name="custom_name", description="Override the docstring description.")
+def my_function(param: str) -> str:
+    ...
+```
+
+### Supported parameter types
+
+| Python type | JSON Schema |
+|------------|------------|
+| `str` | `{"type": "string"}` |
+| `int` | `{"type": "integer"}` |
+| `float` | `{"type": "number"}` |
+| `bool` | `{"type": "boolean"}` |
+| `list[str]` | `{"type": "array", "items": {"type": "string"}}` |
+| `dict` | `{"type": "object"}` |
+| `Optional[str]` | `{"type": "string"}` (not required) |
+| `Literal["a","b"]` | `{"type": "string", "enum": ["a","b"]}` |
+
+Parameters without defaults → `required`. Parameters with defaults → optional (default shown in schema).
+
+---
+
+## Multiple tool files
+
+```yaml
+tools:
+  - name: db_tools
+    source: ./tools/db_tools.py
+
+  - name: api_tools
+    source: ./tools/api_tools.py
+
+  - name: web_search
+    source: mcp://brave-search
+```
+
+---
+
+## Testing your tools
+
+Tools are plain Python functions — test them directly:
+
+```python
+# tests/test_db_tools.py
+from tools.db_tools import query_customers
+
+def test_query_customers():
+    result = query_customers("SELECT id FROM customers LIMIT 1")
+    assert isinstance(result, list)
+```
+
+To inspect the generated schema:
+
+```python
+from ninetrix import _registry
+from tools import db_tools  # triggers @Tool registrations
+
+td = _registry.get("query_customers")
+print(td.to_anthropic_schema())
+```
+
+---
+
+## Roadmap
+
+- **Phase 1** ✅ — `@Tool` decorator, build discovery, runtime dispatch
+- **Phase 2** — `Agent(...)` class + `@Workflow` decorator for Python-first agent definition
+- **Phase 3** — Durable execution: checkpoint every workflow step, resume on crash
+
+---
+
+## License
+
+Apache 2.0
+

ninetrix_sdk-0.1.0/examples/db_tools.py

@@ -0,0 +1,68 @@
+"""
+Example: custom database + API tools for a Ninetrix agent.
+
+Reference in agentfile.yaml:
+    tools:
+      - name: db_tools
+        source: ./examples/db_tools.py
+
+Then ninetrix build bundles this file and registers all @Tool functions.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from ninetrix import Tool
+
+
+@Tool
+def query_customers(sql: str, limit: int = 100) -> list[dict]:
+    """Execute a read-only SQL query against the customer database.
+
+    Args:
+        sql: A valid SELECT statement. UPDATE/DELETE/INSERT are not allowed.
+        limit: Maximum number of rows to return. Hard-capped at 1000.
+    """
+    # Replace with real DB call
+    raise NotImplementedError("Connect to your database here")
+
+
+@Tool
+def get_customer(customer_id: str) -> dict:
+    """Fetch a single customer record by ID.
+
+    Args:
+        customer_id: The unique customer identifier (UUID or integer string).
+    """
+    raise NotImplementedError
+
+
+@Tool
+def search_products(
+    query: str,
+    category: str | None = None,
+    sort: Literal["price_asc", "price_desc", "relevance"] = "relevance",
+    limit: int = 20,
+) -> list[dict]:
+    """Search the product catalog.
+
+    Args:
+        query: Full-text search query.
+        category: Optional category filter (e.g. "electronics", "apparel").
+        sort: Sort order for results.
+        limit: Maximum products to return.
+    """
+    raise NotImplementedError
+
+
+@Tool(name="send_internal_notification")
+def notify(channel: str, message: str, priority: Literal["low", "high"] = "low") -> bool:
+    """Send a notification to an internal Slack channel or PagerDuty.
+
+    Args:
+        channel: Destination channel name (e.g. "#ops-alerts").
+        message: Notification body. Keep it under 500 characters.
+        priority: "high" pages on-call, "low" posts silently.
+    """
+    raise NotImplementedError

ninetrix_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ninetrix-sdk"
+version = "0.1.0"
+description = "Python SDK for Ninetrix — define agent tools in code"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://ninetrix.io"
+Repository = "https://github.com/Ninetrix-ai/ninetrix"
+Documentation = "https://ninetrix.io/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ninetrix"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short -q"
+
+[tool.coverage.run]
+source = ["src/ninetrix"]
+omit = ["tests/*"]

ninetrix_sdk-0.1.0/src/ninetrix/__init__.py

@@ -0,0 +1,60 @@
+"""
+Ninetrix SDK — Python primitives for building AI agent tools.
+
+Phase 1: @Tool decorator
+    Define Python functions as agent-callable tools. They are auto-discovered
+    by ``ninetrix build``, bundled into the Docker image, and dispatched at
+    runtime alongside MCP tools.
+
+Phase 2 (upcoming): Agent + Workflow
+    Define full agents and complex workflows in Python.
+
+Quick start::
+
+    from ninetrix import Tool
+
+    @Tool
+    def query_customers(sql: str, limit: int = 100) -> list[dict]:
+        \"\"\"Run a read-only SQL query against the customer database.
+
+        Args:
+            sql: A valid SELECT statement.
+            limit: Maximum rows to return.
+        \"\"\"
+        return db.execute(sql, limit=limit)
+
+Reference the tool in ``agentfile.yaml``::
+
+    tools:
+      - name: query_customers
+        source: ./tools/db_tools.py
+
+Then build and run as usual::
+
+    ninetrix build
+    ninetrix run
+"""
+
+from ninetrix.tool import Tool
+from ninetrix.registry import ToolDef, ToolRegistry, _registry
+from ninetrix.discover import (
+    discover_tools_in_file,
+    discover_tools_in_files,
+    load_local_tools,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # Primary public API
+    "Tool",
+    # Registry types (useful for type hints and testing)
+    "ToolDef",
+    "ToolRegistry",
+    # Build-time discovery
+    "discover_tools_in_file",
+    "discover_tools_in_files",
+    # Runtime loader (called by generated entrypoint)
+    "load_local_tools",
+    # Internal registry (advanced / testing)
+    "_registry",
+]