sentimentizer 0.99.0__py3-none-any.whl

sentimentizer/__init__.py

@@ -0,0 +1,60 @@
+import logging
+import sys
+import time
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+from typing import Any, TextIO
+
+import psutil
+import structlog
+
+file_path = Path(__file__)
+root = file_path.parent.parent.absolute()
+
+
+def new_logger(level: int = 20, output: TextIO = sys.stderr) -> Any:
+    """Creates a configured structlog logger.
+
+    Returns Any because structlog's bound logger accepts arbitrary
+    keyword arguments for event key-value pairs, which static type
+    checkers cannot express.
+    """
+    structlog.configure(
+        cache_logger_on_first_use=True,
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.format_exc_info,
+            structlog.processors.TimeStamper(fmt="iso", utc=True),
+            structlog.processors.JSONRenderer(),
+        ],
+        logger_factory=structlog.PrintLoggerFactory(file=output),
+    )
+    return structlog.getLogger(__name__)
+
+
+logger: Any = new_logger(logging.INFO)
+
+
+def time_decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+    """logs time stats of function"""
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        ts = time.perf_counter()
+        result = func(*args, **kwargs)
+        te = time.perf_counter()
+        event = "function completed successfully"
+        logger.info(
+            event,
+            function=func.__name__,
+            run_time=f"{te - ts: 2.4f} seconds",
+            available_memory=f"{psutil.virtual_memory().available / 1024**3: .2f} GBs",
+            free_memory=f"{psutil.virtual_memory().free / 1024**3: .2f} GBs",
+            used_memory=f"{psutil.virtual_memory().used / 1024**3: .2f} GBs",
+        )
+        return result
+
+    return wrapper

sentimentizer/agent/__init__.py

@@ -0,0 +1,11 @@
+"""Sentimentizer hyperparameter tuning agent.
+
+Uses Pydantic AI Slim (GLM 5.1 via Ollama) for LLM reasoning,
+LangGraph for workflow orchestration, and Ray Tune + Optuna for
+hyperparameter search.
+"""
+
+from sentimentizer.agent.graph import run_agent_tuning
+from sentimentizer.agent.loader import AgentConfig, TunerConfig, load_agent_config
+
+__all__ = ["AgentConfig", "TunerConfig", "load_agent_config", "run_agent_tuning"]

sentimentizer/agent/agents.py

