modulex-integrations 0.0.1a0__py3-none-any.whl

modulex_integrations/__init__.py

@@ -0,0 +1,55 @@
+"""modulex-integrations — community-contributable integrations for ModuleX.
+
+Every integration lives at ``modulex_integrations.tools.<name>`` and is
+discovered by the modulex runtime via the ``modulex.tools`` entry-point
+group declared in ``pyproject.toml``.
+
+This top-level module re-exports the schema types so contributors can
+write a manifest with::
+
+    from modulex_integrations import (
+        IntegrationManifest, ActionDefinition, OAuth2AuthSchema, ...
+    )
+"""
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from modulex_integrations.schema import (
+    ActionDefinition,
+    ApiKeyAuthSchema,
+    AuthSchema,
+    BearerTokenAuthSchema,
+    CustomAuthSchema,
+    EnvVar,
+    IntegrationManifest,
+    InternalAuthSchema,
+    ModulexKeyAuthSchema,
+    OAuth2AuthSchema,
+    OAuthConfig,
+    ParameterDef,
+    SuccessIndicators,
+    TestEndpoint,
+)
+
+try:
+    __version__ = _pkg_version("modulex-integrations")
+except PackageNotFoundError:  # source checkout without `pip install -e .`
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "ActionDefinition",
+    "ApiKeyAuthSchema",
+    "AuthSchema",
+    "BearerTokenAuthSchema",
+    "CustomAuthSchema",
+    "EnvVar",
+    "IntegrationManifest",
+    "InternalAuthSchema",
+    "ModulexKeyAuthSchema",
+    "OAuth2AuthSchema",
+    "OAuthConfig",
+    "ParameterDef",
+    "SuccessIndicators",
+    "TestEndpoint",
+    "__version__",
+]

modulex_integrations/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1a0'
+__version_tuple__ = version_tuple = (0, 0, 1, 'a0')
+
+__commit_id__ = commit_id = None

modulex_integrations/schema.py

