modulex-integrations 0.0.1a0__tar.gz

modulex_integrations-0.0.1a0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution
+*.egg-info/
+*.egg
+dist/
+build/
+wheels/
+sdist/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Generated by hatch-vcs at build time
+src/modulex_integrations/_version.py
+
+# Local environment
+.env
+.env.local
+*.local
+
+# Internal-only artifacts — never push to this public repo.
+# (History was scrubbed of CLAUDE.md, external-briefs/, and .claude/
+# on 2026-05-15; see the cleanup commit on main.)
+CLAUDE.md
+.claude/
+external-briefs/

modulex_integrations-0.0.1a0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `modulex-integrations` are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial repository skeleton (src/ layout, hatchling build, pytest/ruff/mypy config).
+- `IntegrationManifest` pydantic schema with discriminated-union `auth_schemas` covering oauth2, bearer_token, api_key, modulex_key, custom, internal.
+- Contract tests on a github-shaped manifest.
+- `CLAUDE.md` — project rules for Claude Code sessions in this repo.
+- `external-briefs/` workflow scaffold (`README.md` spec + `modulex/` placeholder) for coordinating changes in sibling repos.
+- Community meta files: `.github/CODEOWNERS`, `.github/PULL_REQUEST_TEMPLATE.md`, `.github/ISSUE_TEMPLATE/{bug_report.md,integration_request.md,config.yml}`, `SECURITY.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1).
+- `.github/workflows/validate.yml` — lint + type-check + test on Python 3.12 and 3.13.
+- `.editorconfig` and `.python-version` for consistent local tooling.
+
+### Changed
+
+- `README.md` expanded with "Why this repo exists", badges, per-integration layout, and a roadmap section.
+- `.gitignore` no longer ignores `.python-version` (file is now committed); now also ignores the hatch-vcs-generated `src/modulex_integrations/_version.py`.
+- `pyproject.toml`: switched to `dynamic = ["version"]` driven by `hatch-vcs`; static `version = "0.0.1"` removed. Static `__version__` in `__init__.py` replaced by `importlib.metadata`-based resolution.
+
+### Added (release infrastructure)
+
+- `.github/workflows/release.yml` — tag-triggered (`v*`) workflow that classifies pre-release vs stable via PEP 440, enforces branch-of-origin (stable from `main`, pre-release from `staging`), builds sdist + wheel, and publishes to PyPI via Trusted Publishing OIDC in the `release-pypi` environment.
+- `RELEASING.md` — release process, PyPI Trusted Publisher setup checklist, and the modulex-side per-branch pinning policy.
+- `external-briefs/modulex/001-bump-python-floor-to-3-12.md` — blocking brief: modulex must bump its `requires-python` floor and runtime Python to 3.12 before the upcoming `modulex-integrations` dependency line can resolve.
+- `CLAUDE.md` — "Release model" section pointing at `RELEASING.md`.
+
+## [0.0.1] — 2026-05-15
+
+Project bootstrap.

modulex_integrations-0.0.1a0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to modulex-integrations
+
+This repository expects every integration to ship with the same set of files in the same shape. Reviews are mechanical: if the structure is wrong, the PR is sent back. If the structure is right, review focuses on correctness of the API calls.
+
+## Project layout
+
+```
+src/modulex_integrations/tools/<name>/
+├── __init__.py                  # re-exports `manifest` and `TOOLS`
+├── manifest.py                  # IntegrationManifest instance
+├── tools.py                     # LangChain @tool functions
+├── outputs.py                   # pydantic response models
+├── dependencies.toml            # runtime deps (assembled into root pyproject by CI)
+├── README.md                    # 5 required sections (see template below)
+└── tests/
+    └── test_<name>.py           # ≥1 happy-path test per @tool
+```
+
+## Required README sections
+
+Every integration's `README.md` must contain these top-level headings, in this order:
+
+1. `# <Display Name>` + 1–2 sentence summary
+2. `## Authentication` — auth methods supported, where to get credentials, OAuth scopes if applicable
+3. `## Tools` — table of `name | description | required params`
+4. `## Limits & Quotas` — rate limits, known issues
+5. `## Maintainer` — github handle or "ModuleX core team"
+
+CI enforces the section list.
+
+## Test requirements
+
+- **HTTP tools (using `httpx`):** at least one `httpx.MockTransport` test per action's happy path.
+- **SDK tools** (using a vendor SDK such as `hubspot-api-client`): at least one `unittest.mock.patch` test stubbing the SDK client per action.
+
+## Schema contract
+
+The full set of types is in [`src/modulex_integrations/schema.py`](src/modulex_integrations/schema.py). Use these symbols — do not invent fields:
+
+- `IntegrationManifest` — top-level
+- `ActionDefinition`, `ParameterDef`
+- `OAuth2AuthSchema`, `BearerTokenAuthSchema`, `ApiKeyAuthSchema`, `ModulexKeyAuthSchema`, `CustomAuthSchema`, `InternalAuthSchema`
+- `OAuthConfig`, `EnvVar`, `TestEndpoint`, `SuccessIndicators`
+
+All models use `extra="forbid"` — typos fail at import time.
+
+## Local workflow
+
+```bash
+pip install -e ".[dev]"
+pytest                                                         # all tests
+pytest src/modulex_integrations/tools/<name>/tests/            # one integration
+ruff check src tests
+mypy src/modulex_integrations
+```
+
+## Adding a new integration
+
+> TODO: flesh out once the POC migration of the github tool lands. The intent is straightforward — copy an existing integration's folder, edit the manifest/tools/outputs/tests, open a PR.

