phronesis-framework 0.1.0__tar.gz

phronesis_framework-0.1.0/.commitlintrc.yml

@@ -0,0 +1,10 @@
+extends:
+  - "@commitlint/config-conventional"
+rules:
+  type-enum:
+    - 2
+    - always
+    - [feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert]
+  subject-case: [2, never, [upper-case, pascal-case, start-case]]
+  header-max-length: [2, always, 100]
+  body-max-line-length: [1, always, 120]

phronesis_framework-0.1.0/.github/actions/setup-python-uv/action.yml

@@ -0,0 +1,38 @@
+name: "Setup Python + uv"
+description: "Instala uv, Python y sincroniza dependencias con cache"
+inputs:
+  python-version:
+    description: "Python version"
+    required: false
+    default: "3.11"
+  extras:
+    description: "Extras a instalar (ej: 'dev', 'dev,test')"
+    required: false
+    default: "dev"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Sync dependencies
+      shell: bash
+      run: |
+        flags=""
+        IFS=',' read -ra EXTRAS <<< "${{ inputs.extras }}"
+        for extra in "${EXTRAS[@]}"; do
+          extra="$(echo -n "$extra" | tr -d '[:space:]')"
+          if [ -n "$extra" ]; then
+            flags="$flags --extra $extra"
+          fi
+        done
+        uv sync $flags --frozen

phronesis_framework-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels: ["ci", "dependencies"]
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels: ["dependencies"]

phronesis_framework-0.1.0/.github/workflows/branch-ci.yml

