lightman_ai 0.20.1__py3-none-any.whl

lightman_ai/ai/base/agent.py

@@ -0,0 +1,26 @@
+import logging
+from abc import ABC, abstractmethod
+from typing import Never
+
+from lightman_ai.article.models import SelectedArticlesList
+from pydantic_ai import Agent
+from pydantic_ai.models.google import GoogleModel
+from pydantic_ai.models.openai import OpenAIModel
+
+
+class BaseAgent(ABC):
+    _class: type[OpenAIModel] | type[GoogleModel]
+    _default_model_name: str
+
+    def __init__(self, system_prompt: str, model: str | None = None, logger: logging.Logger | None = None) -> None:
+        agent_model = self._class(model or self._default_model_name)
+        self.agent: Agent[Never, SelectedArticlesList] = Agent(
+            model=agent_model, output_type=SelectedArticlesList, system_prompt=system_prompt
+        )
+        self.logger = logger or logging.getLogger("lightman")
+
+    def get_prompt_result(self, prompt: str) -> SelectedArticlesList:
+        return self._run_prompt(prompt)
+
+    @abstractmethod
+    def _run_prompt(self, prompt: str) -> SelectedArticlesList: ...

lightman_ai/ai/base/exceptions.py

@@ -0,0 +1,4 @@
+from lightman_ai.core.exceptions import BaseHackermanError
+
+
+class BaseAgentError(BaseHackermanError): ...

lightman_ai/ai/gemini/agent.py

@@ -0,0 +1,19 @@
+from typing import override
+
+from lightman_ai.ai.base.agent import BaseAgent
+from lightman_ai.ai.gemini.exceptions import map_gemini_exceptions
+from lightman_ai.article.models import SelectedArticlesList
+from pydantic_ai.models.google import GoogleModel
+
+
+class GeminiAgent(BaseAgent):
+    """Class that provides an interface to operate with the Gemini model."""
+
+    _class = GoogleModel
+    _default_model_name = "gemini-2.5-pro-preview-05-06"
+
+    @override
+    def _run_prompt(self, prompt: str) -> SelectedArticlesList:
+        with map_gemini_exceptions():
+            result = self.agent.run_sync(prompt)
+        return result.output

lightman_ai/ai/gemini/exceptions.py

@@ -0,0 +1,19 @@
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+from lightman_ai.core.exceptions import BaseHackermanError
+
+
+class BaseGeminiError(BaseHackermanError): ...
+
+
+class GeminiError(BaseGeminiError): ...
+
+
+@contextmanager
+def map_gemini_exceptions() -> Generator[Any, Any]:
+    try:
+        yield
+    except Exception as err:
+        raise GeminiError from err

lightman_ai/ai/openai/agent.py

@@ -0,0 +1,29 @@
+import time
+from typing import override
+
+from lightman_ai.ai.base.agent import BaseAgent
+from lightman_ai.ai.openai.exceptions import LimitTokensExceededError, map_openai_exceptions
+from lightman_ai.article.models import SelectedArticlesList
+from pydantic_ai.agent import AgentRunResult
+from pydantic_ai.models.openai import OpenAIModel
+
+
+class OpenAIAgent(BaseAgent):
+    """Class that provides an interface to operate with the OpenAI model."""
+
+    _class = OpenAIModel
+    _default_model_name = "gpt-4.1"
+
+    def _execute_agent(self, prompt: str) -> AgentRunResult[SelectedArticlesList]:
+        with map_openai_exceptions():
+            return self.agent.run_sync(prompt)
+
+    @override
+    def _run_prompt(self, prompt: str) -> SelectedArticlesList:
+        try:
+            result = self._execute_agent(prompt)
+        except LimitTokensExceededError as err:
+            self.logger.warning("waiting %s", err.wait_time)
+            time.sleep(err.wait_time)
+            result = self._execute_agent(prompt)
+        return result.output

lightman_ai/ai/openai/exceptions.py

