# This resource guide is derived from the GAM7 project documentation:
# https://github.com/GAM-team/GAM/wiki/Bulk-Processing
# Copyright (C) GAM-team and contributors
# Licensed under the Apache License, Version 2.0
# https://www.apache.org/licenses/LICENSE-2.0
#
# Modifications: Condensed and reformatted as an MCP resource reference.
# This file (including modifications) is distributed under MIT License,
# with the above Apache-2.0 attribution preserved for the original documentation content.


# resources/bulk_processing.py

def register(mcp):
    @mcp.resource("gam://bulk-processing-guide", mime_type="text/markdown")
    def bulk_processing_guide() -> str:
        """
        Reference guide for constructing GAM bulk processing commands.
        Consult this resource when building a bulk operation to select the correct
        source type, processing mode, and column substitution syntax.
        """
        return _BULK_GUIDE

_BULK_GUIDE = """
# GAM Bulk Processing Reference

## Source Types
- Local CSV:     gam csv /path/to/file.csv gam <args>
- Google Sheet:  gam csv gsheet <operator_email> <fileID> "<sheetName>" gam <args>
- Google Doc:    gam batch gdoc <operator_email> <docID>
- stdin:         gam csv - gam <args>

## Processing Modes
- csv    → parallel (multi-process); supports gsheet/gdoc sources
- loop   → serial; same syntax as csv; use for rate-sensitive operations
- batch  → parallel from a .bat file; nested gam csv is NOT allowed
- tbatch → parallel threads from a .bat file; nested gam csv IS allowed

## Column Substitution
- ~ColumnName         → standalone arg replaced by that column's value
- ~~ColumnName~~      → embedded in a string: "prefix_~~ColumnName~~_suffix"
- ~~Col~!~pattern~!~replacement~~ → regex substitution via re.sub()

## Redirect + Multiprocess (required for parallel output)
gam redirect csv ./output.csv multiprocess csv Users.csv gam user "~primaryEmail" print filelist
gam redirect csv - multiprocess todrive csv Users.csv gam user "~primaryEmail" print filelist

## Write Results to Google Sheet (todrive)
Append to any redirect csv command:
  todrive tdfileid <sheetFileID> tdsheet "<sheetName>" tdupdatesheet

## Batch File Directives
- commit-batch  → wait for running commands before continuing
- sleep <N>     → pause N seconds
- set <K> <V>   → define substitution variable; use %K% in subsequent lines
- clear <K>     → remove a substitution variable
- print <text>  → write to stderr
- execute <cmd> → (tbatch only) run an external program

## Parallelism Config (gam.cfg)
- num_threads          → csv/loop parallelism
- num_tbatch_threads   → tbatch parallelism
- auto_batch_min       → auto-batch when entity count exceeds N
"""
