hockey-blast-common-lib 0.1.62__py3-none-any.whl → 0.1.64__py3-none-any.whl

hockey_blast_common_lib/assign_skater_skill.py

@@ -1,45 +1,50 @@
-import sys, os
+import os
+import sys
 
 # Add the package directory to the Python path
 sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
-from hockey_blast_common_lib.models import Human, Level
-from hockey_blast_common_lib.stats_models import LevelStatsSkater
 from hockey_blast_common_lib.db_connection import create_session
+from hockey_blast_common_lib.models import Human, Level
 from hockey_blast_common_lib.progress_utils import create_progress_tracker
+from hockey_blast_common_lib.stats_models import LevelStatsSkater
+
 
 def calculate_skater_skill_value(session, level_stats):
-    min_skill_value = float('inf')  # Start with infinity since we want the minimum
+    min_skill_value = float("inf")  # Start with infinity since we want the minimum
 
     for stat in level_stats:
         level = session.query(Level).filter(Level.id == stat.level_id).first()
         if not level or level.skill_value < 0:
             continue
         level_skill_value = level.skill_value
-        
+
         # Fix critical bug: Invert rank ratios so better players (lower ranks) get higher skill values
         # Rank 1 (best) should get factor close to 1.0, worst rank should get factor close to 0.0
         if stat.total_in_rank > 1:
-            ppg_skill_factor = 1 - (stat.points_per_game_rank - 1) / (stat.total_in_rank - 1)
+            ppg_skill_factor = 1 - (stat.points_per_game_rank - 1) / (
+                stat.total_in_rank - 1
+            )
         else:
             ppg_skill_factor = 1.0  # Only one player in level
-        
+
         # Apply skill adjustment: range from 0.8 to 1.2 of level base skill
         # Since lower skill_value is better: Best player gets 0.8x (closer to better levels), worst gets 1.2x
         skill_adjustment = 1.3 - 0.2 * ppg_skill_factor
         skill_value = level_skill_value * skill_adjustment
-        
+
         # Take the minimum skill value across all levels the player has played in (lower is better)
         min_skill_value = min(min_skill_value, skill_value)
 
-    return min_skill_value if min_skill_value != float('inf') else 0
+    return min_skill_value if min_skill_value != float("inf") else 0
+
 
 def assign_skater_skill_values():
     session = create_session("boss")
 
     humans = session.query(Human).all()
     total_humans = len(humans)
-    
+
     # Create progress tracker
     progress = create_progress_tracker(total_humans, "Assigning skater skill values")
 
@@ -47,7 +52,11 @@ def assign_skater_skill_values():
     updates_count = 0
 
     for i, human in enumerate(humans):
-        level_stats = session.query(LevelStatsSkater).filter(LevelStatsSkater.human_id == human.id).all()
+        level_stats = (
+            session.query(LevelStatsSkater)
+            .filter(LevelStatsSkater.human_id == human.id)
+            .all()
+        )
         if level_stats:
             skater_skill_value = calculate_skater_skill_value(session, level_stats)
             human.skater_skill_value = skater_skill_value
@@ -65,5 +74,6 @@ def assign_skater_skill_values():
 
     print("Skater skill values have been assigned to all humans.")
 
+
 if __name__ == "__main__":
     assign_skater_skill_values()

hockey_blast_common_lib/db_connection.py

@@ -1,7 +1,8 @@
 import os
+
+from dotenv import load_dotenv
 from sqlalchemy import create_engine
 from sqlalchemy.orm import sessionmaker
-from dotenv import load_dotenv
 
 # Load environment variables from .env file in the root directory of THE PROJECT (not this library)
 load_dotenv()
@@ -13,36 +14,86 @@ DB_PARAMS = {
         "user": os.getenv("DB_USER", "frontend_user"),
         "password": os.getenv("DB_PASSWORD", "hockey-blast"),
         "host": os.getenv("DB_HOST", "localhost"),
-        "port": int(os.getenv("DB_PORT", 5432))
+        "port": int(os.getenv("DB_PORT", 5432)),
     },