@@ -0,0 +1,212 @@
+"""Schema definitions for the modulex-integrations package.
+
+Every integration declares its metadata by constructing an
+``IntegrationManifest`` instance in its own ``manifest.py``. The modulex
+runtime imports these manifests via the ``modulex.tools`` entry-point
+group and uses them to drive credential UI, validation, and tool
+discovery.
+
+Design choices worth knowing:
+
+- All models use ``extra="forbid"`` so a typo in a contributor's
+  manifest fails at import time, not at runtime.
+- ``auth_schemas`` is a discriminated union keyed on ``auth_type``;
+  the same integration can expose multiple credential methods (GitHub
+  supports both OAuth2 and a personal access token).
+- Action ``output_schema`` is intentionally absent. The shape of every
+  action's return value is derived from the LangChain ``@tool``
+  function's return-type annotation (defined in each integration's
+  ``outputs.py``); the runtime obtains it via
+  ``Model.model_json_schema()`` at startup.
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "ActionDefinition",
+    "ApiKeyAuthSchema",
+    "AuthSchema",
+    "BearerTokenAuthSchema",
+    "CustomAuthSchema",
+    "EnvVar",
+    "IntegrationManifest",
+    "InternalAuthSchema",
+    "ModulexKeyAuthSchema",
+    "OAuth2AuthSchema",
+    "OAuthConfig",
+    "ParameterDef",
+    "SuccessIndicators",
+    "TestEndpoint",
+]
+
+
+# --- Parameters --------------------------------------------------------
+
+ParameterType = Literal[
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "array",
+    "object",
+]
+
+
+class ParameterDef(BaseModel):
+    """Definition of a single action parameter."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: ParameterType
+    description: str
+    default: Any = None
+    required: bool = False
+
+
+# --- Actions -----------------------------------------------------------
+
+
+class ActionDefinition(BaseModel):
+    """One callable action exposed by the integration.
+
+    The return shape is derived from the matching ``@tool`` function's
+    return-type annotation in ``tools.py`` — do not duplicate it here.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(pattern=r"^[a-z][a-z0-9_]*$")
+    description: str
+    parameters: dict[str, ParameterDef] = Field(default_factory=dict)
+
+
+# --- Credentials -------------------------------------------------------
+
+
+class EnvVar(BaseModel):
+    """A configurable secret/setting the operator must provide."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    display_name: str
+    description: str
+    required: bool = True
+    sensitive: bool = False
+    only_for_custom: bool = False
+    sample_format: str | None = None
+    about_url: str | None = None
+
+
+class SuccessIndicators(BaseModel):
+    """How to tell a credential test endpoint succeeded."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status_codes: list[int]
+    response_fields: list[str] | None = None
+
+
+class TestEndpoint(BaseModel):
+    """Endpoint hit to validate a configured credential.
+
+    Header values may contain placeholders such as ``{access_token}`` or
+    ``{token}`` which the runtime substitutes with the resolved
+    credential value.
+    """
+
+    __test__ = False  # pydantic model, not a pytest test class
+    model_config = ConfigDict(extra="forbid")
+
+    url: str
+    method: Literal["GET", "POST", "PUT", "DELETE", "PATCH"] = "GET"
+    headers: dict[str, str] = Field(default_factory=dict)
+    success_indicators: SuccessIndicators
+    cost_level: str = "free"
+    description: str | None = None
+
+
+# --- Auth schemas (discriminated union) --------------------------------
+
+
+class _AuthSchemaBase(BaseModel):
+    """Fields shared by every auth_schema variant."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    display_name: str
+    description: str
+    setup_instructions: list[str] | None = None
+    setup_environment_variables: list[EnvVar] = Field(default_factory=list)
+    test_endpoint: TestEndpoint
+
+
+class OAuthConfig(BaseModel):
+    """OAuth 2.0 authorize/token URL bundle."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    auth_url: str
+    token_url: str
+    scopes: list[str] = Field(default_factory=list)
+    token_auth_method: Literal["body", "basic"] = "body"
+
+
+class OAuth2AuthSchema(_AuthSchemaBase):
+    auth_type: Literal["oauth2"] = "oauth2"
+    oauth_config: OAuthConfig
+
+
+class BearerTokenAuthSchema(_AuthSchemaBase):
+    auth_type: Literal["bearer_token"] = "bearer_token"
+
+
+class ApiKeyAuthSchema(_AuthSchemaBase):
+    auth_type: Literal["api_key"] = "api_key"
+
+
+class ModulexKeyAuthSchema(_AuthSchemaBase):
+    auth_type: Literal["modulex_key"] = "modulex_key"
+
+
+class CustomAuthSchema(_AuthSchemaBase):
+    auth_type: Literal["custom"] = "custom"
+
+
+class InternalAuthSchema(_AuthSchemaBase):
+    auth_type: Literal["internal"] = "internal"
+
+
+AuthSchema = Annotated[
+    OAuth2AuthSchema
+    | BearerTokenAuthSchema
+    | ApiKeyAuthSchema
+    | ModulexKeyAuthSchema
+    | CustomAuthSchema
+    | InternalAuthSchema,
+    Field(discriminator="auth_type"),
+]
+
+
+# --- Top-level manifest ------------------------------------------------
+
+
+class IntegrationManifest(BaseModel):
+    """The contract every integration's ``manifest.py`` produces."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    integration_type: Literal["tool"] = "tool"
+    name: str = Field(pattern=r"^[a-z][a-z0-9_]*$")
+    display_name: str
+    description: str
+    version: str = "1.0.0"
+    author: str = "ModuleX"
+    logo: str | None = None
+    app_url: str | None = None
+    categories: list[str] = Field(default_factory=list)
+    actions: list[ActionDefinition] = Field(default_factory=list)
+    auth_schemas: list[AuthSchema] = Field(default_factory=list)

modulex_integrations/tools/__init__.py

@@ -0,0 +1,7 @@
+"""Namespace for individual integration packages.
+
+Each integration lives in its own directory under this module:
+``modulex_integrations.tools.<name>``. The modulex runtime discovers
+them via the ``modulex.tools`` entry-point group; do not import from
+here directly.
+"""