@@ -0,0 +1,85 @@
+import math
+import re
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any, override
+
+from lightman_ai.core.exceptions import BaseHackermanError
+from pydantic_ai.exceptions import ModelHTTPError
+
+from openai import RateLimitError
+
+
+class BaseOpenAIError(BaseHackermanError): ...
+
+
+class UnknownOpenAIError(BaseOpenAIError): ...
+
+
+class OpenAIRateLimitError(BaseOpenAIError):
+    regex: str
+
+    @classmethod
+    def get_matches(cls, message: str) -> tuple[str, ...]:
+        match = re.search(cls.regex, message)
+        return match.groups() if match else ()
+
+    @classmethod
+    def is_match(cls, message: str) -> bool:
+        return bool(re.search(cls.regex, message))
+
+
+class InputTooLargeError(OpenAIRateLimitError):
+    limit: int
+    requested: int
+
+    regex: str = (
+        r"Limit (\d+), Requested (\d+)\. The input or output tokens must be reduced in order to run successfully\."
+    )
+
+    def __init__(self, values: tuple[str, ...]) -> None:
+        self.limit = int(values[0])
+        self.requested = int(values[1])
+
+
+class LimitTokensExceededError(OpenAIRateLimitError):
+    limit: int
+    used: int
+    requested: int
+    wait_time: int
+
+    regex = r"Limit (\d+), Used (\d+), Requested (\d+)\. Please try again in (\d+\.?(\d+)?)s\."
+
+    def __init__(self, values: tuple[str, ...]) -> None:
+        self.limit = int(values[0])
+        self.used = int(values[1])
+        self.requested = int(values[2])
+        self.wait_time = math.ceil(float(values[3]))
+
+
+class QuotaExceededError(OpenAIRateLimitError):
+    regex = r"You exceeded your current quota"
+
+    @override
+    @classmethod
+    def get_matches(cls, message: str) -> tuple[str, ...]:
+        match = re.search(cls.regex, message)
+        return match.groups() if match else ()
+
+
+type TRateLimitErr = type[InputTooLargeError | LimitTokensExceededError]
+RATE_LIMIT_ERRORS: list[TRateLimitErr] = [LimitTokensExceededError, InputTooLargeError]
+
+
+@contextmanager
+def map_openai_exceptions() -> Generator[Any, Any]:
+    try:
+        yield
+    except RateLimitError as err:
+        for error in RATE_LIMIT_ERRORS:
+            if matches := error.get_matches(err.message):
+                raise error(matches) from err
+        raise UnknownOpenAIError from err
+    except ModelHTTPError as err:
+        if QuotaExceededError.is_match(err.message):
+            raise QuotaExceededError() from err

lightman_ai/ai/utils.py

@@ -0,0 +1,14 @@
+from lightman_ai.ai.base.agent import BaseAgent
+from lightman_ai.ai.gemini.agent import GeminiAgent
+from lightman_ai.ai.openai.agent import OpenAIAgent
+
+AGENT_MAPPING = {"openai": OpenAIAgent, "gemini": GeminiAgent}
+
+
+def get_agent_class_from_agent_name(agent: str) -> type[BaseAgent]:
+    if agent not in AGENT_MAPPING:
+        raise ValueError(f"Agent '{agent}' is not recognized. Available agents: {list(AGENT_MAPPING.keys())}")
+    return AGENT_MAPPING[agent]
+
+
+AGENT_CHOICES = list(AGENT_MAPPING.keys())

lightman_ai/article/models.py

@@ -0,0 +1,64 @@
+from abc import ABC
+from typing import override
+
+from pydantic import BaseModel
+
+
+class BaseArticle(BaseModel, ABC):
+    """Base abstract class for all Articles."""
+
+    title: str
+    link: str
+
+    @override
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, BaseArticle):
+            return False
+
+        return self.link == value.link
+
+    @override
+    def __hash__(self) -> int:
+        return hash(self.link.encode())
+
+
+class SelectedArticle(BaseArticle):
+    why_is_relevant: str
+    relevance_score: int
+
+
+class Article(BaseArticle):
+    title: str
+    description: str
+
+
+class BaseArticlesList[TArticle: BaseArticle](BaseModel):
+    articles: list[TArticle]
+
+    def __len__(self) -> int:
+        return len(self.articles)
+
+    @property
+    def titles(self) -> list[str]:
+        return [new.title for new in self.articles]
+
+    @property
+    def links(self) -> list[str]:
+        return [new.link for new in self.articles]
+
+
+class SelectedArticlesList(BaseArticlesList[SelectedArticle]):
+    """
+    Model that holds all the articles that were selected by the AI model.
+
+    It saves the minimum information so that they are identifiable.
+    """
+
+    def get_articles_with_score_gte_threshold(self, score_threshold: int) -> list[SelectedArticle]:
+        if not score_threshold > 0:
+            raise ValueError("score threshold must be > 0.")
+        return [article for article in self.articles if article.relevance_score >= score_threshold]
+
+
+class ArticlesList(BaseArticlesList[Article]):
+    """Model that saves articles with all their information."""