modulex_integrations-0.0.1a0/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.

modulex_integrations-0.0.1a0/PKG-INFO

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

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

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["hatchling>=1.20", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "modulex-integrations"
+dynamic = ["version"]
+description = "Community-contributable integrations (tools) for ModuleX"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ModuleX", email = "team@modulex.dev" }]
+keywords = ["modulex", "integrations", "ai", "tools", "langchain"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.5.0",
+    "httpx>=0.25.0",
+    "langchain-core>=0.3.0",
+]
+
+[project.optional-dependencies]
+# `all` is auto-assembled from per-integration `dependencies.toml`
+# files by scripts/assemble_dependencies.py. Do not edit by hand.
+all = []
+
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-httpx>=0.30.0",
+    "ruff>=0.6.0",
+    "mypy>=1.10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ModuleXAI/modulex-integrations"
+Repository = "https://github.com/ModuleXAI/modulex-integrations"
+Issues = "https://github.com/ModuleXAI/modulex-integrations/issues"
+
+# Entry points — each migrated tool gets one line here.
+[project.entry-points."modulex.tools"]
+# Example (added when github POC lands):
+# github = "modulex_integrations.tools.github"
+
+[tool.hatch.version]
+# Version is derived from the latest git tag matching v* (e.g. v0.1.0,
+# v0.2.0a1). Between tags, builds carry a PEP 440 dev-suffixed version.
+# Release CI only publishes on a tag push, so PyPI never sees a dev
+# version.
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+# Writes a `_version.py` into the source tree at build time. Kept out
+# of git via .gitignore; importlib.metadata is the runtime path we use.
+version-file = "src/modulex_integrations/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modulex_integrations"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src",
+    "tests",
+    "scripts",
+    "README.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src/modulex_integrations"]
+python_files = "test_*.py"
+asyncio_mode = "auto"
+addopts = [
+    "--strict-markers",
+    "--import-mode=importlib",
+    "-ra",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+# Generated by hatch-vcs at build time; not under our control.
+extend-exclude = ["src/modulex_integrations/_version.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "B", "C4", "UP", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["N802", "N803", "N806"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unused_configs = true
+files = ["src/modulex_integrations"]

modulex_integrations-0.0.1a0/scripts/README.md

@@ -0,0 +1,10 @@
+# scripts/
+
+Utility scripts maintained alongside the package.
+
+Planned scripts:
+
+- `migrate_from_modulex.py` — one-shot conversion of legacy `py/app/integrations/tools/<name>_integration.json` files into `src/modulex_integrations/tools/<name>/` directories (manifest + outputs + tests stubs).
+- `assemble_dependencies.py` — read every `tools/<name>/dependencies.toml` and regenerate `[project.optional-dependencies]` in the root `pyproject.toml`. Run by CI on every PR.
+
+Neither script is implemented yet; placeholders only.

modulex_integrations-0.0.1a0/src/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-0.0.1a0/src/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-0.0.1a0/src/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-0.0.1a0/src/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/tests/conftest.py

@@ -0,0 +1,7 @@
+"""Top-level pytest configuration for modulex-integrations.
+
+Per-integration tests live next to each integration
+(``src/modulex_integrations/tools/<name>/tests/``). Shared fixtures
+applicable to many integrations belong here. Right now this file is a
+placeholder; fixtures will be added as the github POC migration lands.
+"""

modulex_integrations-0.0.1a0/tests/test_schema.py

@@ -0,0 +1,224 @@
+"""Contract tests for the IntegrationManifest schema.
+
+These tests pin down the shape that every integration's manifest must
+satisfy. They use a github-shaped manifest because it exercises every
+schema feature: multi-action, multi-auth (OAuth2 + bearer), parameters
+with defaults, env vars with rich UI metadata.
+"""
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from modulex_integrations import (
+    ActionDefinition,
+    BearerTokenAuthSchema,
+    EnvVar,
+    IntegrationManifest,
+    OAuth2AuthSchema,
+    OAuthConfig,
+    ParameterDef,
+    SuccessIndicators,
+    TestEndpoint,
+)
+
+
+def _github_like_manifest() -> IntegrationManifest:
+    """Construct a manifest shaped like the existing github_integration.json.
+
+    Truncated to two actions; the goal is exercising every schema
+    feature, not duplicating the 1180-line JSON.
+    """
+    return IntegrationManifest(
+        name="github",
+        display_name="GitHub",
+        description="GitHub repository and code management platform",
+        version="1.0.0",
+        author="ModuleX",
+        logo="https://cdn.jsdelivr.net/gh/ModuleXAI/logox@main/tools/github.svg",
+        app_url="https://github.com",
+        categories=["Developer Tools & Infrastructure", "version-control", "productivity"],
+        actions=[
+            ActionDefinition(
+                name="list_repositories",
+                description="List repositories for the authenticated user or organization",
+                parameters={
+                    "visibility": ParameterDef(
+                        type="string",
+                        description="Filter by visibility: all, public, private",
+                        default="all",
+                    ),
+                    "per_page": ParameterDef(
+                        type="integer",
+                        description="Results per page (max 100)",
+                        default=30,
+                    ),
+                },
+            ),
+            ActionDefinition(
+                name="create_issue",
+                description="Create a new issue",
+                parameters={
+                    "owner": ParameterDef(
+                        type="string", description="Repository owner", required=True
+                    ),
+                    "repo": ParameterDef(
+                        type="string", description="Repository name", required=True
+                    ),
+                    "title": ParameterDef(
+                        type="string", description="Issue title", required=True
+                    ),
+                    "labels": ParameterDef(type="array", description="Issue labels"),
+                },
+            ),
+        ],
+        auth_schemas=[
+            OAuth2AuthSchema(
+                display_name="OAuth2 Authentication",
+                description="Connect using GitHub OAuth (recommended for most use cases)",
+                setup_environment_variables=[
+                    EnvVar(
+                        name="GITHUB_OAUTH2_CLIENT_ID",
+                        display_name="Client ID",
+                        description="GitHub OAuth App Client ID",
+                        sensitive=False,
+                        only_for_custom=True,
+                        sample_format="Iv1.xxxxxxxxxxxxxxxx",
+                        about_url="https://github.com/settings/applications/new",
+                    ),
+                    EnvVar(
+                        name="GITHUB_OAUTH2_CLIENT_SECRET",
+                        display_name="Client Secret",
+                        description="GitHub OAuth App Client Secret",
+                        sensitive=True,
+                        only_for_custom=True,
+                        sample_format="x" * 40,
+                        about_url="https://github.com/settings/applications/new",
+                    ),
+                ],
+                oauth_config=OAuthConfig(
+                    auth_url="https://github.com/login/oauth/authorize",
+                    token_url="https://github.com/login/oauth/access_token",
+                    scopes=["repo", "user", "read:org", "workflow"],
+                    token_auth_method="body",
+                ),
+                test_endpoint=TestEndpoint(
+                    url="https://api.github.com/user",
+                    method="GET",
+                    headers={
+                        "Authorization": "Bearer {access_token}",
+                        "Accept": "application/vnd.github+json",
+                        "X-GitHub-Api-Version": "2022-11-28",
+                    },
+                    success_indicators=SuccessIndicators(
+                        status_codes=[200], response_fields=["login", "id"]
+                    ),
+                    cost_level="free",
+                ),
+            ),
+            BearerTokenAuthSchema(
+                display_name="Personal Access Token",
+                description="Use your GitHub Personal Access Token (Classic or Fine-grained)",
+                setup_instructions=[
+                    "Go to GitHub Settings -> Developer settings -> Personal access tokens",
+                    "Choose 'Tokens (classic)' OR 'Fine-grained tokens (Beta)'",
+                    "Generate, copy, and configure GITHUB_PERSONAL_TOKEN.",
+                ],
+                setup_environment_variables=[
+                    EnvVar(
+                        name="GITHUB_PERSONAL_TOKEN",
+                        display_name="Personal Access Token",
+                        description="Your GitHub Personal Access Token",
+                        sensitive=True,
+                        sample_format="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+                        about_url="https://github.com/settings/tokens",
+                    ),
+                ],
+                test_endpoint=TestEndpoint(
+                    url="https://api.github.com/user",
+                    headers={"Authorization": "Bearer {token}"},
+                    success_indicators=SuccessIndicators(
+                        status_codes=[200], response_fields=["login", "id"]
+                    ),
+                ),
+            ),
+        ],
+    )
+
+
+class TestManifestConstruction:
+    def test_github_like_manifest_validates(self) -> None:
+        manifest = _github_like_manifest()
+        assert manifest.name == "github"
+        assert manifest.integration_type == "tool"
+        assert len(manifest.actions) == 2
+        assert len(manifest.auth_schemas) == 2
+
+    def test_discriminator_picks_oauth2_variant(self) -> None:
+        manifest = _github_like_manifest()
+        first = manifest.auth_schemas[0]
+        assert isinstance(first, OAuth2AuthSchema)
+        assert first.oauth_config.scopes == ["repo", "user", "read:org", "workflow"]
+
+    def test_discriminator_picks_bearer_variant(self) -> None:
+        manifest = _github_like_manifest()
+        second = manifest.auth_schemas[1]
+        assert isinstance(second, BearerTokenAuthSchema)
+        # bearer variant has no oauth_config; extra="forbid" guards this
+        assert not hasattr(second, "oauth_config")
+
+
+class TestManifestRoundtrip:
+    def test_serialize_then_validate(self) -> None:
+        original = _github_like_manifest()
+        dumped = original.model_dump()
+        restored = IntegrationManifest.model_validate(dumped)
+        assert restored == original
+
+    def test_model_json_schema_describes_auth_union(self) -> None:
+        schema = IntegrationManifest.model_json_schema()
+        # The generated JSONSchema is what the UI consumes; make sure
+        # the auth_schemas field is present and discriminated.
+        assert "auth_schemas" in schema["properties"]
+
+
+class TestValidation:
+    def test_invalid_auth_type_rejected(self) -> None:
+        bad = {
+            "name": "x",
+            "display_name": "X",
+            "description": "y",
+            "auth_schemas": [
+                {
+                    "auth_type": "not_a_real_auth",
+                    "display_name": "z",
+                    "description": "z",
+                    "test_endpoint": {
+                        "url": "https://example.com",
+                        "headers": {},
+                        "success_indicators": {"status_codes": [200]},
+                    },
+                },
+            ],
+        }
+        with pytest.raises(ValidationError):
+            IntegrationManifest.model_validate(bad)
+
+    def test_invalid_name_slug_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            IntegrationManifest(
+                name="GitHub",
+                display_name="X",
+                description="y",
+            )
+
+    def test_extra_field_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            IntegrationManifest.model_validate(
+                {
+                    "name": "x",
+                    "display_name": "X",
+                    "description": "y",
+                    "bogus_field": "nope",
+                }
+            )