Build an integration

src/modulex_integrations/tools/<name>/
├── __init__.py        # re-exports `manifest` + `TOOLS`
├── manifest.py        # IntegrationManifest instance bound to the name `manifest`
├── tools.py           # LangChain @tool functions (one per action)
├── outputs.py         # pydantic response models (output schema derived from these)
├── dependencies.toml  # per-integration runtime deps
├── README.md          # 5-section strict template
└── tests/
    ├── __init__.py    # empty
    └── test_<name>.py # ≥1 happy-path test per @tool

"""<Display name> integration — discovered by the modulex runtime via the
``modulex.tools`` entry point declared in the root ``pyproject.toml``.

The runtime imports this module, then reads:

- ``manifest`` — an IntegrationManifest describing metadata, actions, and auth schemas.
- ``TOOLS`` — a tuple of LangChain StructuredTool objects, one per action.
"""
from modulex_integrations.tools.<name>.manifest import manifest
from modulex_integrations.tools.<name>.tools import (
    create_thing,
    list_things,
)

TOOLS = (
    list_things,
    create_thing,
)

__all__ = ["TOOLS", "create_thing", "list_things", "manifest"]

from modulex_integrations.schema import (
    ActionDefinition,
    BearerTokenAuthSchema,
    EnvVar,
    IntegrationManifest,
    ParameterDef,
    SuccessIndicators,
    TestEndpoint,
)

manifest = IntegrationManifest(
    name="acme",
    display_name="Acme",
    description="Acme task and project management",
    version="1.0.0",
    author="ModuleX",
    logo="modulex:acme-themed",
    app_url="https://acme.example.com",
    categories=["Productivity"],
    actions=[
        ActionDefinition(
            name="list_tasks",
            description="List tasks in a project",
            parameters={
                "project_id": ParameterDef(type="string", description="Project id", required=True),
                "limit": ParameterDef(type="integer", description="Max tasks to return", default=30),
            },
        ),
    ],
    auth_schemas=[
        BearerTokenAuthSchema(
            display_name="Personal Access Token",
            description="Use your Acme API token",
            setup_environment_variables=[
                EnvVar(
                    name="ACME_TOKEN",
                    display_name="API Token",
                    description="Acme personal access token",
                    sensitive=True,
                    sample_format="acme_xxxxxxxx",
                    about_url="https://acme.example.com/settings/tokens",
                ),
            ],
            test_endpoint=TestEndpoint(
                url="https://api.acme.example.com/me",
                method="GET",
                headers={"Authorization": "Bearer {token}"},
                success_indicators=SuccessIndicators(status_codes=[200], response_fields=["id"]),
                cost_level="free",
            ),
        ),
    ],
)

from __future__ import annotations

from typing import Any

import httpx
from langchain_core.tools import tool
from pydantic import BaseModel, Field

from modulex_integrations import serialize_pydantic_return
from modulex_integrations.tools.acme.outputs import ListTasksOutput


class ListTasksInput(BaseModel):
    auth_type: str = Field(description="Authentication type (oauth2, bearer_token)")
    auth_data: dict[str, Any] = Field(description="Authentication data containing tokens")
    project_id: str = Field(description="Project id")
    limit: int = Field(default=30, description="Max tasks to return")


@tool(args_schema=ListTasksInput)       # OUTER — applied last, closest to the call site
@serialize_pydantic_return              # INNER — wraps the raw function
async def list_tasks(
    auth_type: str,
    auth_data: dict[str, Any],
    project_id: str,
    limit: int = 30,
) -> ListTasksOutput:                    # return annotation = the output model
    """List tasks in a project."""
    headers = _get_auth_headers(auth_type, auth_data)
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://api.acme.example.com/projects/{project_id}/tasks",
            headers=headers,
            params={"limit": limit},
        )
        response.raise_for_status()
        data = response.json()
    return ListTasksOutput(success=True, tasks=data.get("tasks", []))

from __future__ import annotations

from pydantic import BaseModel, ConfigDict, Field


class _Base(BaseModel):
    model_config = ConfigDict(extra="forbid")


class TaskSummary(_Base):
    id: str | None = None
    title: str | None = None
    status: str | None = None


class ListTasksOutput(_Base):
    success: bool                                    # required on every output model
    tasks: list[TaskSummary] = Field(default_factory=list)
    error: str | None = None                         # present only on inline-error integrations

[project.entry-points."modulex.tools"]
github = "modulex_integrations.tools.github"
slack = "modulex_integrations.tools.slack"
acme = "modulex_integrations.tools.acme"

dependencies = ["acme-sdk>=2.0.0"]

from __future__ import annotations

from typing import Any

import pytest

from modulex_integrations.tools.acme import TOOLS, list_tasks, manifest

API = "https://api.acme.example.com"
_AUTH: dict[str, Any] = {"auth_type": "bearer_token", "auth_data": {"token": "acme-fake"}}


def _args(**extra: Any) -> dict[str, Any]:
    return dict(_AUTH, **extra)


class TestManifest:
    def test_actions_match_tools_tuple(self) -> None:
        assert {a.name for a in manifest.actions} == {t.name for t in TOOLS}


@pytest.mark.asyncio
async def test_list_tasks(httpx_mock):  # type: ignore[no-untyped-def]
    httpx_mock.add_response(
        method="GET",
        url=f"{API}/projects/p1/tasks?limit=30",
        json={"tasks": [{"id": "t1", "title": "Ship docs", "status": "open"}]},
    )
    result = await list_tasks.ainvoke(_args(project_id="p1"))
    assert result["success"] is True
    assert result["tasks"][0]["id"] == "t1"