Ac APIegyankosh.ac.in ↗

"""
eGyanKosh API Client - Educational Materials Navigator
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, Dict, Any, List


class ParseClient:
    """Client for interacting with the eGyanKosh API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.
        
        Args:
            api_key: API key for authentication. If None, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "75eaec3c-43b1-4dff-9f15-4ad0419f35a0"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key not provided and PARSE_API_KEY env var not set")

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make a request to the Parse API.
        
        Args:
            endpoint: The endpoint name (e.g., 'get_communities')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters
            
        Returns:
            Response JSON as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")
        
        response.raise_for_status()
        return response.json()

    def get_communities(self) -> Dict[str, Any]:
        """
        List all top-level communities in the repository.
        
        Returns:
            Dictionary containing list of communities with name and handle
        """
        return self._call("get_communities", method="GET")

    def get_community(self, handle: str) -> Dict[str, Any]:
        """
        Get details, sub-communities, and collections for a specific community.
        
        Args:
            handle: The handle ID of the community (e.g., '123456789/1')
            
        Returns:
            Dictionary with community details, sub-communities, and collections
        """
        return self._call("get_community", method="GET", handle=handle)

    def get_block_units(self, handle: str, page: int = 0) -> Dict[str, Any]:
        """
        List all units (items) within a collection.
        
        Args:
            handle: The handle ID of the collection
            page: Page number for pagination (default: 0)
            
        Returns:
            Dictionary with paginated items and metadata
        """
        return self._call("get_block_units", method="GET", handle=handle, page=page)

    def get_unit_detail(self, handle: str) -> Dict[str, Any]:
        """
        Get full metadata and direct PDF URLs for a specific unit.
        
        Args:
            handle: The handle ID of the unit/item
            
        Returns:
            Dictionary with unit title, metadata, and file URLs
        """
        return self._call("get_unit_detail", method="GET", handle=handle)

    def search(self, query: str, scope: str = "", page: int = 0) -> Dict[str, Any]:
        """
        Search for items across the repository.
        
        Args:
            query: Search keyword
            scope: Optional handle to limit search scope
            page: Page number for pagination (default: 0)
            
        Returns:
            Dictionary with search results and pagination info
        """
        return self._call(
            "search",
            method="GET",
            query=query,
            scope=scope,
            page=page
        )


def main():
    """Main workflow demonstrating practical usage of the eGyanKosh API."""
    
    # Initialize client
    client = ParseClient()
    
    print("=" * 80)
    print("eGyanKosh Educational Materials Navigator")
    print("=" * 80)
    
    # Step 1: Search for materials on a specific topic
    print("\n[STEP 1] Searching for 'philosophy' course materials...")
    search_results = client.search(query="philosophy", page=0)
    results = search_results.get("data", {}).get("results", [])
    
    if not results:
        print("  ✗ No results found. Trying alternative search...")
        search_results = client.search(query="course", page=0)
        results = search_results.get("data", {}).get("results", [])
    
    print(f"  ✓ Found {len(results)} results")
    
    # Display search results
    print("\n  Top 3 Search Results:")
    for i, result in enumerate(results[:3], 1):
        print(f"    {i}. {result.get('title', 'N/A')}")
        print(f"       Handle: {result.get('handle', 'N/A')} | Date: {result.get('date', 'N/A')}")
        print(f"       Contributor: {result.get('contributor', 'N/A')}")
    
    # Step 2: Get detailed information for the first search result
    if results:
        first_handle = results[0].get("handle")
        print(f"\n[STEP 2] Fetching detailed information for first result...")
        print(f"         Handle: {first_handle}")
        
        unit_detail = client.get_unit_detail(handle=first_handle)
        unit_data = unit_detail.get("data", {})
        
        print(f"\n  Title: {unit_data.get('title', 'N/A')}")
        print(f"  URI: {unit_data.get('metadata', {}).get('uri', 'N/A')}")
        
        metadata = unit_data.get("metadata", {})
        print("\n  Metadata:")
        for key, value in metadata.items():
            if value and key != "uri":
                print(f"    • {key}: {value}")
        
        # Show available files
        files = unit_data.get("files", [])
        if files:
            print(f"\n  Available Files ({len(files)}):")
            for file_info in files:
                filename = file_info.get("filename", "N/A")
                size = file_info.get("size", "N/A")
                print(f"    • {filename} {f'({size})' if size else ''}")
    
    # Step 3: Browse the hierarchy - get top-level communities
    print(f"\n[STEP 3] Browsing top-level communities...")
    communities_response = client.get_communities()
    communities = communities_response.get("data", {}).get("communities", [])
    
    print(f"  ✓ Found {len(communities)} top-level communities")
    print("\n  Communities:")
    for i, community in enumerate(communities[:5], 1):
        print(f"    {i}. {community.get('name', 'N/A')}")
    
    # Step 4: Explore the first community's structure
    if communities:
        first_community = communities[0]
        comm_handle = first_community.get("handle")
        
        print(f"\n[STEP 4] Exploring structure of '{first_community.get('name')}'...")
        community_detail = client.get_community(handle=comm_handle)
        community_data = community_detail.get("data", {})
        
        # Show sub-communities
        sub_communities = community_data.get("sub_communities", [])
        if sub_communities:
            print(f"\n  Sub-Communities ({len(sub_communities)}):")
            for sub in sub_communities[:5]:
                print(f"    • {sub.get('name', 'N/A')}")
        
        # Show collections
        collections = community_data.get("collections", [])
        if collections:
            print(f"\n  Collections ({len(collections)}):")
            for col in collections[:5]:
                print(f"    • {col.get('name', 'N/A')}")
            
            # Step 5: List units from first collection
            first_collection = collections[0]
            col_handle = first_collection.get("handle")
            
            print(f"\n[STEP 5] Listing units in '{first_collection.get('name')}'...")
            units_response = client.get_block_units(handle=col_handle, page=0)
            units_data = units_response.get("data", {})
            units = units_data.get("items", [])
            page = units_data.get("page", 0)
            
            print(f"  ✓ Found {len(units)} units (page {page})")
            
            if units:
                print("\n  Sample Units:")
                for i, unit in enumerate(units[:5], 1):
                    print(f"    {i}. {unit.get('title', 'N/A')}")
                    print(f"       Date: {unit.get('date', 'N/A')} | Handle: {unit.get('handle', 'N/A')}")
                
                # Step 6: Get details for first unit in collection
                first_unit = units[0]
                unit_handle = first_unit.get("handle")
                
                print(f"\n[STEP 6] Getting full details for first collection unit...")
                full_unit = client.get_unit_detail(handle=unit_handle)
                full_unit_data = full_unit.get("data", {})
                
                print(f"  Title: {full_unit_data.get('title', 'N/A')}")
                files = full_unit_data.get("files", [])
                if files:
                    print(f"  Files available: {len(files)}")
                    for file_info in files[:3]:
                        print(f"    • {file_info.get('filename', 'N/A')}")
    
    print("\n" + "=" * 80)
    print("Navigation complete!")
    print("=" * 80)


if __name__ == "__main__":
    main()