-
     "frontend-sample-db": {
         "dbname": os.getenv("DB_NAME_SAMPLE", "hockey_blast_sample"),
         "user": os.getenv("DB_USER", "frontend_user"),
         "password": os.getenv("DB_PASSWORD", "hockey-blast"),
         "host": os.getenv("DB_HOST", "localhost"),
-        "port": int(os.getenv("DB_PORT", 5432))
+        "port": int(os.getenv("DB_PORT", 5432)),
     },
-
-# The section below is to handle recovery of sample DB where boss user is present, to avoid warnings and errors
-# TODO: Maybe figure out a way to do backup without it and make frontend_user own the sample? 
+    # MCP server uses read-only frontend_user (same as frontend)
+    "mcp": {
+        "dbname": os.getenv("DB_NAME", "hockey_blast"),
+        "user": os.getenv("DB_USER", "frontend_user"),
+        "password": os.getenv("DB_PASSWORD", "hockey-blast"),
+        "host": os.getenv("DB_HOST", "localhost"),
+        "port": int(os.getenv("DB_PORT", 5432)),
+    },
+    # The section below is to handle recovery of sample DB where boss user is present, to avoid warnings and errors
+    # TODO: Maybe figure out a way to do backup without it and make frontend_user own the sample?
     "boss": {
         "dbname": os.getenv("DB_NAME", "hockey_blast"),
         "user": os.getenv("DB_USER_BOSS", "boss"),
         "password": os.getenv("DB_PASSWORD_BOSS", "boss"),
         "host": os.getenv("DB_HOST", "localhost"),
-        "port": int(os.getenv("DB_PORT", 5432))
+        "port": int(os.getenv("DB_PORT", 5432)),
     },
 }
 
+
 def get_db_params(config_name):
     if config_name not in DB_PARAMS:
         raise ValueError(f"Invalid organization: {config_name}")
     return DB_PARAMS[config_name]
 
+
 def create_session(config_name):
+    """
+    Create a database session using the specified configuration.
+
+    Args:
+        config_name: One of "frontend", "frontend-sample-db", "mcp", "boss"
+
+    Returns:
+        SQLAlchemy session object
+    """
     db_params = get_db_params(config_name)
     db_url = f"postgresql://{db_params['user']}:{db_params['password']}@{db_params['host']}:{db_params['port']}/{db_params['dbname']}"
     engine = create_engine(db_url)
     Session = sessionmaker(bind=engine)
     return Session()
+
+
+# Convenience functions for standardized session creation
+def create_session_frontend():
+    """
+    Create read-only session for frontend web application.
+    Uses frontend_user with limited permissions.
+    """
+    return create_session("frontend")
+
+
+def create_session_mcp():
+    """
+    Create read-only session for MCP server.
+    Uses frontend_user with limited permissions (same as frontend).
+    """
+    return create_session("mcp")
+
+
+def create_session_frontend_sampledb():
+    """
+    Create read-only session for frontend sample database.
+    Uses frontend_user with limited permissions.
+    """
+    return create_session("frontend-sample-db")
+
+
+def create_session_boss():
+    """
+    Create full-access session for pipeline operations.
+    WARNING: Has write permissions. Use only in pipeline scripts.
+    """
+    return create_session("boss")

hockey_blast_common_lib/embedding_utils.py

