metadata-curation-client 0.1.0__py3-none-any.whl

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/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"

metadata_curation_client/source_manager.py

@@ -0,0 +1,455 @@
+"""
+Metadata Curation Client - Source Manager
+
+Enhanced abstractions for the metadata curation API client, inspired by the internal AbstractExtractor.
+
+This provides higher-level functionality for external integrators who prefer a more
+streamlined approach with features like:
+- Pre-fetching data to reduce API calls
+- Lookup tables for efficient access
+- Automatic property creation and validation
+- Streamlined suggestion creation
+"""
+
+from typing import Dict, List, Any, Optional, Union
+from datetime import datetime
+from .curation_api_client import CurationAPIClient, PropertyType
+
+
+class SourceManager:
+    """
+    High-level manager for source data integration.
+    
+    Provides similar convenience features to the internal AbstractExtractor:
+    - Prefetches data to reduce API calls
+    - Maintains lookup tables for editions, properties, and suggestions
+    - Automatically creates properties from definitions
+    - Handles validation for different property types
+    - Deduplicates suggestions
+    
+    This is optional - partners can still use the direct CurationAPIClient
+    for simpler integrations if preferred.
+    """
+    
+    def __init__(self, client: CurationAPIClient, source_identifier: Union[int, str], property_definitions: Optional[List[Dict]] = None):
+        """
+        Initialize the source manager with all needed data.
+        
+        Args:
+            client: API client for backend communication
+            source_identifier: Source ID (int) or technical_name (str)
+            property_definitions: Optional list of property definitions to ensure exist
+        """
+        self.client = client
+        self.property_definitions = property_definitions or []
+        
+        # Step 1: Get source information
+        self.source = self._get_source(source_identifier)
+        self.source_id = self.source['id']
+        
+        print(f"🎯 Working with source: {self.source['name']} (ID: {self.source_id})")
+        
+        # Step 2: Fetch all current data via API
+        self._fetch_all_data()
+        
+        # Step 3: Build lookup dictionaries
+        self._build_lookups()
+        
+        # Step 4: Ensure properties exist (if definitions provided)
+        if property_definitions:
+            self._ensure_properties_exist()
+    
+    def _get_source(self, source_identifier: Union[int, str]) -> Dict:
+        """Get source by ID or technical name."""
+        if isinstance(source_identifier, int) or (isinstance(source_identifier, str) and source_identifier.isdigit()):
+            source_id = int(source_identifier)
+            return self.client.get_source(source_id)
+        else:
+            # Get all sources and filter by technical_name
+            response = self.client.get_sources()
+            source = next((s for s in response if s.get('technical_name') == source_identifier), None)
+            if not source:
+                raise ValueError(f"Source '{source_identifier}' not found")
+            return source
+    
+    def _fetch_all_data(self):
+        """Fetch all information via API to reduce individual calls later."""
+        print("📡 Fetching all data from API...")
+        
+        # Get all source-related data
+        self.editions = self.client.get_source_editions(self.source_id)
+        self.properties = self.client.get_source_properties(self.source_id)
+        self.suggestions = self.client.get_source_suggestions(self.source_id)
+        
+        print(f"   📚 {len(self.editions)} editions")
+        print(f"   🏷️  {len(self.properties)} properties")  
+        print(f"   💡 {len(self.suggestions)} suggestions")
+    
+    def _build_lookups(self):
+        """Build lookup dictionaries for efficient access."""
+        print("🔍 Building lookup dictionaries...")
+        
+        # Editions by internal ID
+        self.editions_by_internal_id = {
+            edition['source_internal_id']: edition 
+            for edition in self.editions
+        }
+        
+        # Properties by technical name
+        self.properties_by_tech_name = {
+            prop['technical_name']: prop 
+            for prop in self.properties
+        }
+        
+        # Suggestions by edition and property
+        self.suggestions_lookup = {}
+        for suggestion in self.suggestions:
+            key = (suggestion['edition_id'], suggestion['property_id'])
+            if key not in self.suggestions_lookup:
+                self.suggestions_lookup[key] = []
+            self.suggestions_lookup[key].append(suggestion)
+    
+    def _ensure_properties_exist(self):
+        """Create properties if they don't exist yet."""
+        print("🏷️  Ensuring properties exist...")
+        
+        created_count = 0
+        for prop_def in self.property_definitions:
+            tech_name = prop_def['technical_name']
+            
+            if tech_name not in self.properties_by_tech_name:
+                # Create the property
+                property_data = {
+                    'technical_name': tech_name,
+                    'name': prop_def['name'],
+                    'type': prop_def['type'],
+                    'source_id': self.source_id,
+                    'property_options': []
+                }
+                
+                # Add options for controlled vocabulary and binary
+                if prop_def['type'] == PropertyType.CONTROLLED_VOCABULARY and 'options' in prop_def:
+                    property_data['property_options'] = [
+                        {'name': option} for option in prop_def['options']
+                    ]
+                elif prop_def['type'] == PropertyType.BINARY:
+                    property_data['property_options'] = [
+                        {'name': '0'}, {'name': '1'}
+                    ]
+                
+                # Create via API
+                created_property = self.client.create_property(property_data)
+                self.properties_by_tech_name[tech_name] = created_property
+                self.properties.append(created_property)
+                created_count += 1
+                
+                print(f"   ➕ Created: {prop_def['name']} ({prop_def['type']})")
+        
+        if created_count == 0:
+            print(f"   ✅ All {len(self.property_definitions)} properties already exist")
+        else:
+            print(f"   ✅ Created {created_count} new properties")
+    
+    def get_or_create_edition(self, internal_id: str) -> Dict:
+        """Get existing edition or create new one."""
+        if internal_id in self.editions_by_internal_id:
+            return self.editions_by_internal_id[internal_id]
+        
+        # Create new edition
+        edition_data = {
+            'source_id': self.source_id,
+            'source_internal_id': internal_id,
+            'mapped_from_ids': []
+        }
+        
+        edition = self.client.create_edition(edition_data)
+        self.editions_by_internal_id[internal_id] = edition
+        self.editions.append(edition)
+        
+        print(f"   ➕ Created edition: {internal_id}")
+        return edition
+    
+    def create_suggestion(self, edition_id: int, property_name: str, value: Any) -> Optional[Dict]:
+        """
+        Create a single property suggestion with validation and deduplication.
+        
+        Args:
+            edition_id: ID of the edition
+            property_name: Technical name of the property
+            value: Value to suggest (will be validated based on property type)
+        
+        Returns:
+            Created suggestion or None if invalid/skipped
+        """
+        # Skip empty or None values
+        if value is None or value == "":
+            return None
+        
+        # Find the property object
+        property_obj = self.properties_by_tech_name.get(property_name)
+        if not property_obj:
+            print(f"   ⚠️  Property '{property_name}' not found")
+            return None
+        
+        property_id = property_obj['id']
+        property_type = property_obj['type']
+        suggestion_key = (edition_id, property_id)
+        
+        # Check if suggestion with same value already exists
+        if self._suggestion_exists(suggestion_key, value, property_obj):
+            print(f"   ⏭️  Skipping duplicate suggestion: {property_name} = '{value}'")
+            return None
+        
+        # Prepare suggestion data based on property type
+        suggestion_data = {
+            'edition_id': edition_id,
+            'property_id': property_id,
+            'source_id': self.source_id,
+        }
+        
+        if property_type in [PropertyType.CONTROLLED_VOCABULARY, PropertyType.BINARY]:
+            # Find matching option
+            property_options = property_obj.get('property_options', [])
+            str_value = str(value).strip()
+            
+            if property_type == PropertyType.BINARY:
+                # Normalize binary values (1/0, true/false, yes/no)
+                if str_value.lower() in ['1', 'true', 'yes', 'y']:
+                    option_name = '1'
+                elif str_value.lower() in ['0', 'false', 'no', 'n']:
+                    option_name = '0'
+                else:
+                    print(f"   ⚠️  Invalid binary value: '{value}'")
+                    return None
+            else:
+                option_name = str_value
+            
+            # Find matching option
+            matching_option = next(
+                (opt for opt in property_options if opt['name'].lower() == option_name.lower()),
+                None
+            )
+            
+            if not matching_option:
+                print(f"   ⚠️  No matching option for '{str_value}'")
+                return None
+            
+            suggestion_data['property_option_id'] = matching_option['id']
+            
+        elif property_type in [PropertyType.FREE_TEXT, PropertyType.NUMERICAL]:
+            # For numerical values, validate it's a number
+            if property_type == PropertyType.NUMERICAL:
+                try:
+                    float(str(value))  # Check if it's a valid number
+                except ValueError:
+                    print(f"   ⚠️  Invalid numerical value: '{value}'")
+                    return None
+            
+            # Use custom value for free text and numerical properties
+            suggestion_data['custom_value'] = str(value)
+            
+        else:
+            print(f"   ⚠️  Unknown property type: {property_type}")
+            return None
+        
+        # Create the suggestion
+        try:
+            suggestion = self.client.create_suggestion(suggestion_data)
+            
+            # Add to our lookup for future reference
+            if suggestion_key not in self.suggestions_lookup:
+                self.suggestions_lookup[suggestion_key] = []
+            self.suggestions_lookup[suggestion_key].append(suggestion)
+            self.suggestions.append(suggestion)
+            
+            print(f"   💡 Created suggestion: {property_name} = '{value}'")
+            return suggestion
+            
+        except Exception as e:
+            print(f"   ⚠️  Failed to create suggestion: {e}")
+            return None
+    
+    def _suggestion_exists(self, suggestion_key: tuple, new_value: Any, property_obj: Dict) -> bool:
+        """Check if a suggestion with the same value already exists."""
+        existing_suggestions = self.suggestions_lookup.get(suggestion_key, [])
+        if not existing_suggestions:
+            return False
+        
+        property_type = property_obj.get('type')
+        str_value = str(new_value).strip()
+        
+        for suggestion in existing_suggestions:
+            if property_type in [PropertyType.CONTROLLED_VOCABULARY, PropertyType.BINARY]:
+                # Get the option that matches new_value
+                if property_type == PropertyType.BINARY:
+                    # Normalize binary values
+                    if str_value.lower() in ['1', 'true', 'yes', 'y']:
+                        normalized_value = '1'
+                    elif str_value.lower() in ['0', 'false', 'no', 'n']:
+                        normalized_value = '0'
+                    else:
+                        continue  # Invalid binary value
+                else:
+                    normalized_value = str_value
+                
+                # Check if option ID matches
+                property_options = property_obj.get('property_options', [])
+                for option in property_options:
+                    if option['name'].lower() == normalized_value.lower():
+                        if suggestion.get('property_option_id') == option['id']:
+                            return True
+            
+            elif property_type in [PropertyType.FREE_TEXT, PropertyType.NUMERICAL]:
+                # For free text and numerical, compare custom_value
+                if suggestion.get('custom_value', '').strip() == str_value:
+                    return True
+        
+        return False
+    
+    def create_suggestions_batch(self, edition_id: int, data: Dict[str, Any]) -> Dict:
+        """
+        Create multiple suggestions in a batch.
+        
+        Args:
+            edition_id: ID of the edition
+            data: Dictionary mapping property technical names to values
+        
+        Returns:
+            Dictionary with counts of created and skipped suggestions
+        """
+        created_count = 0
+        skipped_count = 0
+        
+        for property_name, value in data.items():
+            # Handle both single values and lists of values
+            values_to_process = value if isinstance(value, list) else [value]
+            
+            for individual_value in values_to_process:
+                # Skip empty or None list items
+                if individual_value is None or individual_value == "":
+                    continue
+                
+                suggestion = self.create_suggestion(edition_id, property_name, individual_value)
+                if suggestion:
+                    created_count += 1
+                else:
+                    skipped_count += 1
+        
+        if created_count > 0 or skipped_count > 0:
+            print(f"   ✅ Suggestions: {created_count} created, {skipped_count} skipped")
+        
+        return {
+            'created': created_count,
+            'skipped': skipped_count
+        }
+    
+    def finish_ingestion(self):
+        """Mark ingestion complete by updating the timestamp."""
+        try:
+            update_data = {
+                'last_ingestion_at': datetime.now().isoformat()
+            }
+            updated_source = self.client.update_source(self.source_id, update_data)
+            print(f"📅 Updated last ingestion timestamp for: {self.source['name']}")
+            return updated_source
+        except Exception as e:
+            print(f"⚠️  Failed to update last ingestion timestamp: {e}")
+            return None
+
+
+class PropertyBuilder:
+    """Helper class to build property definitions with proper validation."""
+    
+    @staticmethod
+    def free_text(technical_name: str, display_name: str, description: str = "") -> Dict:
+        """Create a free text property definition."""
+        return {
+            'technical_name': technical_name,
+            'name': display_name,
+            'description': description,
+            'type': PropertyType.FREE_TEXT
+        }
+    
+    @staticmethod
+    def controlled_vocabulary(technical_name: str, display_name: str, options: List[str], description: str = "") -> Dict:
+        """Create a controlled vocabulary property definition."""
+        return {
+            'technical_name': technical_name,
+            'name': display_name,
+            'description': description,
+            'type': PropertyType.CONTROLLED_VOCABULARY,
+            'options': options
+        }
+    
+    @staticmethod
+    def binary(technical_name: str, display_name: str, description: str = "") -> Dict:
+        """Create a binary property definition."""
+        return {
+            'technical_name': technical_name,
+            'name': display_name,
+            'description': description,
+            'type': PropertyType.BINARY
+        }
+    
+    @staticmethod
+    def numerical(technical_name: str, display_name: str, description: str = "") -> Dict:
+        """Create a numerical property definition."""
+        return {
+            'technical_name': technical_name,
+            'name': display_name,
+            'description': description,
+            'type': PropertyType.NUMERICAL
+        }
+
+
+class SourceBuilder:
+    """Helper class to create a new source."""
+    
+    @staticmethod
+    def create(client: CurationAPIClient, name: str, description: str, technical_name: str = None) -> Dict:
+        """
+        Create a new source with the given parameters.
+        
+        Args:
+            client: The API client to use
+            name: Display name for the source
+            description: Description of the source
+            technical_name: Optional technical name (slug)
+            
+        Returns:
+            The created source
+        """
+        source_data = {
+            'name': name,
+            'description': description
+        }
+        
+        if technical_name:
+            source_data['technical_name'] = technical_name
+            
+        return client.create_source(source_data)
+
+
+class EditionBuilder:
+    """Helper class to create editions."""
+    
+    @staticmethod
+    def create(client: CurationAPIClient, source_id: int, internal_id: str) -> Dict:
+        """
+        Create a new edition for a source.
+        
+        Args:
+            client: The API client to use
+            source_id: ID of the source
+            internal_id: Internal ID/identifier for this edition
+            
+        Returns:
+            The created edition
+        """
+        edition_data = {
+            'source_id': source_id,
+            'source_internal_id': internal_id,
+            'mapped_from_ids': []
+        }
+        
+        return client.create_edition(edition_data)

metadata_curation_client-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+metadata_curation_client/__init__.py,sha256=VWJY3OsCDQEZ5BbePugl4J8E2etciuHyTuDvTccaqog,360
+metadata_curation_client/curation_api_client.py,sha256=WMfIIKO01b4EZ0wCyO9Opn_FrcZSKJLquHEMsVWQWu0,7459
+metadata_curation_client/source_manager.py,sha256=hkrEU1JT4Hkwy2fUbheb7pP_1KfTXbcU8sjiLYc0i8Q,17940
+metadata_curation_client-0.1.0.dist-info/licenses/LICENSE,sha256=dvKFLHmy95RWWhFDqmOn38Yjfv_w-Hxc5EmQgQ9iCC8,1086
+metadata_curation_client-0.1.0.dist-info/METADATA,sha256=YzREY-ik0GaW44OLOTAnZ0dJvLJXxiAtFzgTflyup10,7890
+metadata_curation_client-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+metadata_curation_client-0.1.0.dist-info/top_level.txt,sha256=FUkmJY-66mVLu-RvgCXwPn26F6Jkxmve9Stw8kCsr0w,25
+metadata_curation_client-0.1.0.dist-info/RECORD,,

metadata_curation_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

metadata_curation_client-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+metadata_curation_client