# [DEF:Shot:Plugin_Example:Example]
# @PURPOSE: Reference implementation of a plugin following GRACE standards.
# @RELATION: IMPLEMENTS -> [DEF:Std:Plugin]

from typing import Dict, Any, Optional
from ..core.plugin_base import PluginBase
from ..core.task_manager.context import TaskContext

class ExamplePlugin(PluginBase):
    @property
    def id(self) -> str:
        return "example-plugin"

    @property
    def name(self) -> str:
        return "Example Plugin"

    @property
    def description(self) -> str:
        return "A simple plugin that demonstrates structured logging and progress tracking."

    @property
    def version(self) -> str:
        return "1.0.0"

    # [DEF:get_schema:Function]
    # @PURPOSE: Defines input validation schema.
    def get_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string",
                    "title": "Message",
                    "description": "A message to log.",
                    "default": "Hello, GRACE!",
                }
            },
            "required": ["message"],
        }
    # [/DEF:get_schema:Function]

    # [DEF:execute:Function]
    # @PURPOSE: Core plugin logic with structured logging and progress reporting.
    # @PARAM: params (Dict) - Validated input parameters.
    # @PARAM: context (TaskContext) - Execution context with logging and progress tools.
    async def execute(self, params: Dict[str, Any], context: Optional[TaskContext] = None):
        message = params["message"]
        
        # 1. Action: Structured Logging with Source Attribution
        if context:
            log = context.logger.with_source("example_plugin")
            log.info(f"Starting execution with message: {message}")

            # 2. Action: Progress Reporting
            log.progress("Processing step 1...", percent=25)
            # Simulating some async work...
            # await some_async_op()

            log.progress("Processing step 2...", percent=75)
            log.info("Execution completed successfully.")
        else:
            # Fallback for manual/standalone execution
            print(f"Standalone execution: {message}")
    # [/DEF:execute:Function]

# [/DEF:Shot:Plugin_Example]