xploreai 0.2.0__tar.gz

xploreai-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.3
+Name: xploreai
+Version: 0.2.0
+Summary: Library and cookbook codes for AI Engineering Projects
+Author: Daniel Dominguete
+Author-email: Daniel Dominguete <daniel.dominguete@gmail.com>
+Requires-Dist: pytest>=9.2.0
+Requires-Python: >=3.12, <3.13
+Description-Content-Type: text/markdown
+
+# XploreAI
+
+Biblioteca Python e cookbook para experimentos em engenharia de AI
+
+## Estrutura do repositório
+
+```
+src/xploreai/   → biblioteca (publicável no PyPI)
+cookbook/       → scripts e notebooks de receitas locais (ex.: langchain/)
+references/     → material de estudo externo (somente leitura)
+```
+
+## Módulos da biblioteca (`src/xploreai/`)
+
+Pacotes por domínio; cada módulo segue o prefixo **`xai_`** (Xplore AI).
+
+| Pacote | Arquivo | Responsabilidade |
+|--------|---------|------------------|
+| `environment` | `xai_localhost.py` | Estrutura de pastas para runs locais |
+| `log` | `xai_log.py` | Logging estruturado e perfil de ambiente em execuções |
+| `utils` | `xai_environment.py` | Localizar a raiz do projeto (`pyproject.toml`) |
+| `utils` | `xai_memory.py` | Conversão e utilitários de memória (unidades binárias) |
+
+## Configuração do ambiente
+
+Este projeto usa **[uv](https://docs.astral.sh/uv/)** para ambientes e dependências.
+Não use `requirements.txt` na raiz nem `pip install` — tudo fica em **`pyproject.toml`** + **`uv.lock`**.
+
+### 1. Instalar uv
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 2. Inicializar ambiente do projeto
+
+Na raiz do repositório (onde está o `pyproject.toml`):
+
+```bash
+uv sync --all-groups
+```
+
+O `uv sync` cria `.venv/`, instala dependências fixadas em `uv.lock` e registra **`xploreai`** em modo editável a partir de `src/xploreai/`.
+
+Para **criar um projeto Python novo** com uv (fora deste repo):
+
+```bash
+uv init --python 3.12
+uv add pandas          # exemplo: adiciona dependencia e atualiza pyproject.toml + uv.lock
+uv sync
+```
+
+### 3. Notebooks sem output no Git (nbstripout)
+
+Este repo **nao usa** o pacote [`pre-commit`](https://pre-commit.com/) para notebooks. A limpeza e feita pelo **filtro Git** do [`nbstripout`](https://github.com/kynan/nbstripout) (ja dependencia em `pyproject.toml`).
+
+**Uma vez por clone** (depois de `uv sync`), na raiz do repo:
+
+```bash
+uv run nbstripout --install --attributes .gitattributes
+```
+
+Isso registra o filtro em `.git/config` e versiona regras em `.gitattributes` (`*.ipynb filter=nbstripout`). No `git add`, outputs sao removidos do que entra no indice; no working tree voce pode continuar executando o notebook normalmente.
+
+Conferir se esta ativo:
+
+```bash
+uv run nbstripout --is-installed
+uv run nbstripout --status
+```
+
+Se recriar o `.venv` ou mudar o caminho do Python, reinstale o filtro:
+
+```bash
+uv run nbstripout --install --attributes .gitattributes --force
+```
+
+Limpar notebooks ja versionados (one-shot), se necessario:
+
+```bash
+uv run nbstripout $(git ls-files '*.ipynb')
+```
+
+Validar CI/local sem alterar arquivos:
+
+```bash
+uv run nbstripout --verify $(git ls-files '*.ipynb')
+```
+
+### 4. Execução
+
+Validação do setup:
+
+```bash
+uv run xploreai
+```
+
+Testes:
+
+```bash
+uv run pytest
+```
+
+Exemplo de cookbook:
+
+```bash
+uv run python cookbook/01_langchain/prompt_template.py
+```
+
+## Versionamento semântico (Commitizen)
+
+Commits seguem **[Conventional Commits](https://www.conventionalcommits.org/)** via [Commitizen](https://commitizen-tools.github.io/commitizen/). A versão do pacote vive em `pyproject.toml` (`[project].version`); o `cz bump` atualiza essa versão, o `CHANGELOG.md` e cria a tag Git `vX.Y.Z`.
+
+### Commits e push
+
+```bash
+git add .
+uv run cz commit
+git push   # sem publicação de nova versão
+```
+
+| Tipo | Quando usar | Bump |
+|------|-------------|------|
+| `feat` | Nova funcionalidade | minor |
+| `fix` | Correção de bug | patch |
+| `docs` | Documentação | — |
+| `refactor` | Refatoração | patch |
+| `test` | Testes | — |
+| `chore` | Manutenção | — |
+
+### Release e publicação
+
+```bash
+uv run cz bump          # bump de versão + CHANGELOG + tag
+uv build                # gera dist/*.whl
+uv run --with xploreai --no-project -- python -c "import xploreai"  # testar artefato
+uv run --env-file .env --no-project -- uv publish   # PyPI (token em UV_PUBLISH_TOKEN)
+git push && git push --tags
+```

xploreai-0.2.0/README.md

@@ -0,0 +1,139 @@
+# XploreAI
+
+Biblioteca Python e cookbook para experimentos em engenharia de AI
+
+## Estrutura do repositório
+
+```
+src/xploreai/   → biblioteca (publicável no PyPI)
+cookbook/       → scripts e notebooks de receitas locais (ex.: langchain/)
+references/     → material de estudo externo (somente leitura)
+```
+
+## Módulos da biblioteca (`src/xploreai/`)
+
+Pacotes por domínio; cada módulo segue o prefixo **`xai_`** (Xplore AI).
+
+| Pacote | Arquivo | Responsabilidade |
+|--------|---------|------------------|
+| `environment` | `xai_localhost.py` | Estrutura de pastas para runs locais |
+| `log` | `xai_log.py` | Logging estruturado e perfil de ambiente em execuções |
+| `utils` | `xai_environment.py` | Localizar a raiz do projeto (`pyproject.toml`) |
+| `utils` | `xai_memory.py` | Conversão e utilitários de memória (unidades binárias) |
+
+## Configuração do ambiente
+
+Este projeto usa **[uv](https://docs.astral.sh/uv/)** para ambientes e dependências.
+Não use `requirements.txt` na raiz nem `pip install` — tudo fica em **`pyproject.toml`** + **`uv.lock`**.
+
+### 1. Instalar uv
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 2. Inicializar ambiente do projeto
+
+Na raiz do repositório (onde está o `pyproject.toml`):
+
+```bash
+uv sync --all-groups
+```
+
+O `uv sync` cria `.venv/`, instala dependências fixadas em `uv.lock` e registra **`xploreai`** em modo editável a partir de `src/xploreai/`.
+
+Para **criar um projeto Python novo** com uv (fora deste repo):
+
+```bash
+uv init --python 3.12
+uv add pandas          # exemplo: adiciona dependencia e atualiza pyproject.toml + uv.lock
+uv sync
+```
+
+### 3. Notebooks sem output no Git (nbstripout)
+
+Este repo **nao usa** o pacote [`pre-commit`](https://pre-commit.com/) para notebooks. A limpeza e feita pelo **filtro Git** do [`nbstripout`](https://github.com/kynan/nbstripout) (ja dependencia em `pyproject.toml`).
+
+**Uma vez por clone** (depois de `uv sync`), na raiz do repo:
+
+```bash
+uv run nbstripout --install --attributes .gitattributes
+```
+
+Isso registra o filtro em `.git/config` e versiona regras em `.gitattributes` (`*.ipynb filter=nbstripout`). No `git add`, outputs sao removidos do que entra no indice; no working tree voce pode continuar executando o notebook normalmente.
+
+Conferir se esta ativo:
+
+```bash
+uv run nbstripout --is-installed
+uv run nbstripout --status
+```
+
+Se recriar o `.venv` ou mudar o caminho do Python, reinstale o filtro:
+
+```bash
+uv run nbstripout --install --attributes .gitattributes --force
+```
+
+Limpar notebooks ja versionados (one-shot), se necessario:
+
+```bash
+uv run nbstripout $(git ls-files '*.ipynb')
+```
+
+Validar CI/local sem alterar arquivos:
+
+```bash
+uv run nbstripout --verify $(git ls-files '*.ipynb')
+```
+
+### 4. Execução
+
+Validação do setup:
+
+```bash
+uv run xploreai
+```
+
+Testes:
+
+```bash
+uv run pytest
+```
+
+Exemplo de cookbook:
+
+```bash
+uv run python cookbook/01_langchain/prompt_template.py
+```
+
+## Versionamento semântico (Commitizen)
+
+Commits seguem **[Conventional Commits](https://www.conventionalcommits.org/)** via [Commitizen](https://commitizen-tools.github.io/commitizen/). A versão do pacote vive em `pyproject.toml` (`[project].version`); o `cz bump` atualiza essa versão, o `CHANGELOG.md` e cria a tag Git `vX.Y.Z`.
+
+### Commits e push
+
+```bash
+git add .
+uv run cz commit
+git push   # sem publicação de nova versão
+```
+
+| Tipo | Quando usar | Bump |
+|------|-------------|------|
+| `feat` | Nova funcionalidade | minor |
+| `fix` | Correção de bug | patch |
+| `docs` | Documentação | — |
+| `refactor` | Refatoração | patch |
+| `test` | Testes | — |
+| `chore` | Manutenção | — |
+
+### Release e publicação
+
+```bash
+uv run cz bump          # bump de versão + CHANGELOG + tag
+uv build                # gera dist/*.whl
+uv run --with xploreai --no-project -- python -c "import xploreai"  # testar artefato
+uv run --env-file .env --no-project -- uv publish   # PyPI (token em UV_PUBLISH_TOKEN)
+git push && git push --tags
+```

xploreai-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "xploreai"
+version = "0.2.0"
+description = "Library and cookbook codes for AI Engineering Projects"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+dependencies = ["pytest>=9.2.0"]
+
+[[project.authors]]
+name = "Daniel Dominguete"
+email = "daniel.dominguete@gmail.com"
+
+[project.scripts]
+xploreai = "xploreai:main"
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["commitizen>=4.19.3"]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+tag_format = "v$version"
+update_changelog_on_bump = true
+changelog_file = "CHANGELOG.md"
+major_version_zero = true

xploreai-0.2.0/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[project]
+name = "xploreai"
+version = "0.2.0"
+description = "Library and cookbook codes for AI Engineering Projects"
+readme = "README.md"
+authors = [
+    { name = "Daniel Dominguete", email = "daniel.dominguete@gmail.com" }
+]
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "pytest>=9.2.0",
+]
+
+[project.scripts]
+xploreai = "xploreai:main"
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "commitizen>=4.19.3",
+]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+tag_format = "v$version"
+update_changelog_on_bump = true
+changelog_file = "CHANGELOG.md"
+major_version_zero = true

xploreai-0.2.0/src/xploreai/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from xploreai!")

xploreai-0.2.0/src/xploreai/environment/xai_localhost.py

@@ -0,0 +1,20 @@
+"""
+Xplore DS :: Localhost Tools Package
+"""
+
+# importando as bibliotecas padrao
+from pathlib import Path
+import sys, os
+
+# Configurando path para raiz do projeto e setup de reconhecimento da pasta da lib
+project_folder = Path(__file__).resolve().parents[2]
+sys.path.append(str(project_folder))
+
+from xploredev.io.file import create_folder
+
+
+class XploreDevLocalhost:
+    def __init__(self, run_folder: str) -> None:
+
+        # criando a pasta de runs caso não exista
+        create_folder(str(run_folder) + "/runs")

xploreai-0.2.0/src/xploreai/log/xai_log.py

@@ -0,0 +1,211 @@
+"""
+Xplore DEV :: Logging Tools Package
+
+Structured logging for scripts and cookbook runs, including environment profiling.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import sys
+import time
+import warnings
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Final
+
+import psutil
+
+from xploreds.io.xds_file import create_folder
+from xploreds.utils.xds_memory import convert_bytes
+
+PathLike = str | Path
+
+_LOGGER_NAME: Final = "xploreds"
+_LOG_FORMAT: Final = "%(asctime)s - %(levelname)s - %(message)s"
+_LOG_DATE_FORMAT: Final = "%d-%m-%Y %H:%M:%S"
+_RUN_TIMESTAMP_FORMAT: Final = "%y%m%d%H%M%S"
+
+_SEPARATOR_TITLE: Final = "*" * 82
+_SEPARATOR_SUBTITLE: Final = "=" * 82
+_SEPARATOR_SECTION: Final = "-" * 82
+
+_VALID_WARNING_ACTIONS: Final = frozenset(
+    {"error", "ignore", "always", "default", "module", "once"}
+)
+
+
+def _configure_python_warnings() -> None:
+    """Apply warning filter from ``PYTHON_WARNINGS`` env var (default: ``default``)."""
+    action = os.getenv("PYTHON_WARNINGS", "default")
+    if action not in _VALID_WARNING_ACTIONS:
+        action = "default"
+    warnings.filterwarnings(action)
+
+
+def _log_bordered(logger: logging.Logger, message: str, separator: str) -> None:
+    """Log a message framed by the same separator line above and below."""
+    logger.info(separator)
+    logger.info(message)
+    logger.info(separator)
+
+
+class XploreDSLogging:
+    """
+    Configure and write structured logs for a single script execution.
+
+    Each run creates a timestamped folder under ``runs/`` with a dedicated
+    ``.log`` file. Use wrapper methods (``info``, ``title``, ``section``) to
+    keep log output consistent across projects.
+
+    Args:
+        project_root: Root directory of the project.
+        script_name: Name or path of the script being executed (used in log paths).
+    """
+
+    def __init__(self, project_root: PathLike, script_name: PathLike) -> None:
+        self.project_root = Path(project_root)
+        script_path = Path(script_name)
+        self.script_name = script_path.name
+
+        self.dt_init = datetime.now()
+        self.dt_init_str = self.dt_init.strftime(_RUN_TIMESTAMP_FORMAT)
+        self.ts_init = time.time()
+
+        script_stem = script_path.stem
+        self.log_run = f"{script_stem}_{self.dt_init_str}"
+        self.log_path = self.project_root / "runs" / self.log_run
+        self.log_name = f"{self.log_run}.log"
+        self.log_file = self.log_path / self.log_name
+
+        create_folder(self.log_path)
+        self.logger = self._setup_logger()
+        _configure_python_warnings()
+
+    def _setup_logger(self) -> logging.Logger:
+        """Configure file and console handlers for the current run."""
+        logger = logging.getLogger(_LOGGER_NAME)
+        logger.setLevel(logging.INFO)
+        logger.handlers.clear()
+        logger.propagate = False
+
+        formatter = logging.Formatter(_LOG_FORMAT, datefmt=_LOG_DATE_FORMAT)
+
+        file_handler = logging.FileHandler(self.log_file)
+        stream_handler = logging.StreamHandler(sys.stderr)
+        for handler in (file_handler, stream_handler):
+            handler.setFormatter(formatter)
+            logger.addHandler(handler)
+
+        return logger
+
+    def info(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log an information-level message."""
+        self.logger.info(message, *args, **kwargs)
+
+    def warning(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log a warning-level message."""
+        self.logger.warning(message, *args, **kwargs)
+
+    def error(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log an error-level message."""
+        self.logger.error(message, *args, **kwargs)
+
+    def title(self, message: str) -> None:
+        """Log a top-level title with a heavy separator."""
+        _log_bordered(self.logger, message, _SEPARATOR_TITLE)
+
+    def subtitle(self, message: str) -> None:
+        """Log a subtitle with a medium separator."""
+        _log_bordered(self.logger, message, _SEPARATOR_SUBTITLE)
+
+    def section(self, message: str) -> None:
+        """Log a section header with a light separator."""
+        _log_bordered(self.logger, message, _SEPARATOR_SECTION)
+
+    def init_run(self) -> None:
+        """Log the start banner for the current run."""
+        _log_bordered(self.logger, f"Starting script: {self.log_run}", _SEPARATOR_TITLE)
+
+    def close_run(self) -> None:
+        """Log the closing banner with execution duration."""
+        ended_at = datetime.now()
+        exec_hours = (time.time() - self.ts_init) / 3600
+
+        self.logger.info(_SEPARATOR_TITLE)
+        self.logger.info("Execution finished script: %s", self.log_run)
+        self.logger.info("Conclusion at %s", ended_at.strftime("%Y-%m-%d %H:%M"))
+        self.logger.info("Execution time: %.2f hours", exec_hours)
+        self.logger.info(_SEPARATOR_TITLE)
+        self.logger.info("%74sXploreDS", "")
+        self.logger.info(_SEPARATOR_TITLE)
+
+    def log_environment_setup(self) -> None:
+        """
+        Log hardware, OS, Python, and run configuration details.
+
+        Note:
+            Requires ``psutil`` for memory and CPU reporting.
+        """
+        self.logger.info(_SEPARATOR_TITLE)
+        self.logger.info("Environment Setup")
+        self._log_machine_setup()
+        self._log_os_setup()
+        self._log_python_setup()
+        self._log_run_setup()
+        self.logger.info(_SEPARATOR_TITLE)
+
+    def _log_section(self, title: str) -> None:
+        """Log a labeled section with light separators."""
+        _log_bordered(self.logger, title, _SEPARATOR_SECTION)
+
+    def _log_machine_setup(self) -> None:
+        """Log CPU and memory details."""
+        self._log_section("Machine Setup")
+        self.logger.info("Machine: %s", platform.machine())
+        self.logger.info("Processor: %s", platform.processor())
+        self.logger.info("Physical cores: %s", psutil.cpu_count(logical=False))
+        self.logger.info("Total cores: %s", psutil.cpu_count(logical=True))
+        memory_gb = convert_bytes(psutil.virtual_memory().total, "GB")
+        self.logger.info("Physical memory: %.2fGB", memory_gb)
+
+    def _log_os_setup(self) -> None:
+        """Log operating system details."""
+        self._log_section("OS Setup")
+        self.logger.info("OS id: %s", platform.platform())
+        self.logger.info("OS System: %s", platform.system())
+        self.logger.info("OS Node Name: %s", platform.node())
+        self.logger.info("OS Release: %s", platform.release())
+
+    def _log_python_setup(self) -> None:
+        """Log Python interpreter details."""
+        self._log_section("Python Setup")
+        self.logger.info("Python version: %s", sys.version)
+        self.logger.info("Python path: %s", sys.executable)
+        self.logger.info("Python warnings: %s", os.getenv("PYTHON_WARNINGS"))
+
+    def _log_run_setup(self) -> None:
+        """Log paths and identifiers for the current run."""
+        self._log_section("Run Setup")
+        self.logger.info("Root folder: %s", self.project_root)
+        self.logger.info("Run name: %s", self.log_run)
+        self.logger.info("Artifacts folder: %s", self.log_path)
+
+
+def create_logger(project_root: PathLike, script_path: PathLike) -> XploreDSLogging:
+    """
+    Create the run logger for the current script.
+
+    Args:
+        project_root: Root directory of the XploreDS project.
+        script_path: Path to the script file being executed.
+
+    Returns:
+        Configured ``XploreDSLogging`` instance.
+    """
+    return XploreDSLogging(
+        project_root=project_root,
+        script_name=script_path,
+    )

xploreai-0.2.0/src/xploreai/utils/xai_environment.py

@@ -0,0 +1,48 @@
+"""
+Xplore DEV :: Environment Utils Package
+
+Utilities for locating project roots and resolving runtime paths.
+"""
+
+from pathlib import Path
+
+PathLike = str | Path
+
+DEFAULT_PROJECT_MARKER = "pyproject.toml"
+
+
+def resolve_project_root(
+    start: PathLike | None = None,
+    *,
+    marker: str = DEFAULT_PROJECT_MARKER,
+) -> Path:
+    """
+    Locate a project root by walking parent directories for a marker file.
+
+    Args:
+        start: Directory to begin the search. Defaults to the current
+            working directory when ``None``.
+        marker: Filename that identifies the project root. Defaults to
+            ``pyproject.toml``.
+
+    Returns:
+        Absolute path to the directory containing the marker file.
+
+    Raises:
+        RuntimeError: When ``marker`` cannot be found in any parent folder.
+
+    Example:
+        From a cookbook script::
+
+            project_root = resolve_project_root(Path(__file__).resolve().parent)
+    """
+    current = Path(start).resolve() if start is not None else Path.cwd()
+
+    for path in (current, *current.parents):
+        if (path / marker).is_file():
+            return path
+
+    raise RuntimeError(
+        f"Could not find {marker!r} starting from {current}. "
+        "Run the script from within the project repository."
+    )

xploreai-0.2.0/src/xploreai/utils/xai_memory.py

@@ -0,0 +1,39 @@
+"""
+Xplore DS :: Memory Utils Package
+
+Utilities for converting and expressing memory sizes in binary units.
+"""
+
+from typing import Final
+
+BYTES_PER_UNIT: Final[int] = 1024
+BINARY_UNITS: Final[tuple[str, ...]] = ("B", "KB", "MB", "GB", "TB")
+_UNIT_EXPONENT: Final[dict[str, int]] = {
+    unit: exponent for exponent, unit in enumerate(BINARY_UNITS)
+}
+
+
+def convert_bytes(size_bytes: int | float, to_unit: str = "GB") -> float:
+    """
+    Convert a byte count to the requested binary unit (KiB-based).
+
+    Args:
+        size_bytes: Size in bytes.
+        to_unit: Target unit. One of B, KB, MB, GB, or TB (case-insensitive).
+
+    Returns:
+        Size expressed in the requested unit.
+
+    Raises:
+        ValueError: When ``to_unit`` is not supported.
+
+    Example:
+        ``convert_bytes(1073741824, "GB")`` returns ``1.0``.
+    """
+    unit = to_unit.upper()
+    if unit not in _UNIT_EXPONENT:
+        supported = ", ".join(BINARY_UNITS)
+        raise ValueError(f"Invalid unit {to_unit!r}. Use one of: {supported}.")
+
+    exponent = _UNIT_EXPONENT[unit]
+    return float(size_bytes) / (BYTES_PER_UNIT**exponent)