modulex_integrations-0.0.1a0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: modulex-integrations
+Version: 0.0.1a0
+Summary: Community-contributable integrations (tools) for ModuleX
+Project-URL: Homepage, https://github.com/ModuleXAI/modulex-integrations
+Project-URL: Repository, https://github.com/ModuleXAI/modulex-integrations
+Project-URL: Issues, https://github.com/ModuleXAI/modulex-integrations/issues
+Author-email: ModuleX <team@modulex.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,integrations,langchain,modulex,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pydantic>=2.5.0
+Provides-Extra: all
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# modulex-integrations
+
+[![CI](https://github.com/ModuleXAI/modulex-integrations/actions/workflows/validate.yml/badge.svg)](https://github.com/ModuleXAI/modulex-integrations/actions/workflows/validate.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/modulex-integrations.svg)](https://pypi.org/project/modulex-integrations/)
+
+Community-contributable integrations (tools) for the [ModuleX](https://github.com/ModuleXAI/modulex) runtime.
+
+## Why this repo exists
+
+`modulex` is a FastAPI/Python backend that, until now, bundled 45
+LangChain tool integrations inline. We are extracting those 45 tools
+into this standalone, publicly pip-installable package so that:
+
+- adding a new tool is a single-repo PR, not a multi-file edit
+  across the modulex monorepo,
+- integration code is publicly inspectable,
+- community contributions flow through the standard GitHub PR model.
+
+LLM providers and knowledge providers stay in modulex. Only the
+`tool` integrations migrate here.
+
+## Status
+
+**Phase 1 — early development.** The schema contract and packaging
+are in place; integrations themselves will be migrated from the
+modulex monorepo one at a time, starting with a `github` POC and
+continuing via a scripted bulk migration. See [CHANGELOG.md](CHANGELOG.md)
+for progress and [CONTRIBUTING.md](CONTRIBUTING.md) for layout rules.
+
+## What is this?
+
+Each integration in this package exposes one or more LangChain
+`@tool` functions to the ModuleX runtime, together with credential
+metadata (auth schemas, env vars, test endpoints). The runtime
+discovers integrations via the Python `modulex.tools` entry-point
+group and loads them at startup.
+
+## Installation
+
+```bash
+pip install modulex-integrations
+```
+
+With every integration's optional dependencies:
+
+```bash
+pip install "modulex-integrations[all]"
+```
+
+Or only the integrations you need (extras are populated as
+integrations are migrated):
+
+```bash
+pip install "modulex-integrations[github,slack]"
+```
+
+## Per-integration layout
+
+Every integration ships in the same shape:
+
+```
+src/modulex_integrations/tools/<name>/
+├── __init__.py        # re-exports manifest + TOOLS
+├── manifest.py        # IntegrationManifest instance
+├── tools.py           # LangChain @tool functions
+├── outputs.py         # pydantic response models (UI/docs derive JSONSchema)
+├── dependencies.toml  # per-integration runtime deps
+├── README.md          # 5-section strict template (see CONTRIBUTING.md)
+└── tests/
+    └── test_<name>.py
+```
+
+The contract is enforced by pydantic types in
+[`src/modulex_integrations/schema.py`](src/modulex_integrations/schema.py)
+with `extra="forbid"` everywhere — a typo in a manifest fails at
+import time, not at runtime.
+
+## Development
+
+```bash
+git clone https://github.com/ModuleXAI/modulex-integrations.git
+cd modulex-integrations
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+mypy src/modulex_integrations
+```
+
+## Roadmap
+
+- **Phase 1 — bootstrap (this commit).** Schema, packaging, CI,
+  community meta files, cross-repo brief workflow.
+- **Phase 2 — github POC migration.** One integration end-to-end:
+  manifest, tools, outputs, tests, entry point, real
+  `httpx.MockTransport` coverage of at least one action.
+- **Phase 3 — scripted bulk migration.** The remaining 44
+  integrations migrated by a one-shot script, then reviewed
+  individually.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

modulex_integrations-0.0.1a0.dist-info/RECORD

@@ -0,0 +1,9 @@
+modulex_integrations/__init__.py,sha256=y03jgEhl4SeWPR89ZqXdlfweSkFJ4rpUfKWHXSLaSrk,1447
+modulex_integrations/_version.py,sha256=FsByamrmbXweQe1NVtH7k9LbbU4TLa-ybqnCcTiv85U,528
+modulex_integrations/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modulex_integrations/schema.py,sha256=SaXqBfZtSftfuw1gC6SNGC4zgKZ2tlSILBRXGMF0R6A,5804
+modulex_integrations/tools/__init__.py,sha256=MkxH_u0Nx2VysZVVRX5Fz5swCb38CUPBenWFJT4uN2M,271
+modulex_integrations-0.0.1a0.dist-info/METADATA,sha256=tby9Ka9PQ_2RoNe937jU3lmhzE4G-4Yuhs7o188kmOY,4742
+modulex_integrations-0.0.1a0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+modulex_integrations-0.0.1a0.dist-info/licenses/LICENSE,sha256=bfr2xGJEVUFiqqrNKUl973a_UchvRWcJ9jZX8x4SAOA,1064
+modulex_integrations-0.0.1a0.dist-info/RECORD,,

modulex_integrations-0.0.1a0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

modulex_integrations-0.0.1a0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ModuleX
+
+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.