@@ -0,0 +1,143 @@
+"""Pydantic AI agent definitions for the tuning agent.
+
+Two agents work together:
+1. AnalysisAgent — examines training metrics and diagnoses issues
+2. StrategyAgent — decides the next tuning strategy and search space
+
+Both use GLM 5.1 via Ollama's OpenAI-compatible API.
+Pydantic AI validates the LLM's structured output, rejecting
+hallucinated or invalid configurations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.models.openai import OpenAIModel
+from pydantic_ai.providers.openai import OpenAIProvider
+
+from sentimentizer import new_logger
+from sentimentizer.agent.loader import AgentConfig
+from sentimentizer.agent.models import AnalysisResult, TuningDecision
+from sentimentizer.agent.prompts import ANALYSIS_SYSTEM_PROMPT, STRATEGY_SYSTEM_PROMPT
+from sentimentizer.config import DEFAULT_LOG_LEVEL
+
+logger = new_logger(DEFAULT_LOG_LEVEL)
+
+
+@dataclass
+class TuningDeps:
+    """Dependencies injected into both agents.
+
+    Provides the agents with access to tuning history, current
+    metrics, and the model type being tuned.
+    """
+
+    model_type: str = "rnn"
+    history: list[dict[str, Any]] | None = None
+    current_metrics: dict[str, Any] | None = None
+    search_space_defaults: dict[str, dict[str, Any]] | None = None
+
+
+def _create_model(config: AgentConfig) -> OpenAIModel:
+    """Create an OpenAI-compatible model pointed at Ollama.
+
+    Ollama exposes an OpenAI-compatible API at /v1, so we
+    use pydantic-ai-slim's OpenAIModel with OpenAIProvider
+    configured with Ollama's base_url.
+    """
+    provider = OpenAIProvider(
+        base_url=config.ollama_base_url,
+        api_key="ollama",  # Ollama doesn't require a real key
+    )
+    return OpenAIModel(
+        model_name=config.model_name,
+        provider=provider,
+    )
+
+
+def create_analysis_agent(config: AgentConfig) -> Agent[TuningDeps, AnalysisResult]:
+    """Create the analysis agent that examines training metrics.
+
+    This agent:
+    - Reads validation loss, accuracy, and training loss curves
+    - Detects overfitting (val_loss rising while train_loss falls)
+    - Detects underfitting (both losses remain high)
+    - Assesses whether learning rate is appropriate
+    - Suggests which parameters to focus on next
+
+    Returns a Pydantic-validated AnalysisResult.
+    """
+    model = _create_model(config)
+
+    agent = Agent(
+        model=model,
+        output_type=AnalysisResult,
+        deps_type=TuningDeps,
+        system_prompt=ANALYSIS_SYSTEM_PROMPT,
+        model_settings={"temperature": config.temperature, "max_tokens": config.max_tokens},
+    )
+
+    @agent.tool
+    def get_previous_results(ctx: RunContext[TuningDeps]) -> list[dict[str, Any]]:
+        """Get the history of past tuning iterations."""
+        return ctx.deps.history or []
+
+    @agent.tool
+    def get_current_metrics(ctx: RunContext[TuningDeps]) -> dict[str, Any]:
+        """Get the current iteration's training metrics."""
+        return ctx.deps.current_metrics or {}
+
+    @agent.tool
+    def get_model_type(ctx: RunContext[TuningDeps]) -> str:
+        """Get the model type being tuned (rnn, encoder, decoder)."""
+        return ctx.deps.model_type
+
+    return agent
+
+
+def create_strategy_agent(config: AgentConfig) -> Agent[TuningDeps, TuningDecision]:
+    """Create the strategy agent that decides the next tuning action.
+
+    This agent:
+    - Receives the analysis of training metrics
+    - Decides whether to widen, narrow, change focus, or stop
+    - Produces a new search space configuration
+    - Sets the number of trials for the next Ray Tune run
+
+    Returns a Pydantic-validated TuningDecision, ensuring
+    the search space and strategy are always valid.
+    """
+    model = _create_model(config)
+
+    agent = Agent(
+        model=model,
+        output_type=TuningDecision,
+        deps_type=TuningDeps,
+        system_prompt=STRATEGY_SYSTEM_PROMPT,
+        model_settings={"temperature": config.temperature, "max_tokens": config.max_tokens},
+    )
+
+    @agent.tool
+    def get_analysis(ctx: RunContext[TuningDeps]) -> dict[str, Any]:
+        """Get the current analysis results from the analysis agent."""
+        return ctx.deps.current_metrics or {}
+
+    @agent.tool
+    def get_previous_results(ctx: RunContext[TuningDeps]) -> list[dict[str, Any]]:
+        """Get the history of past tuning iterations."""
+        return ctx.deps.history or []
+
+    @agent.tool
+    def get_default_search_space(ctx: RunContext[TuningDeps]) -> dict[str, dict[str, Any]]:
+        """Get the default search space parameters from the YAML config."""
+        return ctx.deps.search_space_defaults or {}
+
+    @agent.tool
+    def get_model_type(ctx: RunContext[TuningDeps]) -> str:
+        """Get the model type being tuned (rnn, encoder, decoder)."""
+        return ctx.deps.model_type
+
+    return agent

sentimentizer/agent/config.yaml