lightman_ai/cli.py

@@ -0,0 +1,113 @@
+import logging
+from importlib import metadata
+
+import click
+from dotenv import load_dotenv
+from lightman_ai.ai.utils import AGENT_CHOICES
+from lightman_ai.constants import DEFAULT_CONFIG_FILE, DEFAULT_CONFIG_SECTION, DEFAULT_ENV_FILE
+from lightman_ai.core.config import FileConfig, FinalConfig, PromptConfig
+from lightman_ai.core.exceptions import ConfigNotFoundError, InvalidConfigError, PromptNotFoundError
+from lightman_ai.core.sentry import configure_sentry
+from lightman_ai.main import lightman
+
+logger = logging.getLogger("lightman")
+
+
+def get_version() -> str:
+    """Read version from VERSION file."""
+    return metadata.version("lightman-ai")
+
+
+@click.group()
+@click.version_option(version=get_version(), prog_name="lightman-ai")
+def entry_point() -> None:
+    pass
+
+
+@entry_point.command()
+@click.option("--agent", type=click.Choice(AGENT_CHOICES), help=("Which agent to use"))
+@click.option(
+    "--prompt-file",
+    type=str,
+    default=DEFAULT_CONFIG_FILE,
+    help=(f"Location of the config file containing the prompts. Defaults to `{DEFAULT_CONFIG_FILE}`."),
+)
+@click.option("--prompt", type=str, help=("Which prompt to use"))
+@click.option("--model", type=str, default=None, help=("Which model to use. Must be set in conjunction with --agent."))
+@click.option(
+    "--score",
+    type=int,
+    help=("The minimum score relevance that an article needs to have to be considered relevant"),
+    default=None,
+)
+@click.option(
+    "--config-file",
+    type=str,
+    default=DEFAULT_CONFIG_FILE,
+    help=(f"The config file path. Defaults to `{DEFAULT_CONFIG_FILE}`."),
+)
+@click.option(
+    "--config",
+    type=str,
+    default=DEFAULT_CONFIG_SECTION,
+    help=(f"The config settings to use. Defaults to `{DEFAULT_CONFIG_SECTION}`."),
+)
+@click.option(
+    "--env-file",
+    type=str,
+    default=DEFAULT_ENV_FILE,
+    help=(f"Path to the environment file. Defaults to `{DEFAULT_ENV_FILE}`."),
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help=(
+        "When set, runs the script without publishing the results to the integrated services, just shows them in stdout."
+    ),
+)
+def run(
+    agent: str,
+    prompt: str,
+    prompt_file: str,
+    model: str | None,
+    score: int | None,
+    config_file: str,
+    config: str,
+    env_file: str,
+    dry_run: bool,
+) -> int:
+    """
+    Entrypoint of the application.
+
+    Holds no logic. It calls the main method and returns 0 when succesful .
+    """
+    load_dotenv(env_file)
+    configure_sentry()
+    try:
+        prompt_config = PromptConfig.get_config_from_file(path=prompt_file)
+        config_from_file = FileConfig.get_config_from_file(config_section=config, path=config_file)
+        final_config = FinalConfig.init_from_dict(
+            data={
+                "agent": agent or config_from_file.agent,
+                "prompt": prompt or config_from_file.prompt,
+                "score_threshold": score or config_from_file.score_threshold,
+                "model": model or config_from_file.model,
+            }
+        )
+
+        prompt_text = prompt_config.get_prompt(final_config.prompt)
+    except (InvalidConfigError, PromptNotFoundError, ConfigNotFoundError) as err:
+        raise click.BadParameter(err.args[0]) from None
+
+    relevant_articles = lightman(
+        agent=final_config.agent,
+        prompt=prompt_text,
+        score_threshold=final_config.score_threshold,
+        dry_run=dry_run,
+        project_key=config_from_file.service_desk_project_key,
+        request_id_type=config_from_file.service_desk_request_id_type,
+        model=final_config.model,
+    )
+    relevant_articles_metadata = [f"{article.title} ({article.link})" for article in relevant_articles]
+    logger.warning("Found these articles: \n- %s", "\n- ".join(relevant_articles_metadata))
+    return 0

