diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..50c83ebe --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,69 @@ +name: Build and Publish Docs + +on: + push: + branches: + - dev + - main + workflow_dispatch: + release: + types: [published] + +concurrency: + group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref}} + cancel-in-progress: true + +permissions: + contents: write + pages: write + pull-requests: write + +jobs: + deploy: + name: Publish Docs + runs-on: ubuntu-latest + timeout-minutes: 10 + strategy: + matrix: + python-version: ["3.12"] + steps: + - name: Checkout the repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 0 + + - name: Install uv and set Python ${{ matrix.python-version }} + uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3 + with: + python-version: ${{ matrix.python-version }} + activate-environment: true + + - name: Install dependencies + run: | + uv sync --group docs + + - name: Configure git for github-actions + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" + + - name: Deploy Development Docs + if: (github.event_name == 'push' && github.ref == 'refs/heads/dev') || github.event_name == 'workflow_dispatch' + run: | + uv run mike deploy --push dev + + - name: Set Default to Dev + if: (github.event_name == 'push' && github.ref == 'refs/heads/dev') || github.event_name == 'workflow_dispatch' + run: | + uv run mike set-default dev --push + + - name: Deploy Release Docs + if: github.event_name == 'release' && github.event.action == 'published' + run: | + latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`) + uv run mike deploy --push --update-aliases $latest_tag latest + + - name: Deploy Main Docs + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + run: | + uv run mike deploy --push main diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 00000000..791c01e1 Binary files /dev/null and b/docs/assets/favicon.ico differ diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 00000000..1ec94049 Binary files /dev/null and b/docs/assets/logo.png differ diff --git a/docs/cluster/README.md b/docs/cluster/README.md new file mode 120000 index 00000000..84733930 --- /dev/null +++ b/docs/cluster/README.md @@ -0,0 +1 @@ +../../mindtrace/cluster/README.md \ No newline at end of file diff --git a/docs/cluster/api.md b/docs/cluster/api.md new file mode 100644 index 00000000..2580e105 --- /dev/null +++ b/docs/cluster/api.md @@ -0,0 +1,6 @@ +# Cluster Package API Reference +::: mindtrace.cluster + options: + show_root_heading: false + show_source: false + heading_level: 4 \ No newline at end of file diff --git a/docs/core/README.md b/docs/core/README.md new file mode 120000 index 00000000..cf4f9da3 --- /dev/null +++ b/docs/core/README.md @@ -0,0 +1 @@ +../../mindtrace/core/README.md \ No newline at end of file diff --git a/docs/core/api.md b/docs/core/api.md new file mode 100644 index 00000000..d5a9e054 --- /dev/null +++ b/docs/core/api.md @@ -0,0 +1,6 @@ +# Core Package API Reference +::: mindtrace.core + options: + show_root_heading: false + show_source: false + heading_level: 4 \ No newline at end of file diff --git a/docs/database/README.md b/docs/database/README.md new file mode 120000 index 00000000..2640a987 --- /dev/null +++ b/docs/database/README.md @@ -0,0 +1 @@ +../../mindtrace/database/README.md \ No newline at end of file diff --git a/docs/database/api.md b/docs/database/api.md new file mode 100644 index 00000000..2d56b266 --- /dev/null +++ b/docs/database/api.md @@ -0,0 +1,6 @@ +# Database Package API Reference +::: mindtrace.database + options: + show_root_heading: false + show_source: false + heading_level: 4 \ No newline at end of file diff --git a/docs/hardware/README.md b/docs/hardware/README.md new file mode 120000 index 00000000..dc749e48 --- /dev/null +++ b/docs/hardware/README.md @@ -0,0 +1 @@ +../../mindtrace/hardware/README.md \ No newline at end of file diff --git a/docs/hardware/api.md b/docs/hardware/api.md new file mode 100644 index 00000000..131bb081 --- /dev/null +++ b/docs/hardware/api.md @@ -0,0 +1,6 @@ +# Hardware Package API Reference +::: mindtrace.hardware + options: + show_root_heading: false + show_source: false + heading_level: 4 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..f102ac54 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,120 @@ +# :material-rocket-launch: Welcome to Mindtrace + +Unifying asset inspection under a single package, Mindtrace brings together industrial hardware, machine learning, and automation, bridging the gap between edge devices and scalable intelligence. + +Monitor, automate, and scale your on-prem AI solutions effortlessly with **Mindtrace** package. +From training robust AI models, hardware integration to deploying and scaling edge intelligence for **Asset inspection**, Mindtrace enables full-cycle orchestration. + +It seamlessly connects **hardware, data, and machine learning**, empowering teams to deploy context-aware decision systems, derive real-time insights, and visualize results through interactive dashboards + +--- + +## :material-star: Features + + +- :fontawesome-solid-network-wired: **Unified Architecture** + Integrates data ingestion, model training, deployment, and system coordination under one modular ecosystem that scales seamlessly across services and clusters. + +- :material-cpu-64-bit: **Hardware-Aware Intelligence** + Connect directly to PLCs, cameras, and sensors for real-time inference, control, and closed-loop feedback across industrial environments. + +- :material-brain: **ML-Native Design** + Provides end-to-end pipelines for dataset management, model registry, and distributed training workflows. + +- :material-database: **Datalake Integration** + Built-in connectors and APIs for storing, indexing, and retrieving structured or unstructured data — powering analytics, retraining, and traceability. + +- :material-cloud-sync: **Cluster-Aware Orchestration** + Enables coordinated operation across multiple nodes or services, supporting distributed execution and horizontal scaling. + +- :material-account-group: **Service Collaboration Layer** + Seamlessly launch, register, and interconnect FastAPI or MCP-based microservices through a unified control plane and shared state system. + + +--- + +## :material-layers-triple: Layered Architecture + +Mindtrace is organized into a layered workspace to support ML components as Python modules with clearly defined boundaries and dependencies. We use a level-based system for organizing modules based on dependency direction and build order. + +### **Level 1: Core** +- `core`: Foundational utilities and base classes used across all other modules. + +### **Level 2: Core Consumers** +- `jobs`: Job execution and backend interfaces. +- `registry`: Artifact and metadata management. +- `database`: Redis, Mongo, and DB access layers. +- `services`: Service base classes, authentication, and gateways. +- `storage`: Storage functionality for cloud storage integration. +- `ui`: Optional UI libraries and components. + +### **Level 3: Infrastructure Modules** +- `hardware`: Interfaces for cameras, PLCs, scanners, etc. +- `cluster`: Runtime cluster management, nodes, and workers. +- `datalake`: Dataset interfaces for HuggingFace and Mindtrace datasets. +- `models`: Core model definitions and leaderboard utilities. + +### **Level 4: Automation** +- `automation`: Integration of pipelines and orchestration using level 2–3 modules. + +### **Level 5: Applications** +- `apps`: End-user applications composed of all previous levels. + - E.g., Demo pipelines + +--- + +## :material-arrow-down-bold: Dependency Flow + +Each layer only depends on modules in lower levels. + +| Module | Depends On | +|------------|------------------------------------------------------| +| `core` | – | +| `jobs` | `core` | +| `registry` | `core` | +| `database` | `core`, `registry` | +| `services` | `core` | +| `storage` | – | +| `ui` | `core` | +| `cluster` | `core`, `jobs`, `registry`, `database`, `services` | +| `datalake` | `core`, `registry`, `database`, `services` | +| `models` | `core`, `registry`, `services` | +| `hardware` | `core`, `services`, `storage` | +| `automation` | `core`, `registry`, `database`, `services`, `datalake`, `models`, `cluster` | +| `apps` | `core`, `registry`, `database`, `services`, `datalake`, `models`, `cluster`, `jobs`, `hardware`, `ui`, `automation` | + +--- + +## :material-link: Useful Links + +- :material-github: [GitHub Repository](https://github.com/Mindtrace/mindtrace) +- :material-package: [PyPI Package](https://pypi.org/project/mindtrace/) + +--- +## :material-console: Quick Start + +### :material-download: Installation + +```bash +# Install the full Mindtrace package +uv add mindtrace + +# Or install a minimal dependency chain +uv add mindtrace-datalake +``` + +### :material-code-tags: Basic Usage + +```python +from mindtrace import core, registry, database, services +``` + +--- + +## :material-rocket: Contribute + +We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes Mindtrace better. + +- :material-book-open: [Contributing Guide](https://github.com/Mindtrace/mindtrace/blob/dev/CONTRIBUTING.md) - Learn how to get started +- :material-github: [GitHub Issues](https://github.com/Mindtrace/mindtrace/issues) - Report bugs or suggest features +- :material-source-branch: [Pull Requests](https://github.com/Mindtrace/mindtrace/pulls) - Submit your contributions \ No newline at end of file diff --git a/docs/jobs/README.md b/docs/jobs/README.md new file mode 120000 index 00000000..e028feae --- /dev/null +++ b/docs/jobs/README.md @@ -0,0 +1 @@ +../../mindtrace/jobs/README.md \ No newline at end of file diff --git a/docs/jobs/api.md b/docs/jobs/api.md new file mode 100644 index 00000000..6cbff20d --- /dev/null +++ b/docs/jobs/api.md @@ -0,0 +1,6 @@ +# Jobs Package API Reference +::: mindtrace.jobs + options: + show_root_heading: false + show_source: false + heading_level: 4 \ No newline at end of file diff --git a/docs/services/README.md b/docs/services/README.md new file mode 120000 index 00000000..7fa70e5e --- /dev/null +++ b/docs/services/README.md @@ -0,0 +1 @@ +../../mindtrace/services/README.md \ No newline at end of file diff --git a/docs/services/api.md b/docs/services/api.md new file mode 100644 index 00000000..4c49255c --- /dev/null +++ b/docs/services/api.md @@ -0,0 +1,6 @@ +# Services Package API Reference +::: mindtrace.services + options: + show_root_heading: false + show_source: false + heading_level: 4 \ No newline at end of file diff --git a/docs/storage/README.md b/docs/storage/README.md new file mode 120000 index 00000000..264e14ca --- /dev/null +++ b/docs/storage/README.md @@ -0,0 +1 @@ +../../mindtrace/storage/README.md \ No newline at end of file diff --git a/docs/storage/api.md b/docs/storage/api.md new file mode 100644 index 00000000..4ebcbed0 --- /dev/null +++ b/docs/storage/api.md @@ -0,0 +1,6 @@ +# Storage Package API Reference +::: mindtrace.storage + options: + show_root_heading: false + show_source: false + heading_level: 4 \ No newline at end of file diff --git a/mindtrace/core/README.md b/mindtrace/core/README.md index 3a7a208f..1dab3c24 100644 --- a/mindtrace/core/README.md +++ b/mindtrace/core/README.md @@ -50,7 +50,7 @@ The core module is organized into several submodules: ### Logging (`logging/`) - Structured logging configuration and utilities -## API Reference + ### Core Classes @@ -78,7 +78,7 @@ print(config["MINDTRACE_DIR_PATHS"]["TEMP"]) print(config.MINDTRACE_DIR_PATHS.TEMP) ``` -For detailed usage of the Config class—including how it’s used within the Mindtrace class—refer to the [Usage documentation](../../samples/core/config/README.md) +For detailed usage of the Config class—including how it's used within the Mindtrace class—refer to the [Usage documentation](https://github.com/Mindtrace/mindtrace/tree/dev/samples/core/config) #### `Logging` The `get_logger` function provides a unified way to configure logging across your application. It can return either a standard Python logger or a structlog @@ -285,4 +285,3 @@ Dynamically instantiate a class from string reference. from mindtrace.core import instantiate_target instance = instantiate_target("my.module.MyClass", param="value") ``` - diff --git a/mindtrace/services/README.md b/mindtrace/services/README.md index 93953179..fd155508 100644 --- a/mindtrace/services/README.md +++ b/mindtrace/services/README.md @@ -9,7 +9,7 @@ [Architecture](#architecture)
[Auto-generation for Connection Managers](#auto-generation-for-connection-managers)
[Usage Example](#usage-example)
-[Testing & Coverage](#testing--coverage)
+[Testing & Coverage](#testing-and-coverage)
[API Reference](#api-reference)
[MCP Integration: Exposing Service Endpoints as Tools](#mcp-integration-exposing-service-endpoints-as-tools)
[Remote MCP Server Usage with Cursor](#remote-mcp-server-usage-with-cursor) @@ -69,7 +69,7 @@ cm.status() # now generated as a method ## Usage Example -See [`mindtrace/services/sample/echo_service.py`](./mindtrace/services/sample/echo_service.py) for a full example. Basic usage: +See [`mindtrace/services/sample/echo_service.py`](https://github.com/Mindtrace/mindtrace/blob/dev/mindtrace/services/sample/echo_service.py) for a full example. Basic usage: ```python from mindtrace.services import Service @@ -115,7 +115,7 @@ class EchoService(Service): return EchoOutput(echoed=payload.message) ``` -## Testing & Coverage +## Testing and Coverage The test runner supports unit, integration, and stress tests: @@ -181,7 +181,7 @@ The Model Context Protocol (MCP) is a protocol for exposing service functionalit This makes the `echo` function available both as a REST endpoint and as an MCP tool. ### Example: EchoService with MCP -See [`mindtrace/services/sample/echo_mcp.py`](./mindtrace/services/sample/echo_mcp.py): +See [`mindtrace/services/sample/echo_mcp.py`](https://github.com/Mindtrace/mindtrace/blob/dev/mindtrace/services/sample/echo_mcp.py): ```python from mindtrace.services.samples.echo_mcp import EchoService @@ -286,9 +286,9 @@ asyncio.run(main()) - The MCP client allows you to list and call tools programmatically. For trial purposes, see the sample files: -- [`mindtrace/services/sample/echo_mcp.py`](./mindtrace/services/sample/echo_mcp.py) -- [`samples/services/echo_mcp_service.py`](../../samples/services/echo_mcp_service.py) -- [`samples/services/mcp/mcp_client.py`](../../samples/services/mcp/mcp_client.py) +- [`mindtrace/services/sample/echo_mcp.py`](https://github.com/Mindtrace/mindtrace/blob/dev/mindtrace/services/sample/echo_mcp.py) +- [`samples/services/echo_mcp_service.py`](https://github.com/Mindtrace/mindtrace/blob/dev/samples/services/echo_mcp_service.py) +- [`samples/services/mcp/mcp_client.py`](https://github.com/Mindtrace/mindtrace/blob/dev/samples/services/mcp/mcp_client.py) ## Remote MCP Server Usage with Cursor diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..8dcf9c18 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,124 @@ +site_name: Mindtrace Package Docs +site_url: https://mindtrace.ai +repo_url: https://github.com/Mindtrace/mindtrace + +extra: + social: + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/company/mindtrace-ai + generator: false + + +nav: + - Home: index.md + - Mindtrace: + - Core: core/README.md + - Services: services/README.md + - Hardware: hardware/README.md + - Cluster: cluster/README.md + - Jobs: jobs/README.md + - Database: database/README.md + - Storage: storage/README.md + + + - API Reference: + - Core: core/api.md + - Services: services/api.md + - Hardware: hardware/api.md + - Cluster: cluster/api.md + - Jobs: jobs/api.md + - Database: database/api.md + - Storage: storage/api.md + +plugins: + - search + - mkdocstrings: + handlers: + python: + options: + docstring_style: google + show_source: true + show_root_heading: true + show_root_toc_entry: true + show_signature_annotations: true + show_signature_return_annotation: true + show_bases: true + show_submodules: true + merge_init_into_class: true + show_if_no_docstring: false + show_signature: true + separate_signature: true + line_length: 80 + max_depth: 3 + filters: ["!^_"] + members_order: source + docstring_section_style: table + show_docstring_attributes: true + show_docstring_examples: true + show_docstring_parameters: true + show_docstring_raises: true + show_docstring_returns: true + show_docstring_summary: true + +theme: + name: material + font: + text: Inter + code: JetBrains Mono + icon: + repo: fontawesome/brands/github + logo: assets/logo.png + favicon: assets/favicon.ico + features: + - navigation.tabs + - navigation.footer + - navigation.top + - navigation.expand + - navigation.tabs.sticky + - search.suggest + - search.highlight + - search.share + + # - navigation.sections + + palette: + # Dark Mode + - scheme: slate + toggle: + icon: material/weather-sunny + name: Dark mode + primary: deep purple + accent: green + + # Light Mode + - scheme: default + toggle: + icon: material/weather-night + name: Light mode + primary: deep purple + accent: deep orange + +markdown_extensions: + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - admonition + - pymdownx.details + + + +copyright: Copyright © 2025 Mindtrace diff --git a/pyproject.toml b/pyproject.toml index 492db805..38d61811 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,6 +46,14 @@ dev = [ "pre-commit>=4.2.0", "twine>=6.1.0", ] +docs = [ + "mkdocs-material>=9.6.21", + "mkdocstrings[python]>=0.30.1", + "mike>=2.0.0", + "mkdocs-git-committers-plugin-2>=2.4.1", + "mkdocs-git-revision-date-localized-plugin>=1.2.4", + "mkdocs-jupyter>=0.24.3", +] [project.urls] Homepage = "https://mindtrace.ai"