@@ -0,0 +1,116 @@
+# Sentimentizer Agent Configuration
+# Controls the hyperparameter tuning agent powered by GLM 5.1 via Ollama
+
+agent:
+  # LLM configuration (Ollama OpenAI-compatible endpoint)
+  model_name: "glm-5.1:cloud"
+  ollama_base_url: "http://localhost:11434/v1"
+  temperature: 0.3
+  max_tokens: 2048
+
+  # Agent loop configuration
+  max_iterations: 5
+  convergence_threshold: 0.005  # Stop if improvement < this over last 3 iterations
+  initial_search_strategy: "bayesian"  # bayesian | grid | random
+
+  # LangGraph checkpointing (resume interrupted tuning sessions)
+  checkpointing:
+    enabled: true
+    db_path: "agent_checkpoints.db"
+
+  # Human-in-the-loop (pause before expensive training runs)
+  human_in_the_loop: false
+
+tuner:
+  # Ray Tune + Optuna scheduler configuration
+  scheduler: "asha"  # asha | hyperband | median
+  metric: "val_accuracy"
+  mode: "max"
+  num_samples: 20
+  grace_period: 2
+  reduction_factor: 3
+
+  # Search spaces per model type
+  # Each parameter supports: loguniform, uniform, choice, randint
+  search_spaces:
+    rnn:
+      lr:
+        type: "loguniform"
+        low: 1.0e-5
+        high: 1.0e-2
+      hidden_size:
+        type: "choice"
+        values: [128, 256, 512]
+      num_layers:
+        type: "randint"
+        low: 1
+        high: 4
+      dropout:
+        type: "uniform"
+        low: 0.1
+        high: 0.5
+      weight_decay:
+        type: "loguniform"
+        low: 1.0e-6
+        high: 1.0e-2
+      batch_size:
+        type: "choice"
+        values: [32, 64, 128]
+
+    encoder:
+      lr:
+        type: "loguniform"
+        low: 1.0e-5
+        high: 5.0e-3
+      d_model:
+        type: "choice"
+        values: [128, 256, 512]
+      n_heads:
+        type: "choice"
+        values: [2, 4, 8]
+      n_layers:
+        type: "randint"
+        low: 1
+        high: 6
+      dropout:
+        type: "uniform"
+        low: 0.1
+        high: 0.5
+      weight_decay:
+        type: "loguniform"
+        low: 1.0e-6
+        high: 1.0e-2
+      batch_size:
+        type: "choice"
+        values: [32, 64, 128]
+
+    decoder:
+      lr:
+        type: "loguniform"
+        low: 1.0e-5
+        high: 1.0e-2
+      d_model:
+        type: "choice"
+        values: [128, 256, 512]
+      n_heads:
+        type: "choice"
+        values: [2, 4, 8]
+      n_encoder_layers:
+        type: "randint"
+        low: 1
+        high: 4
+      n_decoder_layers:
+        type: "randint"
+        low: 2
+        high: 6
+      dropout:
+        type: "uniform"
+        low: 0.1
+        high: 0.5
+      weight_decay:
+        type: "loguniform"
+        low: 1.0e-6
+        high: 1.0e-2
+      batch_size:
+        type: "choice"
+        values: [32, 64, 128]

sentimentizer/agent/graph.py

