codex-core 0.1.0__tar.gz → 0.2.0__tar.gz

{codex_core-0.1.0 → codex_core-0.2.0}/.github/workflows/ci.yml

@@ -36,15 +36,18 @@ jobs:
         run: pip install mypy && mypy src/codex_core/
 
   unit-tests:
-    name: Unit Tests
+    name: Unit Tests (Python ${{ matrix.python-version }})
     needs: quality-gate
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.12
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: 'pip'
 
       - name: Install All Dependencies

codex_core-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Deploy Docs
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version alias to deploy (e.g. 0.x, 1.x)'
+        required: true
+      alias:
+        description: 'Alias (latest, stable, or leave empty)'
+        required: false
+        default: 'latest'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build & Deploy Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Resolve version alias (tag push)
+        if: github.event_name == 'push'
+        id: version
+        run: |
+          TAG="${GITHUB_REF_NAME}"           # e.g. v1.2.3
+          MAJOR=$(echo "$TAG" | sed 's/^v//' | cut -d. -f1)
+          MINOR=$(echo "$TAG" | sed 's/^v//' | cut -d. -f2)
+          echo "alias=${MAJOR}.x" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy versioned docs (tag push)
+        if: github.event_name == 'push'
+        run: |
+          mike deploy --push --update-aliases "${{ steps.version.outputs.alias }}" latest
+          mike set-default --push latest
+
+      - name: Deploy versioned docs (manual)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if [ -n "${{ inputs.alias }}" ]; then
+            mike deploy --push --update-aliases "${{ inputs.version }}" "${{ inputs.alias }}"
+          else
+            mike deploy --push "${{ inputs.version }}"
+          fi
+          mike set-default --push latest

{codex_core-0.1.0 → codex_core-0.2.0}/.gitignore

@@ -194,6 +194,9 @@ gen/
 .cursorignore
 .cursorindexingignore
 
+# Claude Code
+.claude/
+
 # Marimo
 marimo/_static/
 marimo/_lsp/