@@ -0,0 +1,309 @@
+"""
+Embedding utilities for vector search using AWS Bedrock Titan.
+
+This module provides functions to generate embeddings for text using AWS Bedrock's
+Titan embedding model and store them in the database for semantic search.
+"""
+
+import json
+import logging
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+# AWS Bedrock configuration
+BEDROCK_REGION = "us-west-2"
+BEDROCK_EMBEDDING_MODEL = "amazon.titan-embed-text-v2:0"
+EMBEDDING_DIMENSION = 1024  # Titan v2 produces 1024-dimensional embeddings
+
+
+def generate_embedding(text: str) -> Optional[List[float]]:
+    """
+    Generate embedding vector for text using AWS Bedrock Titan.
+
+    Args:
+        text: Text to embed (e.g., "Pavel Kletskov" or "Good Guys")
+
+    Returns:
+        List of floats representing the embedding vector (1024 dimensions)
+        None if embedding generation fails
+    """
+    if not text or not text.strip():
+        logger.warning("Empty text provided to generate_embedding")
+        return None
+
+    try:
+        import boto3
+
+        bedrock = boto3.client(
+            service_name="bedrock-runtime",
+            region_name=BEDROCK_REGION
+        )
+
+        # Titan embedding API request format
+        request_body = {
+            "inputText": text.strip()
+        }
+
+        response = bedrock.invoke_model(
+            modelId=BEDROCK_EMBEDDING_MODEL,
+            body=json.dumps(request_body)
+        )
+
+        response_body = json.loads(response["body"].read())
+        embedding = response_body.get("embedding")
+
+        if not embedding:
+            logger.error(f"No embedding returned for text: {text[:50]}")
+            return None
+
+        if len(embedding) != EMBEDDING_DIMENSION:
+            logger.error(
+                f"Unexpected embedding dimension: {len(embedding)} (expected {EMBEDDING_DIMENSION})"
+            )
+            return None
+
+        return embedding
+
+    except Exception as e:
+        logger.error(f"Failed to generate embedding for '{text[:50]}': {e}")
+        return None
+
+
+def update_human_embedding(session, human_id: int, full_name: str) -> bool:
+    """
+    Generate and store embedding for a human (player/referee/scorekeeper).
+
+    Args:
+        session: SQLAlchemy session
+        human_id: Human ID in database
+        full_name: Full name like "Pavel Kletskov"
+
+    Returns:
+        True if embedding was successfully stored, False otherwise
+    """
+    from datetime import datetime
+    from hockey_blast_common_lib.models import HumanEmbedding
+
+    if not full_name or not full_name.strip():
+        logger.warning(f"Empty full_name for human_id {human_id}")
+        return False
+
+    # Generate embedding
+    embedding = generate_embedding(full_name.strip())
+    if not embedding:
+        return False
+
+    try:
+        # Convert Python list to PostgreSQL array format for vector type
+        embedding_str = "[" + ",".join(str(x) for x in embedding) + "]"
+
+        # Check if embedding already exists using ORM
+        existing = session.query(HumanEmbedding).filter_by(human_id=human_id).first()
+
+        if existing:
+            # Update existing record
+            # Note: Need raw SQL for vector type casting with ::vector
+            # Using format() for embedding since it needs ::vector cast
+            from sqlalchemy import text
+            sql = text(f"""
+                UPDATE human_embeddings
+                SET full_name = :full_name,
+                    embedding = '{embedding_str}'::vector,
+                    updated_at = :updated_at
+                WHERE human_id = :human_id
+            """)
+            session.execute(
+                sql,
+                {
+                    "human_id": human_id,
+                    "full_name": full_name.strip(),
+                    "updated_at": datetime.utcnow()
+                }
+            )
+        else:
+            # Insert new record
+            # Note: Need raw SQL for vector type casting with ::vector
+            # Using format() for embedding since it needs ::vector cast
+            from sqlalchemy import text
+            sql = text(f"""
+                INSERT INTO human_embeddings (human_id, full_name, embedding, updated_at)
+                VALUES (:human_id, :full_name, '{embedding_str}'::vector, :updated_at)
+            """)
+            session.execute(
+                sql,
+                {
+                    "human_id": human_id,
+                    "full_name": full_name.strip(),
+                    "updated_at": datetime.utcnow()
+                }
+            )
+
+        logger.info(f"Updated embedding for human_id={human_id}, name='{full_name}'")
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to store embedding for human_id={human_id}: {e}")
+        return False
+
+
+def update_team_embedding(session, team_id: int, team_name: str) -> bool:
+    """
+    Generate and store embedding for a team.
+
+    Args:
+        session: SQLAlchemy session
+        team_id: Team ID in database
+        team_name: Team name like "Good Guys"
+
+    Returns:
+        True if embedding was successfully stored, False otherwise
+    """
+    from datetime import datetime
+    from hockey_blast_common_lib.models import TeamEmbedding
+
+    if not team_name or not team_name.strip():
+        logger.warning(f"Empty team_name for team_id {team_id}")
+        return False
+
+    # Generate embedding
+    embedding = generate_embedding(team_name.strip())
+    if not embedding:
+        return False
+
+    try:
+        # Convert Python list to PostgreSQL array format for vector type
+        embedding_str = "[" + ",".join(str(x) for x in embedding) + "]"
+
+        # Check if embedding already exists using ORM
+        existing = session.query(TeamEmbedding).filter_by(team_id=team_id).first()
+
+        if existing:
+            # Update existing record
+            # Note: Need raw SQL for vector type casting with ::vector
+            # Using format() for embedding since it needs ::vector cast
+            from sqlalchemy import text
+            sql = text(f"""
+                UPDATE team_embeddings
+                SET team_name = :team_name,
+                    embedding = '{embedding_str}'::vector,
+                    updated_at = :updated_at
+                WHERE team_id = :team_id
+            """)
+            session.execute(
+                sql,
+                {
+                    "team_id": team_id,
+                    "team_name": team_name.strip(),
+                    "updated_at": datetime.utcnow()
+                }
+            )
+        else:
+            # Insert new record
+            # Note: Need raw SQL for vector type casting with ::vector
+            # Using format() for embedding since it needs ::vector cast
+            from sqlalchemy import text
+            sql = text(f"""
+                INSERT INTO team_embeddings (team_id, team_name, embedding, updated_at)
+                VALUES (:team_id, :team_name, '{embedding_str}'::vector, :updated_at)
+            """)
+            session.execute(
+                sql,
+                {
+                    "team_id": team_id,
+                    "team_name": team_name.strip(),
+                    "updated_at": datetime.utcnow()
+                }
+            )
+
+        logger.info(f"Updated embedding for team_id={team_id}, name='{team_name}'")
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to store embedding for team_id={team_id}: {e}")
+        return False
+
+
+def search_embeddings_semantic(
+    session,
+    query: str,
+    entity_type: str = "all",
+    limit: int = 10
+) -> List[dict]:
+    """
+    Semantic search across human and team embeddings.
+
+    Args:
+        session: SQLAlchemy session
+        query: Search query (e.g., "good guy", "pavel")
+        entity_type: "human", "team", or "all"
+        limit: Maximum number of results
+
+    Returns:
+        List of dicts with keys: type, id, name, similarity
+    """
+    from sqlalchemy import text
+
+    # Generate query embedding
+    query_embedding = generate_embedding(query)
+    if not query_embedding:
+        logger.error(f"Failed to generate embedding for query: {query}")
+        return []
+
+    embedding_str = "[" + ",".join(str(x) for x in query_embedding) + "]"
+    results = []
+
+    try:
+        # Search humans
+        # Note: Using raw SQL for pgvector distance operator (<=>)
+        # Using format() for embedding since it needs ::vector cast
+        if entity_type in ("human", "all"):
+            sql = text(f"""
+                SELECT
+                    human_id,
+                    full_name,
+                    1 - (embedding <=> '{embedding_str}'::vector) as similarity
+                FROM human_embeddings
+                ORDER BY embedding <=> '{embedding_str}'::vector
+                LIMIT :limit
+            """)
+            human_results = session.execute(sql, {"limit": limit}).fetchall()
+
+            for row in human_results:
+                results.append({
+                    "type": "human",
+                    "id": row[0],
+                    "name": row[1],
+                    "similarity": float(row[2])
+                })
+
+        # Search teams
+        # Note: Using raw SQL for pgvector distance operator (<=>)
+        # Using format() for embedding since it needs ::vector cast
+        if entity_type in ("team", "all"):
+            sql = text(f"""
+                SELECT
+                    team_id,
+                    team_name,
+                    1 - (embedding <=> '{embedding_str}'::vector) as similarity
+                FROM team_embeddings
+                ORDER BY embedding <=> '{embedding_str}'::vector
+                LIMIT :limit
+            """)
+            team_results = session.execute(sql, {"limit": limit}).fetchall()
+
+            for row in team_results:
+                results.append({
+                    "type": "team",
+                    "id": row[0],
+                    "name": row[1],
+                    "similarity": float(row[2])
+                })
+
+        # Sort by similarity descending and limit
+        results.sort(key=lambda x: x["similarity"], reverse=True)
+        return results[:limit]
+
+    except Exception as e:
+        logger.error(f"Semantic search failed for query '{query}': {e}")
+        return []