@@ -0,0 +1,67 @@
+name: Branch CI (fast)
+
+on:
+  push:
+    branches:
+      - "feat/**"
+      - "feats/**"
+      - "feature/**"
+      - "fix/**"
+      - "bugfix/**"
+      - "hotfix/**"
+      - "release/**"
+      - "refactor/**"
+      - "perf/**"
+      - "docs/**"
+      - "test/**"
+      - "build/**"
+      - "ci/**"
+      - "chore/**"
+      - "chores/**"
+      - "style/**"
+      - "revert/**"
+
+concurrency:
+  group: branch-ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  format:
+    name: Format (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+      - run: uv run ruff format --check .
+
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+      - run: uv run ruff check .
+
+  types:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+        with:
+          extras: "dev,obs"
+      - run: uv run mypy src
+
+  test:
+    name: Tests (pytest)
+    runs-on: ubuntu-latest
+    needs: [format, lint, types]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+        with:
+          extras: "dev,obs"
+      - run: uv run pytest -x --no-cov

phronesis_framework-0.1.0/.github/workflows/pr-ci.yml

@@ -0,0 +1,139 @@
+name: PR CI
+
+on:
+  pull_request:
+    branches: [develop, main]
+    types: [opened, synchronize, reopened, edited]
+
+concurrency:
+  group: pr-ci-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  # ---------- Format / Quality (siempre) ----------
+  pr-title:
+    name: PR title (conventional commits)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            El subject del PR no debe empezar en may\u00fascula.
+
+  commit-lint:
+    name: Commit messages lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: wagoid/commitlint-github-action@v6
+        with:
+          configFile: .commitlintrc.yml
+
+  format:
+    name: Format (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+      - run: uv run ruff format --check .
+
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+      - run: uv run ruff check --output-format=github .
+
+  types:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+        with:
+          extras: "dev,obs"
+      - run: uv run mypy src
+
+  # ---------- Tests + Coverage ----------
+  test-coverage:
+    name: Tests + Coverage (line >=90, branch >=85)
+    runs-on: ubuntu-latest
+    needs: [format, lint, types]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+        with:
+          extras: "dev,obs"
+      - name: Run pytest with coverage
+        run: |
+          uv run pytest \
+            --cov=src/phronesis \
+            --cov-branch \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --cov-fail-under=90
+      - name: Enforce branch coverage threshold
+        run: |
+          uv run python -c "
+          import xml.etree.ElementTree as ET, sys
+          root = ET.parse('coverage.xml').getroot()
+          branch = float(root.get('branch-rate', 0)) * 100
+          print(f'Branch coverage: {branch:.2f}%')
+          sys.exit(0 if branch >= 85 else 1)
+          "
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ github.sha }}
+          path: coverage.xml
+          retention-days: 7
+
+  # ---------- Security ----------
+  secrets-scan:
+    name: Secret detection (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # ---------- Solo en PR -> main ----------
+  build:
+    name: Build (sdist + wheel)
+    if: github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    needs: [test-coverage, secrets-scan]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 14

phronesis_framework-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write  # PyPI trusted publishing (OIDC)
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-python-uv
+
+      - name: Resolve version from tag
+        id: ver
+        run: |
+          VER="${GITHUB_REF_NAME#v}"
+          echo "version=$VER" >> "$GITHUB_OUTPUT"
+          echo "Releasing $VER"
+
+      - name: Sync pyproject and __version__ with tag
+        run: |
+          VER="${{ steps.ver.outputs.version }}"
+          python - <<PY
+          import pathlib, re
+          ver = "$VER"
+          p = pathlib.Path("pyproject.toml")
+          p.write_text(
+              re.sub(r'^version = ".*"', f'version = "{ver}"', p.read_text(encoding="utf-8"), count=1, flags=re.M),
+              encoding="utf-8",
+          )
+          q = pathlib.Path("src/phronesis/__init__.py")
+          q.write_text(
+              re.sub(r'__version__ = ".*"', f'__version__ = "{ver}"', q.read_text(encoding="utf-8"), count=1),
+              encoding="utf-8",
+          )
+          PY
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/*

phronesis_framework-0.1.0/.github/workflows/scheduled-security.yml

@@ -0,0 +1,30 @@
+name: Scheduled Security
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"  # Lunes 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  deep-secrets:
+    name: Deep secret scan (full history)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  dependency-audit:
+    name: Dependency audit (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+      - run: uv run --with pip-audit pip-audit --disable-pip

phronesis_framework-0.1.0/.github/workflows/sonarcloud.yml

@@ -0,0 +1,42 @@
+name: SonarCloud
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  scan:
+    name: SonarCloud Scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history so SonarCloud can compute blame and new-code metrics.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest \
+            --cov=src/phronesis \
+            --cov-branch \
+            --cov-report=xml
+
+      - name: SonarCloud Scan
+        uses: SonarSource/sonarqube-scan-action@v4
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

phronesis_framework-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Ruff / mypy
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code
+.claude/
+CLAUDE.md

phronesis_framework-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--config-file=pyproject.toml]
+        files: ^src/
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]

phronesis_framework-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

phronesis_framework-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: phronesis-framework
+Version: 0.1.0
+Summary: Phronesis Framework
+Author-email: Eduardo Marrero González <edumarreroglezz@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.27.2
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: obs
+Requires-Dist: opentelemetry-api>=1.27; extra == 'obs'
+Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'obs'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'obs'
+Description-Content-Type: text/markdown
+
+#
+
+<div align="center">
+  <img src="./assets/banners/phronesis.svg" alt="Phronesis Framework" width="60%" />
+</div>
+
+<div align="center">
+
+# Phronesis Framework - Documentation
+
+</div>
+
+<div align="center">
+  Índice raíz de la documentación. Refleja la estructura de <code>src/phronesis/</code>.
+</div>
+
+<div align="center">
+  <a href="https://github.com/phronesis-framework/phronesis">repo</a> ·
+  <a href="../LICENSE">license</a>
+</div>
+
+<div align="center">
+
+[![Status](https://img.shields.io/badge/status-WIP-orange)]()
+[![Python](https://img.shields.io/badge/python-3.11+-blue?logo=python&logoColor=white)]()
+
+</div>
+
+---
+
+<div align="center">
+
+## 🗺️ Map
+
+</div>
+
+| Área | Estado | Documentación |
+|---|---|---|
+| `_internal` - infraestructura compartida | en construcción | [internal/](./internal/index.md) |
+| `tools` - declaración y registro de tools | estable | [tools/](./tools/index.md) |
+| `agents` - `@agent`, runtime, sessions, tool-calling loop | estable | [agents/](./agents/index.md) |
+| `runtime` - orquestación de agentes (19 modos) | estable | [runtime/](./runtime/index.md) |
+| `providers` - adaptadores por proveedor LLM | estable | [providers/](./providers/index.md) |
+| `obs` - observabilidad (spans, metrics, log correlation) | estable | [obs/](./obs/index.md) |
+| `context` - ContextBuilder + Context inyectado a tools | estable | [context/](./context/index.md) |
+| `memory` - working/kv/vector/episodic stores + checkpoints | estable | [memory/](./memory/index.md) |
+| `pipelines` - composición declarativa de Executables nombrados | estable | [pipelines/](./pipelines/index.md) |
+| `mcp` - cliente y servidor Model Context Protocol | estable | [mcp/](./mcp/index.md) |
+| `middleware` - cadena onion sobre `LLMProvider.complete` | estable | [middleware/](./middleware/index.md) |
+| `replay` - record/replay de respuestas LLM en cassettes JSONL | estable | [replay/](./replay/index.md) |
+| `core` - tipos de dominio (`Message`, `ContentBlock`) | estable | [core/](./core/index.md) |
+| `communication` - identidad de sesión (`SessionId`) | estable | [communication/](./communication/index.md) |
+
+<div align="center">
+
+## 📐 Decisiones y planes
+
+</div>

phronesis_framework-0.1.0/deploy/observability/.gitignore

@@ -0,0 +1,4 @@
+volumes/
+data/
+*.log
+.env

phronesis_framework-0.1.0/deploy/observability/README.md

@@ -0,0 +1,78 @@
+# Phronesis - Observability stack
+
+Stack OTLP estandar para consumir lo que `phronesis.obs` emite: traces (Tempo), metricas (Prometheus) y logs (Loki), visualizados en Grafana con dashboards pre-construidos.
+
+## Perfiles
+
+### Dev (all-in-one)
+
+Imagen unica `grafana/otel-lgtm` para iteracion local rapida. Sin persistencia.
+
+```bash
+cd deploy/observability
+docker compose -f docker-compose.dev.yml up -d
+```
+
+Servicios expuestos:
+
+- Grafana UI: http://localhost:3000 (sin auth)
+- OTLP HTTP: http://localhost:4318
+- OTLP gRPC: localhost:4317
+- Prometheus: http://localhost:9090
+
+### Prod (stack separado)
+
+Containers separados con volumenes persistentes, healthchecks y networks aisladas.
+
+```bash
+cd deploy/observability
+export GRAFANA_ADMIN_PASSWORD=<secret>
+docker compose -f docker-compose.prod.yml up -d
+```
+
+Servicios:
+
+- `otel-collector` - recibe OTLP HTTP/gRPC y multiplexa a backends
+- `tempo` - traces (filesystem block storage)
+- `loki` - logs (boltdb-shipper + filesystem)
+- `prometheus` - metricas (OTLP write receiver activado)
+- `grafana` - UI + datasources + dashboards auto-provisionados
+
+## Configurar phronesis
+
+```python
+from phronesis.obs import configure_obs
+
+configure_obs(
+    exporter="otlp",
+    endpoint="http://localhost:4318",
+    service_name="my-app",
+)
+```
+
+## Validar end-to-end
+
+```bash
+uv run python deploy/observability/scripts/obs_demo.py
+```
+
+Genera trafico sintetico (agent runs, tool invocations, provider requests) e imprime el `trace_id` raiz y la URL de Grafana.
+
+## Dashboards
+
+Siete dashboards pre-construidos en `grafana/dashboards/`:
+
+- `phronesis-overview` - health agregado
+- `phronesis-providers` - LLM perf/cost
+- `phronesis-tools` - tool performance
+- `phronesis-agents` - agent execution
+- `phronesis-pipelines` - pipeline orchestration
+- `phronesis-retries` - resilience
+- `phronesis-traces-explorer` - navegacion Tempo
+
+Detalle en `docs/obs/dashboards.md`.
+
+## Documentacion
+
+- `docs/obs/stack.md` - arquitectura, troubleshooting, retention
+- `docs/obs/dashboards.md` - catalogo panel-a-panel

phronesis_framework-0.1.0/deploy/observability/docker-compose.dev.yml

@@ -0,0 +1,28 @@
+name: phronesis-obs-dev
+
+services:
+  lgtm:
+    image: grafana/otel-lgtm:0.11.12
+    container_name: phronesis-lgtm
+    ports:
+      - "3000:3000"
+      - "4317:4317"
+      - "4318:4318"
+      - "9090:9090"
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_AUTH_DISABLE_LOGIN_FORM=true
+    volumes:
+      # Dev datasources point to localhost (otel-lgtm is all-in-one).
+      # Mount the full directory so the built-in grafana-datasources.yaml
+      # is replaced; mounting a single file would leave conflicting
+      # built-in datasources and crash Grafana provisioning.
+      - ./grafana/provisioning/datasources-dev:/otel-lgtm/grafana/conf/provisioning/datasources:ro
+      - ./grafana/provisioning/dashboards:/otel-lgtm/grafana/conf/provisioning/dashboards:ro
+      - ./grafana/dashboards:/var/lib/grafana/dashboards:ro
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 6