codex_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-02-13
+
+### Added
+- **Python 3.13 Support**: Added official support for Python 3.13 in `pyproject.toml` classifiers.
+- **Comprehensive Unit Tests**:
+  - New tests for `core/exceptions.py` covering base exception functionality.
+  - New tests for `common/log_context.py` covering `TaskLogContext` logging methods.
+  - New tests for `common/loguru_setup.py` covering `InterceptHandler`, `setup_universal_logging`, and `setup_logging` with and without `loguru` installed.
+
+### Changed
+- **Documentation Structure**:
+  - Renamed top-level language directories from `en_EN/` to `en/` and `ru_RU/` to `ru/`.
+  - Moved `api/` documentation into `en/api/` for better language-specific grouping.
+  - Renamed `guide/` directories to `tasks/` in both `en/` and `ru/` to align with `DocArchitect:StructurePolicy` for user-oriented guides.
+  - Updated `mkdocs.yml` navigation and all internal Markdown links to reflect the new documentation structure.
+  - Updated root `README.md` to strictly follow `DocArchitect:StructurePolicy` (Layer 5 - Root Landing), including a detailed `Modules` table (with `dev` module) and a comprehensive `Part of the Codex ecosystem` section.
+- **Test Coverage Configuration**:
+  - Configured `pytest-cov` in `pyproject.toml` to include `addopts`, `[tool.coverage.run]`, and `[tool.coverage.report]` sections.
+  - Excluded `src/codex_core/dev/*` from coverage reports as these are internal development tools.
+  - Added `exclude_lines` for `TYPE_CHECKING` and `ImportError` to achieve accurate coverage metrics.
+- **Test Isolation**: Implemented `autouse` fixture `reset_pii_registry` in `tests/conftest.py` to ensure `PIIRegistry` global state is reset between tests, guaranteeing test isolation.
+- **Test Markers**: Created `tests/unit/conftest.py` and `tests/integration/conftest.py` to automatically apply `pytest.mark.unit` and `pytest.mark.integration` markers to tests within their respective directories.
+
+### Fixed
+- **Mypy Errors**: Resolved missing type parameters for generic types in `src/codex_core/dev/static_compiler/compiler.py` and `src/codex_core/dev/static_compiler/css.py`.
+- **Ruff Errors**: Resolved `SIM118` (Use `key in dict` instead of `key in dict.keys()`) in `src/codex_core/core/pii.py`.
+- **Ruff Errors**: Resolved `SIM117` (Use a single `with` statement with multiple contexts) in `tests/unit/common/test_loguru_setup.py`.
+- **Test Coverage Gaps**:
+  - Covered `PIIRegistry` initialization logic and recursive list masking in `tests/unit/core/test_pii.py`.
+  - Covered falsy input handling in `transliterate` and `sanitize_for_sms` functions in `tests/unit/common/test_text.py`.
+
+## [0.1.1] - 2025-02-12
+
+### Added
+- **Declarative PII Registry**: Introduced `PIIRegistry` class in `pii.py` for explicit sensitive field name tracking, complementing the heuristic keyword-based matching.
+- **Enhanced Documentation**:
+  - Comprehensive Google-style docstrings added to all core modules: `log_context`, `loguru_setup`, `phone`, `text`, `base_dto`, `exceptions`, and `settings/base`.
+  - Added localized (EN/RU) documentation links and PyPI/License badges to `README.md`.
+- **Dependency Management**: Added `loguru` as an explicit optional dependency in `pyproject.toml`.
+
+### Changed
+- **PII Masking Logic**: Refined `is_pii_field` and `mask_value` to prioritize explicit registry matches over heuristic keyword search.
+- **Project Configuration**: Updated `.gitignore` to include `.claude/` for modern AI tool support.
+
+## [0.1.0] - 2024-05-24
+
+### Added
+- **Project Structure**: Initial setup of the core library as a standalone project.
+- **Advanced PII Protection**:
+  - Implementation of `BaseDTO` with automated, recursive PII masking in `repr` and `str`.
+  - Keyword-based sensitive data detection (phone, email, name, address, notes).
+- **International Utilities**:
+  - `normalize_phone`: Robust normalization supporting `+`, `00`, and local German `0` formats.
+  - `normalize_name`: Smart capitalization preserving hyphens and spaces.
+  - `TaskLogContext`: Structured logging adapter for background tasks and operations.
+- **Base Settings**: `BaseCommonSettings` with standardized Redis URL generation and environment-aware flags.
+- **Documentation**:
+  - New Domain-Driven documentation standard (Architecture + API Reference).
+  - Bilingual support (EN/RU) with structural mirroring.
+- **Testing**:
+  - Comprehensive unit test suite (27 scenarios) covering Core, Common, and Settings.
+  - Integration test for environment variable loading.
+
+### Changed
+- **Package Rename**: Renamed package from `codex_tools` to `codex_core` for better clarity.
+- **Dependency Optimization**:
+  - `loguru` removed from mandatory dependencies.
+  - `loguru_setup` updated with safe imports and clear installation instructions.
+- **CI/CD**:
+  - Switched GitHub Actions to use Node.js 24 (via `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24`).
+  - Updated Mypy paths to reflect the new package structure.
+
+### Security
+- Integrated `bandit`, `pip-audit`, and `detect-secrets` into the development lifecycle.
+- Standardized `quote_plus` usage for all infrastructure connection strings.