@@ -0,0 +1,173 @@
+"""LangGraph state graph for the tuning agent.
+
+Defines the workflow: analyze → decide → tune → evaluate → (loop or end)
+
+Uses LangGraph for orchestration and checkpointing, with Pydantic AI
+agents (GLM 5.1 via Ollama) as the LLM reasoning layer inside nodes.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from langgraph.graph import END, StateGraph
+
+from sentimentizer import new_logger
+from sentimentizer.agent.loader import load_agent_config
+from sentimentizer.agent.models import AgentRunResult
+from sentimentizer.agent.nodes import analyze, decide, evaluate, tune
+from sentimentizer.agent.state import AgentState
+from sentimentizer.config import DEFAULT_LOG_LEVEL
+
+logger = new_logger(DEFAULT_LOG_LEVEL)
+
+
+def should_continue(state: AgentState) -> str:
+    """Conditional edge: decide whether to continue or end the loop.
+
+    Returns 'analyze' to continue iterating, or 'end' to stop.
+    """
+    if state.get("converged", False):
+        return "end"
+
+    # Safety check: if iteration exceeds a hard limit, stop
+    iteration = state.get("iteration", 0)
+    config_path = state.get("agent_config_path")
+    try:
+        agent_config, _ = load_agent_config(config_path)
+        hard_limit = agent_config.max_iterations * 2  # allow some extra
+    except Exception:
+        hard_limit = 20
+
+    if iteration >= hard_limit:
+        logger.info("hard_limit_reached", iteration=iteration, limit=hard_limit)
+        return "end"
+
+    return "analyze"
+
+
+def build_graph(
+    model_type: str = "rnn",
+    config_path: str | Path | None = None,
+) -> StateGraph:
+    """Build the LangGraph tuning agent graph.
+
+    The graph has four nodes in a loop:
+    1. analyze — Pydantic AI analysis agent examines metrics
+    2. decide — Pydantic AI strategy agent chooses next action
+    3. tune — Ray Tune + Optuna executes the search
+    4. evaluate — Check convergence, update best results
+
+    After evaluate, a conditional edge either loops back to
+    analyze or goes to END.
+
+    Args:
+        model_type: Model to tune ('rnn', 'encoder', 'decoder').
+        config_path: Path to agent config YAML.
+
+    Returns:
+        Compiled StateGraph ready to run.
+    """
+    graph = StateGraph(AgentState)
+
+    # Add nodes
+    graph.add_node("analyze", analyze)
+    graph.add_node("decide", decide)
+    graph.add_node("tune", tune)
+    graph.add_node("evaluate", evaluate)
+
+    # Define edges
+    graph.set_entry_point("analyze")
+    graph.add_edge("analyze", "decide")
+    graph.add_edge("decide", "tune")
+    graph.add_edge("tune", "evaluate")
+
+    # Conditional edge after evaluate: loop back or end
+    graph.add_conditional_edges(
+        "evaluate",
+        should_continue,
+        {"analyze": "analyze", "end": END},
+    )
+
+    return graph.compile()
+
+
+def create_initial_state(
+    model_type: str = "rnn",
+    config_path: str | Path | None = None,
+) -> dict[str, Any]:
+    """Create the initial AgentState for a new tuning run.
+
+    Args:
+        model_type: Model to tune ('rnn', 'encoder', 'decoder').
+        config_path: Path to agent config YAML.
+
+    Returns:
+        Initial state dict for the graph.
+    """
+    return {
+        "iteration": 0,
+        "model_type": model_type,
+        "history": [],
+        "best_config": {},
+        "best_accuracy": 0.0,
+        "best_loss": float("inf"),
+        "search_space_overrides": {},
+        "agent_config_path": str(config_path) if config_path else None,
+        "converged": False,
+    }
+
+
+async def run_agent_tuning(
+    model_type: str = "rnn",
+    config_path: str | Path | None = None,
+) -> AgentRunResult:
+    """Run the complete agent tuning loop.
+
+    This is the main entry point for the tuning agent. It:
+    1. Builds the LangGraph state graph
+    2. Creates initial state
+    3. Runs the graph to completion
+    4. Returns the best configuration found
+
+    Args:
+        model_type: Model to tune ('rnn', 'encoder', 'decoder').
+        config_path: Path to agent config YAML (uses default if None).
+
+    Returns:
+        AgentRunResult with the best configuration and full history.
+    """
+    graph = build_graph(model_type, config_path)
+    initial_state = create_initial_state(model_type, config_path)
+
+    logger.info(
+        "starting_agent_tuning",
+        model_type=model_type,
+        config_path=str(config_path) if config_path else "default",
+    )
+
+    # Run the graph
+    final_state = await graph.ainvoke(initial_state)
+
+    # Extract final result
+    final_result = final_state.get("final_result")
+    if final_result is None:
+        # Build result from state if graph didn't set it explicitly
+        final_result = AgentRunResult(
+            best_config=final_state.get("best_config", {}),
+            best_accuracy=final_state.get("best_accuracy", 0.0),
+            best_loss=final_state.get("best_loss", float("inf")),
+            iterations_completed=final_state.get("iteration", 0),
+            converged=final_state.get("converged", False),
+        )
+
+    logger.info(
+        "agent_tuning_complete",
+        best_accuracy=final_result.best_accuracy,
+        best_loss=final_result.best_loss,
+        iterations=final_result.iterations_completed,
+        converged=final_result.converged,
+    )
+
+    return final_result

sentimentizer/agent/loader.py

@@ -0,0 +1,90 @@
+"""Load agent and tuner configuration from YAML.
+
+Provides dataclass-backed configuration loading with sensible defaults,
+so the YAML file only needs to override what differs from defaults.
+
+TunerConfig and load_search_space live in sentimentizer.tuner (the
+standalone tuning module). This module re-exports them for convenience
+and adds AgentConfig, which is agent-specific.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from sentimentizer.tuner import TunerConfig
+
+
+@dataclass
+class CheckpointConfig:
+    """LangGraph checkpointing configuration."""
+
+    enabled: bool = True
+    db_path: str = "agent_checkpoints.db"
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for the Pydantic AI tuning agent.
+
+    Connects to GLM 5.1 (or any model) via Ollama's OpenAI-compatible API.
+    """
+
+    model_name: str = "glm-5.1:cloud"
+    ollama_base_url: str = "http://localhost:11434/v1"
+    temperature: float = 0.3
+    max_tokens: int = 2048
+    max_iterations: int = 5
+    convergence_threshold: float = 0.005
+    initial_search_strategy: str = "bayesian"
+    checkpointing: CheckpointConfig = field(default_factory=CheckpointConfig)
+    human_in_the_loop: bool = False
+
+
+def _get_default_config_path() -> Path:
+    """Return path to the default config.yaml bundled with the package."""
+    return Path(__file__).parent / "config.yaml"
+
+
+def _config_dict_to_agent_config(agent_dict: dict[str, Any]) -> AgentConfig:
+    """Convert the agent section of the YAML dict into an AgentConfig."""
+    cp_dict = agent_dict.pop("checkpointing", {})
+    checkpoint_cfg = CheckpointConfig(**cp_dict)
+    return AgentConfig(checkpointing=checkpoint_cfg, **agent_dict)
+
+
+def load_agent_config(
+    path: str | Path | None = None,
+) -> tuple[AgentConfig, TunerConfig]:
+    """Load agent and tuner configuration from a YAML file.
+
+    Args:
+        path: Path to YAML config file. If None, uses the default
+              config.yaml bundled with the package.
+
+    Returns:
+        Tuple of (AgentConfig, TunerConfig) with all settings populated.
+
+    Raises:
+        FileNotFoundError: If the config file doesn't exist.
+    """
+    path = _get_default_config_path() if path is None else Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Agent config file not found: {path}")
+
+    with open(path) as f:
+        raw = yaml.safe_load(f)
+
+    agent_cfg = _config_dict_to_agent_config(raw.get("agent", {}))
+    tuner_cfg = TunerConfig(**raw.get("tuner", {}))
+
+    return agent_cfg, tuner_cfg
+
+
+# Allow overriding config path via environment variable
+CONFIG_PATH_ENV = "SENTIMENTIZER_AGENT_CONFIG"

sentimentizer/agent/models.py

@@ -0,0 +1,104 @@
+"""Pydantic models for the tuning agent's structured input/output.
+
+These models validate the LLM's responses and the tuning results,
+ensuring that only valid configurations are passed to Ray Tune.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class SearchSpaceParam(BaseModel):
+    """A single parameter's search space specification.
+
+    Produced by the LLM agent when it decides to narrow/widen
+    the search space for a hyperparameter.
+    """
+
+    type: Literal["loguniform", "uniform", "choice", "randint"]
+    low: float | None = None
+    high: float | None = None
+    values: list[int] | list[float] | None = None
+
+
+class TuningDecision(BaseModel):
+    """Structured output from the strategy agent.
+
+    The LLM produces this after analyzing training metrics.
+    Pydantic validates it, rejecting hallucinated or invalid configs.
+    """
+
+    reasoning: str = Field(
+        ...,
+        description="Brief explanation of why this strategy was chosen",
+    )
+    strategy: Literal["widen", "narrow", "change_focus", "increase_epochs", "stop"] = Field(
+        ...,
+        description="The tuning strategy to apply next",
+    )
+    search_space: dict[str, SearchSpaceParam] = Field(
+        ...,
+        description="Updated search space parameters for Ray Tune",
+    )
+    num_samples: int = Field(
+        default=20,
+        ge=5,
+        le=100,
+        description="Number of trials for Ray Tune to run",
+    )
+
+
+class TuningResult(BaseModel):
+    """Result from a single Ray Tune tuning run.
+
+    Fed back to the LLM agent for analysis in the next iteration.
+    """
+
+    best_accuracy: float = Field(..., description="Best validation accuracy achieved")
+    best_loss: float = Field(..., description="Best validation loss achieved")
+    best_config: dict[str, float | int] = Field(
+        ..., description="Best hyperparameter configuration found"
+    )
+    trial_count: int = Field(..., description="Number of trials completed")
+    improvement_over_last: float = Field(
+        default=0.0, description="Accuracy improvement vs. previous best"
+    )
+
+
+class AnalysisResult(BaseModel):
+    """Structured output from the analysis agent.
+
+    The LLM produces this after examining training metrics and history.
+    """
+
+    summary: str = Field(..., description="Brief summary of the training results")
+    overfitting: bool = Field(
+        default=False, description="Whether the model appears to be overfitting"
+    )
+    underfitting: bool = Field(
+        default=False, description="Whether the model appears to be underfitting"
+    )
+    lr_status: Literal["too_high", "too_low", "appropriate", "unclear"] = Field(
+        default="unclear", description="Assessment of the learning rate"
+    )
+    suggested_focus: list[str] = Field(
+        default_factory=list,
+        description="Parameters to focus on in the next iteration",
+    )
+
+
+class AgentRunResult(BaseModel):
+    """Final result from the complete agent tuning loop.
+
+    Returned when the agent converges or reaches max iterations.
+    """
+
+    best_config: dict[str, float | int]
+    best_accuracy: float
+    best_loss: float
+    iterations_completed: int
+    converged: bool
+    history: list[TuningResult] = Field(default_factory=list)