[Issue 191] Transformer Scaffolding

lib/python-sdk/DEVELOPMENT.md

@@ -7,51 +7,196 @@ This document provides instructions for common development tasks in the CommonGr
 - Python 3.11 or higher
 - Poetry for dependency management
 
-## Development Commands
-
-### Setup
-
-The commands described in this guide should be run from the `python-sdk` directory:
-```bash
-cd simpler-grants-protocol/lib/python-sdk
-```
+## Dependencies
 
 Install dependencies:
 ```bash
+cd simpler-grants-protocol/lib/python-sdk
 poetry install
 ```
 
-### Testing
+## Code Quality & Testing
+
+### Tests
 
 Run all tests:
 ```bash
-poetry run pytest
+cd simpler-grants-protocol/lib/python-sdk
+poetry run pytest tests/ -v
 ```
 
 Run tests with coverage report:
 ```bash
+cd simpler-grants-protocol/lib/python-sdk
 poetry run pytest --cov=common_grants --cov-report=term-missing
 ```
 
-### Code Quality
-
-#### Formatting
+### Formatting
 
 Format code with Black:
 ```bash
+cd simpler-grants-protocol/lib/python-sdk
 poetry run black .
 ```
 
-#### Linting
+### Linting
 
 Check code with Ruff:
 ```bash
+cd simpler-grants-protocol/lib/python-sdk
 poetry run ruff check .
 ```
 
-#### Type Checking
+### Type Checking
 
 Verify types with MyPy:
 ```bash
+cd simpler-grants-protocol/lib/python-sdk
 poetry run mypy .
 ```
+
+## Usage Examples
+
+### Initialize Opportunity Model Instance
+
+```python
+from datetime import datetime, date, UTC
+from uuid import uuid4
+
+from common_grants.schemas.fields import Money, Event
+from common_grants.schemas.models.opp_base import OpportunityBase
+from common_grants.schemas.models.opp_funding import OppFunding
+from common_grants.schemas.models.opp_status import OppStatus, OppStatusOptions
+from common_grants.schemas.models.opp_timeline import OppTimeline
+
+# Create a new opportunity
+opportunity = OpportunityBase(
+    id=uuid4(),
+    title="Research Grant 2024",
+    description="Funding for innovative research projects",
+    status=OppStatus(
+        value=OppStatusOptions.OPEN,
+        description="This opportunity is currently accepting applications"
+    ),
+    created_at=datetime.now(UTC),
+    last_modified_at=datetime.now(UTC),
+    funding=OppFunding(
+        total_amount_available=Money(amount="100000.00", currency="USD"),
+        min_award_amount=Money(amount="10000.00", currency="USD"),
+        max_award_amount=Money(amount="50000.00", currency="USD"),
+        estimated_award_count=5
+    ),
+    key_dates=OppTimeline(
+        app_opens=Event(
+            name="Application Opens",
+            date=date(2024, 1, 1),
+            description="Applications open"
+        ),
+        app_deadline=Event(
+            name="Application Deadline",
+            date=date(2024, 3, 31),
+            description="Applications close"
+        )
+    )
+)
+```
+
+### Serialize / Deserialize
+
+```python
+# Create an opportunity instance
+opportunity = OpportunityBase(
+    ...
+)
+
+# Serialize to JSON
+json_data = opportunity.dump_json()
+
+# Deserialize from JSON
+loaded_opportunity = OpportunityBase.from_json(json_data)
+```
+
+### Transform Data Sources and Models
+
+When extending an existing system to adopt the CommonGrants protocol, a developer might need to transform existing data model implementations or data sources into canonical model instances. Such custom transformations can be easily implemented by leveraging the abstract base class `OpportunityTransformer`. 
+
+The `OpportunityTransformer` base class defines a standard interface for transforming raw input data (from third-party feeds, legacy formats, custom JSON, etc.) into structured `OpportunityBase` instances. As an abstract base class, `OpportunityTransformer` itself *does not contain any transformation logic*; custom transformation logic must be implemented by subclassing the abstract base class (see following example).
+
+#### Custom Transformer Example
+
+```python
+from uuid import UUID
+from transformers.base import OpportunityTransformer
+from common_grants_sdk.schemas.models.opp_funding import OppFunding
+from common_grants_sdk.schemas.models.opp_status import OppStatus, OppStatusOptions
+from common_grants_sdk.schemas.models.opp_timeline import OppTimeline
+from common_grants_sdk.schemas.fields import Event, Money
+from datetime import date
+
+class LegacyGrantDataTransformer(OpportunityTransformer):
+
+    def transform_opportunity_description(self) -> str:
+        return self.source_data.get("grant_description", "Description")
+
+    def transform_opportunity_funding(self) -> OppFunding:
+        total_award = self.source_data.get("total_award", 0)
+        min_award = self.source_data.get("min_award", 0)
+        max_award = self.source_data.get("max_award", 0)
+        currency = self.source_data.get("award_currency", "USD")
+        return OppFunding(
+            total_amount_available=Money(amount=total_award, currency=currency),
+            min_award_amount=Money(amount=min_award, currency=currency),
+            max_award_amount=Money(amount=max_award, currency=currency),
+            estimated_award_count=10
+        )
+
+    def transform_opportunity_status(self) -> OppStatus:
+        return OppStatus(
+            value=OppStatusOptions.FORECASTED,
+            description="Grant opportunity status"
+        )
+
+    def transform_opportunity_timeline(self) -> OppTimeline:
+        start_date = self.source_data.get("start_date")
+        end_date = self.source_data.get("end_date")
+        return OppTimeline(
+            app_opens=Event(
+                name="Application Open",
+                date=date.fromisoformat(start_date),
+                description="Start date for application submission"
+            ),
+            app_deadline=Event(
+                name="Application Deadline",
+                date=date.fromisoformat(end_date),
+                description="Deadline for submission"
+            )
+        )
+
+    def transform_opportunity_title(self) -> str:
+        return self.source_data.get("grant_name", "Title")
+```
+
+Usage of the custom transformer:
+
+```python
+# Define source data
+source_data = {
+    "grant_name": "Small Business Research Grant",
+    "grant_description": "Funding for early-stage R&D.",
+    "start_date": "2026-06-01",
+    "end_date": "2026-08-31",
+    "total_award": 2000000,
+    "min_award": 10000,
+    "max_award": 50000,
+    "award_count" 10
+}
+
+# Instantiate transformer
+transformer = LegacyGrantFeedTransformer(source_data=source_data)
+
+# Execute transformation to instantiate an opportunity model instance
+opportunity = transformer.transform_opportunity()
+
+# Output the opportunity model instance as json
+print(opportunity.model_dump_json(indent=2))
+```

