metadata-curation-client 0.1.0__tar.gz

metadata_curation_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Digital Edition Curation Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metadata_curation_client-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: metadata-curation-client
+Version: 0.1.0
+Summary: API client for metadata curation platforms
+Author: Digital Edition Curation Team
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/digital-edition-curation
+Project-URL: Repository, https://github.com/yourusername/digital-edition-curation
+Project-URL: Issues, https://github.com/yourusername/digital-edition-curation/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# Metadata Curation Client
+
+API client for external partners to integrate with metadata curation platforms.
+
+## Installation
+
+```bash
+pip install metadata-curation-client
+```
+
+## Basic Usage
+
+```python
+from metadata_curation_client import CurationAPIClient, PropertyType
+
+# Initialize client
+client = CurationAPIClient("http://localhost:8000")
+
+# Create source
+source = client.create_source({
+    "name": "My Archive",
+    "description": "Digital editions from our collection"
+})
+
+# Create controlled vocabulary property
+language_prop = client.create_property({
+    "technical_name": "language",
+    "name": "Language", 
+    "type": PropertyType.CONTROLLED_VOCABULARY,
+    "source_id": source["id"],
+    "property_options": [{"name": "English"}, {"name": "German"}]
+})
+
+# Create free text property
+description_prop = client.create_property({
+    "technical_name": "description",
+    "name": "Description", 
+    "type": PropertyType.FREE_TEXT,
+    "source_id": source["id"]
+})
+
+# Create edition
+edition = client.create_edition({
+    "source_id": source["id"],
+    "source_internal_id": "my_001"
+})
+
+# Create properties for each type
+genre_prop = client.create_property({
+    "technical_name": "genre",
+    "name": "Genre", 
+    "type": PropertyType.CONTROLLED_VOCABULARY,
+    "source_id": source["id"],
+    "property_options": [
+        {"name": "Poetry"}, {"name": "Prose"}, {"name": "Drama"}
+    ]
+})
+
+has_annotations_prop = client.create_property({
+    "technical_name": "has_annotations",
+    "name": "Has Annotations", 
+    "type": PropertyType.BINARY,
+    "source_id": source["id"]
+})
+
+year_prop = client.create_property({
+    "technical_name": "publication_year",
+    "name": "Publication Year", 
+    "type": PropertyType.NUMERICAL,
+    "source_id": source["id"]
+})
+
+description_prop = client.create_property({
+    "technical_name": "description",
+    "name": "Description", 
+    "type": PropertyType.FREE_TEXT,
+    "source_id": source["id"]
+})
+
+# Example 1: CONTROLLED_VOCABULARY suggestion
+# First get the property option ID
+properties = client.get_properties()
+genre_prop = next(p for p in properties if p["technical_name"] == "genre")
+poetry_option = next(opt for opt in genre_prop["property_options"] if opt["name"] == "Poetry")
+
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": genre_prop["id"],
+    "property_option_id": poetry_option["id"]
+})
+
+# Example 2: BINARY suggestion (uses property_option_id)
+# Binary properties always have options with ID 1 (true/1) and ID 2 (false/0)
+# Get the "true" option (usually ID 1)
+binary_props = client.get_properties()
+has_annotations_prop = next(p for p in binary_props if p["technical_name"] == "has_annotations")
+true_option = next(opt for opt in has_annotations_prop["property_options"] if opt["name"] == "1")
+
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": has_annotations_prop["id"],
+    "property_option_id": true_option["id"]  # For "yes"/"true" value
+})
+
+# Example 3: NUMERICAL suggestion (uses custom_value)
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": year_prop["id"],
+    "custom_value": "2025"  # Note: numerical values are sent as strings
+})
+
+# Example 4: FREE_TEXT suggestion (uses custom_value)
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": description_prop["id"],
+    "custom_value": "This is a detailed description of the edition."
+})
+
+# Mark ingestion complete
+client.mark_ingestion_complete(source["id"])
+```
+
+## Property Types
+
+- `PropertyType.CONTROLLED_VOCABULARY` - Predefined options
+- `PropertyType.FREE_TEXT` - Free text
+- `PropertyType.BINARY` - True/false values
+- `PropertyType.NUMERICAL` - Numeric values
+
+## API Reference
+
+See the docstrings in `curation_api_client.py` for detailed method documentation.
+
+## Enhanced Integration with SourceManager
+
+For more sophisticated integrations, we also provide a higher-level abstraction in `source_manager.py` that mirrors some of the conveniences of our internal extractors:
+
+```python
+from metadata_curation_client import CurationAPIClient, PropertyType, SourceManager, PropertyBuilder
+
+# Initialize client and create source
+client = CurationAPIClient("http://localhost:8000")
+source = client.get_source_by_technical_name("my_data_source")
+if not source:
+    source = client.create_source({
+        "name": "My Data Source",
+        "description": "My collection of digital editions",
+        "technical_name": "my_data_source"
+    })
+
+# Define properties using helper builders
+property_definitions = [
+    PropertyBuilder.controlled_vocabulary(
+        "example_genre", "Genre", ["Poetry", "Prose", "Drama"]
+    ),
+    PropertyBuilder.binary(
+        "example_has_annotations", "Has Annotations"
+    ),
+    PropertyBuilder.numerical(
+        "example_year", "Publication Year"
+    )
+]
+
+# Initialize the source manager - this will:
+# - Fetch all existing data
+# - Build lookup tables
+# - Create any missing properties
+manager = SourceManager(client, source['id'], property_definitions)
+
+# Efficiently get or create edition using lookup tables
+edition = manager.get_or_create_edition("book_001")
+
+# Create suggestions in a batch with validation and deduplication
+manager.create_suggestions_batch(
+    edition["id"],
+    {
+        "example_genre": "Poetry",
+        "example_has_annotations": True,
+        "example_year": 2022
+    }
+)
+
+# Mark ingestion complete (updates timestamp)
+manager.finish_ingestion()
+```
+
+### Benefits of the SourceManager
+
+The `SourceManager` provides several advantages for more complex integrations:
+
+1. **Reduced API Calls**: Prefetches data to minimize API requests
+2. **Lookup Tables**: Maintains efficient in-memory lookups for editions, properties, and suggestions
+3. **Automatic Property Creation**: Creates properties from definitions as needed
+4. **Validation**: Automatically validates values based on property types
+5. **Deduplication**: Avoids creating duplicate suggestions
+6. **Builder Helpers**: Provides convenient builder classes for creating properties and sources
+7. **Timestamp Management**: Automatically updates the last ingestion timestamp
+
+For a complete example, see `example_with_source_manager.py`.
+
+### Choosing the Right Approach
+
+- **Basic API Client**: For simple integrations or when you need complete control over the process
+- **SourceManager**: For more complex integrations where efficiency and convenience are priorities
+
+Both approaches use the same underlying API endpoints and data models, so you can choose the one that best fits your needs or even mix them as required.

