refactor(moderation): Migrate to new plugin architecture (match OCR)

[rogermt]

Summary

Moderation plugin needs architecture updates to match OCR's production-ready design and become compatible with new ForgeSyte plugin system.

Current Status

❌ NOT YET COMPATIBLE with new architecture

• Partially migrated to BasePlugin
• Uses outdated schema format
• Hard-coupled to server via app.models imports
• Tests in wrong directory structure

Required Changes

1. Plugin Structure & BasePlugin Contract

• Add fallback BasePlugin import for testing (no app.* import required)
• Fix tools dict schema: replace inputs/outputs with input_schema/output_schema
• Use Pydantic model_json_schema() like OCR plugin
• Remove metadata() method (not part of BasePlugin contract)
• Ensure run_tool() returns plugin output schema, not AnalysisResult

2. Input/Output Schemas

• Create ModerationInput Pydantic model

  class ModerationInput(BaseModel):
      image_bytes: bytes
      options: Optional[dict[str, Any]] = None

• Create ModerationOutput Pydantic model

  class ModerationOutput(BaseModel):
      categories: list[dict[str, Any]]
      overall_confidence: float
      is_safe: bool
      recommendation: str
      error: Optional[str] = None

• Remove dependency on app.models.AnalysisResult
• Export schemas in __all__ for public API
• Replace TypedDict with Pydantic models

3. Dependencies & Portability

• Remove all from app.* imports except BasePlugin
• Add BasePlugin fallback import for standalone testing
• Remove from app.plugins.base import BasePlugin hard import
• Plugin must be testable without server environment
• Ensure all returns use new output schema, not AnalysisResult

4. Test Structure

• Move tests from src/tests/ to src/forgesyte_moderation/tests/
• Update conftest.py path references
• Ensure tests don't import from app.*
• Add contract tests like OCR

5. Project Configuration

• Add pytest-cov>=4.0.0 to dev dependencies
• Add types-Pillow>=10.0.0 to dev dependencies
• Add black tool config section
• Add ruff tool config section
• Add mypy tool config section
• Fix pytest testpaths to match new test location

6. Code Quality

• Remove TypedDict, use Pydantic exclusively
• Add docstrings to all public methods
• Fix all code paths to return proper output schema type
• Keep placeholder implementation for now (real model later)

Reference

See OCR plugin architecture for correct pattern:

forgesyte-plugins/plugins/ocr/src/forgesyte_ocr/
├── plugin.py          # BasePlugin with fallback import
├── schemas.py         # Pydantic input/output schemas
├── ocr_engine.py      # Business logic
└── tests/             # Tests in proper location

Acceptance Criteria

• All 6 categories above are complete
• Plugin schema matches OCR format exactly
• No imports from app.* in plugin code
• Tests pass locally
• Ruff, Black, Mypy all pass
• Plugin can be installed standalone: pip install -e .
• Plugin integrates with new ForgeSyte architecture

Estimated Effort

• Schema creation: 30 min
• Tools dict fixes: 15 min
• Import refactoring: 20 min
• Test restructure: 10 min
• Config updates: 5 min
• TypedDict replacement: 15 min
• Total: ~95 minutes

Labels

refactor, plugins, architecture, breaking-change