lightman_ai/constants.py

@@ -0,0 +1,5 @@
+DEFAULT_CONFIG_SECTION = "default"
+
+DEFAULT_CONFIG_FILE = "lightman.toml"
+
+DEFAULT_ENV_FILE = ".env"

lightman_ai/core/config.py

@@ -0,0 +1,92 @@
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Self, cast
+
+import tomlkit
+from lightman_ai.core.exceptions import ConfigNotFoundError, InvalidConfigError, PromptNotFoundError
+from pydantic import BaseModel, ConfigDict, PositiveInt, ValidationError, field_validator
+from pydantic_core.core_schema import FieldValidationInfo
+
+PROMPTS_SECTION = "prompts"
+logger = logging.getLogger("lightman")
+
+
+def read_config_from_file(*, config_section: str, path: str) -> dict[str, Any]:
+    fpath = Path(path)
+    if not fpath.exists():
+        raise ConfigNotFoundError(f"`{path}` not found!")
+
+    content = fpath.read_text()
+    parsed_content = tomlkit.parse(content)
+
+    return cast("dict[str, Any]", parsed_content.get(config_section, {}))
+
+
+@dataclass
+class PromptConfig:
+    prompts: dict[str, str]
+
+    @classmethod
+    def get_config_from_file(cls, path: str) -> Self:
+        config = read_config_from_file(config_section=PROMPTS_SECTION, path=path)
+        return cls(prompts=config)
+
+    def get_prompt(self, prompt: str) -> str:
+        if prompt not in self.prompts:
+            raise PromptNotFoundError(f"prompt `{prompt}` not found in config file")
+        return self.prompts[prompt]
+
+
+class FileConfig(BaseModel):
+    prompt: str | None = None
+    agent: str | None = None
+    score_threshold: int | None = None
+    service_desk_project_key: str | None = None
+    service_desk_request_id_type: str | None = None
+    model: str | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("service_desk_project_key", "service_desk_request_id_type", mode="before")
+    @classmethod
+    def _cast_service_fields(cls, v: Any, info: FieldValidationInfo) -> Any:
+        if v is None:
+            return v
+        if isinstance(v, int):
+            return str(v)
+        if isinstance(v, str):
+            if v == "":
+                return v
+            try:
+                int(v)
+            except ValueError as err:
+                raise ValueError(f"{info.field_name} must be a number!") from err
+        return v
+
+    @classmethod
+    def get_config_from_file(cls, config_section: str, path: str) -> Self:
+        try:
+            config = read_config_from_file(config_section=config_section, path=path)
+        except ConfigNotFoundError:
+            logger.warning("Config file `%s` not found! Proceeding with empty config.", path)
+            config = {}
+        return cls(**config)
+
+
+class FinalConfig(BaseModel):
+    prompt: str
+    agent: str
+    score_threshold: PositiveInt
+    model: str | None = None
+
+    @classmethod
+    def init_from_dict(cls, data: dict[str, Any]) -> Self:
+        try:
+            return cls(**data)
+        except ValidationError as error:
+            error_list = []
+            for err in error.errors():
+                error_list.append(f"`{err['loc'][0]}`: {err['msg']}")
+            err_msg = f"Invalid configuration provided: [{','.join(error_list)}]"
+            raise InvalidConfigError(err_msg) from error

lightman_ai/core/exceptions.py

@@ -0,0 +1,13 @@
+class BaseHackermanError(Exception): ...
+
+
+class BaseConfigError(BaseHackermanError): ...
+
+
+class InvalidConfigError(BaseConfigError): ...
+
+
+class ConfigNotFoundError(BaseConfigError): ...
+
+
+class PromptNotFoundError(BaseConfigError): ...

lightman_ai/core/sentry.py