metadata_curation_client-0.1.0/README.md

@@ -0,0 +1,210 @@
+# Metadata Curation Client
+
+API client for external partners to integrate with metadata curation platforms.
+
+## Installation
+
+```bash
+pip install metadata-curation-client
+```
+
+## Basic Usage
+
+```python
+from metadata_curation_client import CurationAPIClient, PropertyType
+
+# Initialize client
+client = CurationAPIClient("http://localhost:8000")
+
+# Create source
+source = client.create_source({
+    "name": "My Archive",
+    "description": "Digital editions from our collection"
+})
+
+# Create controlled vocabulary property
+language_prop = client.create_property({
+    "technical_name": "language",
+    "name": "Language", 
+    "type": PropertyType.CONTROLLED_VOCABULARY,
+    "source_id": source["id"],
+    "property_options": [{"name": "English"}, {"name": "German"}]
+})
+
+# Create free text property
+description_prop = client.create_property({
+    "technical_name": "description",
+    "name": "Description", 
+    "type": PropertyType.FREE_TEXT,
+    "source_id": source["id"]
+})
+
+# Create edition
+edition = client.create_edition({
+    "source_id": source["id"],
+    "source_internal_id": "my_001"
+})
+
+# Create properties for each type
+genre_prop = client.create_property({
+    "technical_name": "genre",
+    "name": "Genre", 
+    "type": PropertyType.CONTROLLED_VOCABULARY,
+    "source_id": source["id"],
+    "property_options": [
+        {"name": "Poetry"}, {"name": "Prose"}, {"name": "Drama"}
+    ]
+})
+
+has_annotations_prop = client.create_property({
+    "technical_name": "has_annotations",
+    "name": "Has Annotations", 
+    "type": PropertyType.BINARY,
+    "source_id": source["id"]
+})
+
+year_prop = client.create_property({
+    "technical_name": "publication_year",
+    "name": "Publication Year", 
+    "type": PropertyType.NUMERICAL,
+    "source_id": source["id"]
+})
+
+description_prop = client.create_property({
+    "technical_name": "description",
+    "name": "Description", 
+    "type": PropertyType.FREE_TEXT,
+    "source_id": source["id"]
+})
+
+# Example 1: CONTROLLED_VOCABULARY suggestion
+# First get the property option ID
+properties = client.get_properties()
+genre_prop = next(p for p in properties if p["technical_name"] == "genre")
+poetry_option = next(opt for opt in genre_prop["property_options"] if opt["name"] == "Poetry")
+
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": genre_prop["id"],
+    "property_option_id": poetry_option["id"]
+})
+
+# Example 2: BINARY suggestion (uses property_option_id)
+# Binary properties always have options with ID 1 (true/1) and ID 2 (false/0)
+# Get the "true" option (usually ID 1)
+binary_props = client.get_properties()
+has_annotations_prop = next(p for p in binary_props if p["technical_name"] == "has_annotations")
+true_option = next(opt for opt in has_annotations_prop["property_options"] if opt["name"] == "1")
+
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": has_annotations_prop["id"],
+    "property_option_id": true_option["id"]  # For "yes"/"true" value
+})
+
+# Example 3: NUMERICAL suggestion (uses custom_value)
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": year_prop["id"],
+    "custom_value": "2025"  # Note: numerical values are sent as strings
+})
+
+# Example 4: FREE_TEXT suggestion (uses custom_value)
+client.create_suggestion({
+    "source_id": source["id"],
+    "edition_id": edition["id"],
+    "property_id": description_prop["id"],
+    "custom_value": "This is a detailed description of the edition."
+})
+
+# Mark ingestion complete
+client.mark_ingestion_complete(source["id"])
+```
+
+## Property Types
+
+- `PropertyType.CONTROLLED_VOCABULARY` - Predefined options
+- `PropertyType.FREE_TEXT` - Free text
+- `PropertyType.BINARY` - True/false values
+- `PropertyType.NUMERICAL` - Numeric values
+
+## API Reference
+
+See the docstrings in `curation_api_client.py` for detailed method documentation.
+
+## Enhanced Integration with SourceManager
+
+For more sophisticated integrations, we also provide a higher-level abstraction in `source_manager.py` that mirrors some of the conveniences of our internal extractors:
+
+```python
+from metadata_curation_client import CurationAPIClient, PropertyType, SourceManager, PropertyBuilder
+
+# Initialize client and create source
+client = CurationAPIClient("http://localhost:8000")
+source = client.get_source_by_technical_name("my_data_source")
+if not source:
+    source = client.create_source({
+        "name": "My Data Source",
+        "description": "My collection of digital editions",
+        "technical_name": "my_data_source"
+    })
+
+# Define properties using helper builders
+property_definitions = [
+    PropertyBuilder.controlled_vocabulary(
+        "example_genre", "Genre", ["Poetry", "Prose", "Drama"]
+    ),
+    PropertyBuilder.binary(
+        "example_has_annotations", "Has Annotations"
+    ),
+    PropertyBuilder.numerical(
+        "example_year", "Publication Year"
+    )
+]
+
+# Initialize the source manager - this will:
+# - Fetch all existing data
+# - Build lookup tables
+# - Create any missing properties
+manager = SourceManager(client, source['id'], property_definitions)
+
+# Efficiently get or create edition using lookup tables
+edition = manager.get_or_create_edition("book_001")
+
+# Create suggestions in a batch with validation and deduplication
+manager.create_suggestions_batch(
+    edition["id"],
+    {
+        "example_genre": "Poetry",
+        "example_has_annotations": True,
+        "example_year": 2022
+    }
+)
+
+# Mark ingestion complete (updates timestamp)
+manager.finish_ingestion()
+```
+
+### Benefits of the SourceManager
+
+The `SourceManager` provides several advantages for more complex integrations:
+
+1. **Reduced API Calls**: Prefetches data to minimize API requests
+2. **Lookup Tables**: Maintains efficient in-memory lookups for editions, properties, and suggestions
+3. **Automatic Property Creation**: Creates properties from definitions as needed
+4. **Validation**: Automatically validates values based on property types
+5. **Deduplication**: Avoids creating duplicate suggestions
+6. **Builder Helpers**: Provides convenient builder classes for creating properties and sources
+7. **Timestamp Management**: Automatically updates the last ingestion timestamp
+
+For a complete example, see `example_with_source_manager.py`.
+
+### Choosing the Right Approach
+
+- **Basic API Client**: For simple integrations or when you need complete control over the process
+- **SourceManager**: For more complex integrations where efficiency and convenience are priorities
+
+Both approaches use the same underlying API endpoints and data models, so you can choose the one that best fits your needs or even mix them as required.