lib/python-sdk/README.md

@@ -19,7 +19,7 @@ pip install common-grants-python-sdk
 poetry add common-grants-python-sdk
 ```
 
-## Quick Start
+## Example Usage
 
 ```python
 from datetime import datetime, date, UTC
@@ -90,3 +90,7 @@ loaded_opportunity = OpportunityBase.from_json(json_data)
 - `OppStatus`: Opportunity status tracking
 - `OppTimeline`: Key dates and milestones
 
+## Development Guide
+
+For technical details, see the [Developer Guide](./DEVELOPMENT.md).
+

lib/python-sdk/common_grants_sdk/schemas/models/__init__.py

@@ -4,11 +4,13 @@
 from .opp_funding import OppFunding
 from .opp_status import OppStatus, OppStatusOptions
 from .opp_timeline import OppTimeline
+from .opp_transformer import OpportunityTransformer
 
 __all__ = [
     "OpportunityBase",
     "OppFunding",
     "OppStatus",
     "OppStatusOptions",
     "OppTimeline",
+    "OpportunityTransformer",
 ]

lib/python-sdk/common_grants_sdk/schemas/models/opp_transformer.py

@@ -0,0 +1,98 @@
+from abc import ABC, abstractmethod
+from datetime import datetime, UTC
+from typing import Annotated, Any, final
+from uuid import UUID, uuid4
+
+from pydantic import Field
+
+from common_grants_sdk.schemas.base import CommonGrantsBaseModel
+from common_grants_sdk.schemas.models.opp_base import OpportunityBase
+from common_grants_sdk.schemas.models.opp_funding import OppFunding
+from common_grants_sdk.schemas.models.opp_status import OppStatus
+from common_grants_sdk.schemas.models.opp_timeline import OppTimeline
+
+
+class OpportunityTransformer(CommonGrantsBaseModel, ABC):
+    """
+    Base class for transforming arbitrary data structures
+    into canonical models.
+    """
+
+    source_data: Annotated[
+        dict[str, Any],
+        Field(
+            description="Arbitrary source data",
+        ),
+    ]
+
+    def transform_opportunity(self, id: UUID | None = None) -> OpportunityBase:
+        """
+        Extract and transform opportunity data from source_data
+        into a canonical OpportunityBase model instance.
+        """
+
+        return OpportunityBase(
+            id=id or self._generate_id(),
+            title=self.transform_opportunity_title(),
+            description=self.transform_opportunity_description(),
+            status=self.transform_opportunity_status(),
+            funding=self.transform_opportunity_funding(),
+            key_dates=self.transform_opportunity_timeline(),
+            created_at=self._current_timestamp(),
+            last_modified_at=self._current_timestamp(),
+        )
+
+    @abstractmethod
+    def transform_opportunity_description(self) -> str:
+        """
+        Extract and transform description data from source_data
+        into a canonical description string.
+        """
+
+        pass
+
+    @abstractmethod
+    def transform_opportunity_funding(self) -> OppFunding:
+        """
+        Extract and transform funding data from source_data
+        into a canonical OppFunding model instance.
+        """
+
+        pass
+
+    @abstractmethod
+    def transform_opportunity_status(self) -> OppStatus:
+        """
+        Extract and transform status data from source_data
+        into a canonical OppStatus model instance.
+        """
+
+        pass
+
+    @abstractmethod
+    def transform_opportunity_timeline(self) -> OppTimeline:
+        """
+        Extract and transform timeline data from source_data
+        into a canonical OppTimeline model instance.
+        """
+
+        pass
+
+    @abstractmethod
+    def transform_opportunity_title(self) -> str:
+        """
+        Extract and transform title data from source_data
+        into a canonical title string.
+        """
+
+        pass
+
+    @final
+    def _generate_id(self) -> UUID:
+        """Generate unique ID for the opportunity."""
+        return uuid4()
+
+    @final
+    def _current_timestamp(self) -> datetime:
+        """Get current timestamp."""
+        return datetime.now(UTC)