codex_core-0.2.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: codex-core
+Version: 0.2.0
+Summary: Core utilities, schemas and settings for Codex WaaS toolkit
+Project-URL: Homepage, https://github.com/codexdlc/codex-core
+Project-URL: Documentation, https://codexdlc.github.io/codex-core/
+Project-URL: Repository, https://github.com/codexdlc/codex-core
+Project-URL: Changelog, https://github.com/codexdlc/codex-core/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/codexdlc/codex-core/issues
+Author: CodexDLC
+License: Apache-2.0
+Keywords: core,pydantic,toolkit,waas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: detect-secrets>=1.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mike>=2.0; extra == 'docs'
+Requires-Dist: mkdocs-include-markdown-plugin; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: loguru
+Requires-Dist: loguru>=0.7.0; extra == 'loguru'
+Description-Content-Type: text/markdown
+
+<!-- Type: LANDING -->
+# codex-core
+
+[![PyPI](https://img.shields.io/pypi/v/codex-core)](https://pypi.org/project/codex-core/)
+[![Python](https://img.shields.io/pypi/pyversions/codex-core)](https://pypi.org/project/codex-core/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/codexdlc/codex-core/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-codexdlc.github.io-blue)](https://codexdlc.github.io/codex-core/)
+
+Core utilities, immutable DTOs, and environment-driven settings for the Codex WaaS toolkit.
+Provides the foundational building blocks and PII masking used by all other Codex components.
+
+---
+
+## Install
+
+```bash
+# Core only
+pip install codex-core
+
+# With Loguru support for advanced structured logging
+pip install "codex-core[loguru]"
+```
+
+## Quick Start
+
+```python
+from codex_core.core.base_dto import BaseDTO
+
+# 1. Define an immutable, PII-aware data transfer object
+class UserDTO(BaseDTO):
+    id: int
+    email: str         # Automatically masked in logs
+    phone_number: str  # Automatically masked in logs
+
+user = UserDTO(id=42, email="user@example.com", phone_number="+491511234567")
+
+# 2. Safely log the DTO without leaking personal data
+print(user)
+# Output: UserDTO(id=42, email='***', phone_number='***')
+```
+
+## Modules
+
+| Module | Extra | Description |
+| :--- | :--- | :--- |
+| `codex_core.core` | - | Immutable `BaseDTO` and automated `PIIRegistry` for GDPR-safe logging. |
+| `codex_core.common` | `[loguru]` | Phone/name normalization and structured logging adapters (`TaskLogContext`). |
+| `codex_core.settings` | - | Environment-driven configuration via `BaseCommonSettings` (Pydantic Settings). |
+| `codex_core.dev` | `[dev]` | Internal developer tools (`BaseCheckRunner`, `StaticCompiler`, `ProjectTreeGenerator`). |
+
+## Documentation
+
+Full docs with architecture, API reference, and data flow diagrams:
+
+**[https://codexdlc.github.io/codex-core/](https://codexdlc.github.io/codex-core/)**
+
+## Part of the Codex ecosystem
+
+- **[codex-core](https://github.com/codexdlc/codex-core)**: Foundational utilities and DTOs.
+- **[codex-platform](https://github.com/codexdlc/codex-platform)**: Core platform components and HTTP APIs.
+- **[codex-bot](https://github.com/codexdlc/codex-bot)**: Telegram AI-agent infrastructure.
+- **[codex-services](https://github.com/codexdlc/codex-services)**: Business logic engines (Booking, CRM).
+- **[codex-ai](https://github.com/codexdlc/codex-ai)**: LLM abstraction layer.

codex_core-0.2.0/README.md

@@ -0,0 +1,63 @@
+<!-- Type: LANDING -->
+# codex-core
+
+[![PyPI](https://img.shields.io/pypi/v/codex-core)](https://pypi.org/project/codex-core/)
+[![Python](https://img.shields.io/pypi/pyversions/codex-core)](https://pypi.org/project/codex-core/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/codexdlc/codex-core/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-codexdlc.github.io-blue)](https://codexdlc.github.io/codex-core/)
+
+Core utilities, immutable DTOs, and environment-driven settings for the Codex WaaS toolkit.
+Provides the foundational building blocks and PII masking used by all other Codex components.
+
+---
+
+## Install
+
+```bash
+# Core only
+pip install codex-core
+
+# With Loguru support for advanced structured logging
+pip install "codex-core[loguru]"
+```
+
+## Quick Start
+
+```python
+from codex_core.core.base_dto import BaseDTO
+
+# 1. Define an immutable, PII-aware data transfer object
+class UserDTO(BaseDTO):
+    id: int
+    email: str         # Automatically masked in logs
+    phone_number: str  # Automatically masked in logs
+
+user = UserDTO(id=42, email="user@example.com", phone_number="+491511234567")
+
+# 2. Safely log the DTO without leaking personal data
+print(user)
+# Output: UserDTO(id=42, email='***', phone_number='***')
+```
+
+## Modules
+
+| Module | Extra | Description |
+| :--- | :--- | :--- |
+| `codex_core.core` | - | Immutable `BaseDTO` and automated `PIIRegistry` for GDPR-safe logging. |
+| `codex_core.common` | `[loguru]` | Phone/name normalization and structured logging adapters (`TaskLogContext`). |
+| `codex_core.settings` | - | Environment-driven configuration via `BaseCommonSettings` (Pydantic Settings). |
+| `codex_core.dev` | `[dev]` | Internal developer tools (`BaseCheckRunner`, `StaticCompiler`, `ProjectTreeGenerator`). |
+
+## Documentation
+
+Full docs with architecture, API reference, and data flow diagrams:
+
+**[https://codexdlc.github.io/codex-core/](https://codexdlc.github.io/codex-core/)**
+
+## Part of the Codex ecosystem
+
+- **[codex-core](https://github.com/codexdlc/codex-core)**: Foundational utilities and DTOs.
+- **[codex-platform](https://github.com/codexdlc/codex-platform)**: Core platform components and HTTP APIs.
+- **[codex-bot](https://github.com/codexdlc/codex-bot)**: Telegram AI-agent infrastructure.
+- **[codex-services](https://github.com/codexdlc/codex-services)**: Business logic engines (Booking, CRM).
+- **[codex-ai](https://github.com/codexdlc/codex-ai)**: LLM abstraction layer.

{codex_core-0.1.0/docs/en_EN → codex_core-0.2.0/docs/en}/README.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [🧭 Guide (EN)](README.md) | [⚙️ API Reference](../api/index.md)
+[🏠 Home](../index.md) | [🧭 Guide (EN)](README.md) | [⚙️ API Reference](api/index.md)
 
 # Guide: Overview (EN)
 
@@ -6,7 +6,7 @@ Welcome to the **codex-core** guide! This library serves as the shared foundatio
 
 ## Documentation Sections
 
-### 1. [Getting Started](guide/getting_started.md)
+### 1. [Getting Started](tasks/getting_started.md)
 How to install and integrate `codex-core` into your project.
 
 ### 2. [🛡️ Architecture & Platform](architecture/README.md)
@@ -19,5 +19,5 @@ Detailed breakdown of the core platform components:
 ### 3. [🗺 Evolution](../evolution/roadmap.md)
 Our core purpose and development philosophy.
 
-### 4. [⚙️ API Reference](../api/index.md)
+### 4. [⚙️ API Reference](api/index.md)
 Technical details for developers.

{codex_core-0.1.0/docs → codex_core-0.2.0/docs/en}/api/common.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [⚙️ API Reference](index.md) | [🛠️ Common API](common.md)
+[🏠 Home](../../index.md) | [⚙️ API Reference](index.md) | [🛠️ Common API](common.md)
 
 # 🛠️ Common API (Utilities)
 

{codex_core-0.1.0/docs → codex_core-0.2.0/docs/en}/api/core.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [⚙️ API Reference](index.md) | [🛡️ Core API](core.md)
+[🏠 Home](../../index.md) | [⚙️ API Reference](index.md) | [🛡️ Core API](core.md)
 
 # 🛡️ Core API (DTO & PII)
 

codex_core-0.2.0/docs/en/api/dev.md

@@ -0,0 +1,29 @@
+# Dev Tools — API Reference
+
+## BaseCheckRunner
+
+::: codex_core.dev.check_runner.BaseCheckRunner
+
+---
+
+## StaticCompiler
+
+::: codex_core.dev.static_compiler.compiler.StaticCompiler
+
+---
+
+## CSSCompiler
+
+::: codex_core.dev.static_compiler.css.CSSCompiler
+
+---
+
+## JSCompiler
+
+::: codex_core.dev.static_compiler.js.JSCompiler
+
+---
+
+## ProjectTreeGenerator
+
+::: codex_core.dev.project_tree.ProjectTreeGenerator

{codex_core-0.1.0/docs → codex_core-0.2.0/docs/en}/api/index.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [🧭 Guide (EN)](../en_EN/README.md) | [⚙️ API Reference](index.md)
+[🏠 Home](../../index.md) | [🧭 Guide (EN)](../README.md) | [⚙️ API Reference](index.md)
 
 # API Reference Overview
 
@@ -9,6 +9,7 @@ Welcome to the **codex-core** API Reference! This section provides detailed info
 - **[🛡️ Core (DTO & PII)](core.md)**: Base data models and PII protection utilities.
 - **[🛠️ Common (Utilities)](common.md)**: Phone, text, and logging helpers.
 - **[⚙️ Settings (Config)](settings.md)**: Base configuration patterns.
+- **[🛠️ Dev Tools](dev.md)**: Internal developer tools.
 
 ## Technical Details
 

{codex_core-0.1.0/docs → codex_core-0.2.0/docs/en}/api/settings.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [⚙️ API Reference](index.md) | [⚙️ Settings API](settings.md)
+[🏠 Home](../../index.md) | [⚙️ API Reference](index.md) | [⚙️ Settings API](settings.md)
 
 # ⚙️ Settings API (Base Configuration)
 

{codex_core-0.1.0/docs/en_EN → codex_core-0.2.0/docs/en}/architecture/README.md

@@ -1,4 +1,4 @@
-[🏠 Home](../../index.md) | [🧭 Guide (EN)](../README.md) | [🛡️ Architecture](../../api/index.md)
+[🏠 Home](../../index.md) | [🧭 Guide (EN)](../README.md) | [🛡️ Architecture](../api/index.md)
 
 # 🛡️ Architecture & Platform Overview (EN)
 

{codex_core-0.1.0/docs/en_EN → codex_core-0.2.0/docs/en}/architecture/platform/common.md

@@ -1,4 +1,4 @@
-[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛠️ Common API](../../../api/common.md)
+[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛠️ Common API](../../api/common.md)
 
 # 🛠️ Common: Utilities (Architecture)
 

{codex_core-0.1.0/docs/en_EN → codex_core-0.2.0/docs/en}/architecture/platform/core.md

@@ -1,4 +1,4 @@
-[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛡️ Core API](../../../api/core.md)
+[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛡️ Core API](../../api/core.md)
 
 # 🛡️ Core: PII & DTO (Architecture)