metadata_curation_client-0.1.0/metadata_curation_client/__init__.py

@@ -0,0 +1,11 @@
+"""
+Metadata Curation Client
+
+A lightweight API client for external partners to integrate with metadata curation platforms.
+"""
+
+from .curation_api_client import CurationAPIClient, PropertyType
+from .source_manager import SourceManager, PropertyBuilder
+
+__version__ = "0.1.0"
+__all__ = ["CurationAPIClient", "PropertyType", "SourceManager", "PropertyBuilder"]

metadata_curation_client-0.1.0/metadata_curation_client/curation_api_client.py

@@ -0,0 +1,182 @@
+"""
+Metadata Curation Client - API Client
+
+Lightweight API client for external partners to integrate with metadata curation platforms.
+Based on the actual models and AbstractExtractor patterns.
+"""
+
+import requests
+from typing import Dict, List, Optional, Any
+from datetime import datetime
+
+
+class CurationAPIClient:
+    """
+    API client for external data integration.
+    Mirrors the internal ExtractionAPIClient for consistency.
+    """
+    
+    def __init__(self, base_url: str, api_key: Optional[str] = None):
+        self.base_url = base_url.rstrip('/')
+        self.session = requests.Session()
+        self.session.headers.update({'Content-Type': 'application/json'})
+        
+        if api_key:
+            self.session.headers.update({'Authorization': f'Bearer {api_key}'})
+    
+    def _handle_response(self, response: requests.Response) -> Dict:
+        """Handle API response and raise appropriate exceptions."""
+        try:
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            print(f"API Error {response.status_code}: {response.text}")
+            raise e
+        except requests.exceptions.RequestException as e:
+            print(f"Request Error: {e}")
+            raise e
+    
+    # Source endpoints
+    def create_source(self, source_data: Dict) -> Dict:
+        """Create a new source."""
+        response = self.session.post(f"{self.base_url}/sources/", json=source_data)
+        return self._handle_response(response)
+    
+    def get_source(self, source_id: int) -> Dict:
+        """Get source by ID."""
+        response = self.session.get(f"{self.base_url}/sources/{source_id}")
+        return self._handle_response(response)
+    
+    def get_sources(self) -> List[Dict]:
+        """Get all sources."""
+        response = self.session.get(f"{self.base_url}/sources/")
+        return self._handle_response(response)
+    
+    def get_source_by_technical_name(self, technical_name: str) -> Optional[Dict]:
+        """Get source by technical name."""
+        sources = self.get_sources()
+        return next((s for s in sources if s.get('technical_name') == technical_name), None)
+    
+    def get_source_editions(self, source_id: int, include_relationships: bool = False) -> List[Dict]:
+        """Get all editions for a source."""
+        params = {"include_relationships": include_relationships} if include_relationships else {}
+        response = self.session.get(f"{self.base_url}/sources/{source_id}/editions", params=params)
+        return self._handle_response(response)
+    
+    def get_source_properties(self, source_id: int, include_relationships: bool = False) -> List[Dict]:
+        """Get all properties for a source."""
+        params = {"include_relationships": include_relationships} if include_relationships else {}
+        response = self.session.get(f"{self.base_url}/sources/{source_id}/properties", params=params)
+        return self._handle_response(response)
+    
+    def get_source_suggestions(self, source_id: int, include_relationships: bool = False) -> List[Dict]:
+        """Get all suggestions for a source."""
+        params = {"include_relationships": include_relationships} if include_relationships else {}
+        response = self.session.get(f"{self.base_url}/sources/{source_id}/suggestions", params=params)
+        return self._handle_response(response)
+    
+    def update_source(self, source_id: int, source_data: Dict) -> Dict:
+        """Update an existing source."""
+        response = self.session.put(f"{self.base_url}/sources/{source_id}", json=source_data)
+        return self._handle_response(response)
+    
+    def mark_ingestion_complete(self, source_id: int) -> Dict:
+        """Mark ingestion complete by updating last_ingestion_at timestamp."""
+        return self.update_source(source_id, {
+            "last_ingestion_at": datetime.now().isoformat()
+        })
+    
+    # Edition endpoints
+    def create_edition(self, edition_data: Dict) -> Dict:
+        """
+        Create a new edition.
+        
+        Required fields:
+        - source_id: ID of the source this edition belongs to
+        - source_internal_id: Internal ID/identifier for this edition
+        
+        Optional fields:
+        - mapped_from_ids: List of edition IDs this edition is mapped from
+        """
+        response = self.session.post(f"{self.base_url}/editions/", json=edition_data)
+        return self._handle_response(response)
+    
+    def get_editions(self) -> List[Dict]:
+        """Get all editions."""
+        response = self.session.get(f"{self.base_url}/editions/")
+        return self._handle_response(response)
+    
+    def get_edition(self, edition_id: int) -> Dict:
+        """Get edition by ID."""
+        response = self.session.get(f"{self.base_url}/editions/{edition_id}")
+        return self._handle_response(response)
+    
+    # Property endpoints  
+    def create_property(self, property_data: Dict) -> Dict:
+        """Create a new property."""
+        response = self.session.post(f"{self.base_url}/properties/", json=property_data)
+        return self._handle_response(response)
+    
+    def get_properties(self) -> List[Dict]:
+        """Get all properties."""
+        response = self.session.get(f"{self.base_url}/properties/")
+        return self._handle_response(response)
+    
+    def get_property(self, property_id: int) -> Dict:
+        """Get property by ID."""
+        response = self.session.get(f"{self.base_url}/properties/{property_id}")
+        return self._handle_response(response)
+    
+    # Suggestion endpoints
+    def create_suggestion(self, suggestion_data: Dict) -> Dict:
+        """
+        Create a new suggestion.
+        
+        Required fields:
+        - source_id: ID of the source
+        - edition_id: ID of the edition
+        - property_id: ID of the property
+        
+        For controlled_vocabulary properties:
+        - property_option_id: ID of the property option
+        
+        For free_text, numerical, or other properties:
+        - custom_value: String value for the property
+        
+        Note: Either property_option_id OR custom_value must be provided,
+        depending on the property type.
+        """
+        response = self.session.post(f"{self.base_url}/suggestions/", json=suggestion_data)
+        return self._handle_response(response)
+    
+    def get_suggestions(self) -> List[Dict]:
+        """Get all suggestions."""
+        response = self.session.get(f"{self.base_url}/suggestions/")
+        return self._handle_response(response)
+
+
+# Property type constants (matching models.py)
+class PropertyType:
+    """
+    Property type constants for creating properties.
+    
+    CONTROLLED_VOCABULARY: Property with predefined options
+        - Requires property_options list when creating
+        - Suggestions require property_option_id
+    
+    FREE_TEXT: Property with open text values
+        - No property_options needed
+        - Suggestions require custom_value (string)
+    
+    BINARY: Boolean/yes-no property
+        - Automatically creates "1" and "0" options
+        - Suggestions require property_option_id (use option with name "1" for true)
+    
+    NUMERICAL: Numeric property
+        - No property_options needed
+        - Suggestions require custom_value (numeric value as string)
+    """
+    CONTROLLED_VOCABULARY = "controlled_vocabulary"
+    FREE_TEXT = "free_text"
+    BINARY = "binary"
+    NUMERICAL = "numerical"