@@ -0,0 +1,28 @@
+import logging
+import os
+from importlib import metadata
+
+import sentry_sdk
+from sentry_sdk.integrations.logging import LoggingIntegration
+
+
+def configure_sentry() -> None:
+    """Configure Sentry for error tracking and performance monitoring using env vars with fallbacks."""
+    try:
+        if not os.getenv("SENTRY_DSN"):
+            logging.getLogger("lightman").info("SENTRY_DSN not configured, skipping Sentry initialization")
+            return
+
+        # Logging level from ENV
+        logging_level_str = os.getenv("LOGGING_LEVEL", "ERROR").upper()
+        logging_level = getattr(logging, logging_level_str, logging.ERROR)
+
+        # Set up logging integration
+        sentry_logging = LoggingIntegration(level=logging.INFO, event_level=logging_level)
+
+        sentry_sdk.init(
+            release=metadata.version("lightman-ai"),
+            integrations=[sentry_logging],
+        )
+    except Exception as e:
+        logging.getLogger("lightman").warning("Could not instantiate Sentry! %s.\nContinuing with the execution.", e)

lightman_ai/core/settings.py

@@ -0,0 +1,14 @@
+from typing import Any
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+    OPENAI_ENCODING: str = "cl100k_base"
+    PARALLEL_WORKERS: int = 5
+
+
+settings = Settings()

lightman_ai/integrations/service_desk/__init__.py

@@ -0,0 +1 @@
+# This file marks the service_desk directory as a Python package.

lightman_ai/integrations/service_desk/constants.py

@@ -0,0 +1,7 @@
+import httpx
+from lightman_ai.integrations.service_desk.exceptions import ServiceDeskServerError
+
+# Retry configuration for ServiceDeskIntegration
+SERVICE_DESK_RETRY_ON = (httpx.TransportError, httpx.TimeoutException, ServiceDeskServerError)
+SERVICE_DESK_RETRY_ATTEMPTS = 3
+SERVICE_DESK_RETRY_TIMEOUT = 10

lightman_ai/integrations/service_desk/exceptions.py

@@ -0,0 +1,76 @@
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+from lightman_ai.core.exceptions import BaseHackermanError
+
+logger = logging.getLogger("lightman")
+
+
+class BaseServiceDeskError(BaseHackermanError):
+    """Base exception for all SERVICE_DESK integration errors."""
+
+
+class ServiceDeskConnectionError(BaseServiceDeskError):
+    """Raised when there are network or connection issues with SERVICE_DESK."""
+
+
+class ServiceDeskAuthenticationError(BaseServiceDeskError):
+    """Raised when authentication with SERVICE_DESK fails."""
+
+
+class ServiceDeskPermissionError(BaseServiceDeskError):
+    """Raised when user lacks permissions to perform the requested operation."""
+
+
+class MissingIssueIDError(BaseServiceDeskError):
+    """Error for when we don't get the issue ID in the response."""
+
+    pass
+
+
+class ServiceDeskHTTPStatusError(BaseServiceDeskError):
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"SERVICE_DESK API error {status_code}: {message}")
+
+
+class ServiceDeskClientError(ServiceDeskHTTPStatusError):
+    """Exception for unmapped HTTP 4xx errors."""
+
+    pass
+
+
+class ServiceDeskServerError(ServiceDeskHTTPStatusError):
+    """Exception for HTTP 5xx errors."""
+
+    pass
+
+
+class ServiceDeskApiResponseParsingError(BaseServiceDeskError):
+    """Raised when SERVICE_DESK API returns an error response that cannot be parsed."""
+
+    def __init__(self, status_code: int, raw_response: str) -> None:
+        self.status_code = status_code
+        self.raw_response = raw_response
+        super().__init__(f"SERVICE_DESK API error {status_code}: Unable to parse error response")
+
+
+@asynccontextmanager
+async def handle_service_desk_exceptions() -> AsyncGenerator[Any, Any]:
+    try:
+        yield
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == httpx.codes.UNAUTHORIZED:
+            raise ServiceDeskAuthenticationError from e
+        elif e.response.status_code == httpx.codes.FORBIDDEN:
+            raise ServiceDeskPermissionError from e
+        elif e.response.is_client_error:
+            raise ServiceDeskClientError(e.response.status_code, e.response.text) from e
+        else:
+            raise ServiceDeskServerError(e.response.status_code, e.response.text) from e
+    except httpx.TransportError as e:
+        raise ServiceDeskConnectionError(f"Network error: {e}") from e