miner-harness 0.1.0__tar.gz

miner_harness-0.1.0/.claude/settings.local.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m ruff check src/miner_harness/self_improvement/ tests/self_improvement/)",
+      "Bash(where ruff *)",
+      "Bash(ruff --version)",
+      "Bash(python -m pytest tests/self_improvement/ -v)",
+      "Bash(python -m pip show pytest)",
+      "Bash(pip show *)",
+      "Bash(ls .venv/Scripts/)",
+      "Bash(ls venv/Scripts/)",
+      "Bash(ls .venv/bin/)",
+      "PowerShell(Get-Command pytest -ErrorAction SilentlyContinue)",
+      "PowerShell(Get-Command ruff -ErrorAction SilentlyContinue)",
+      "PowerShell(Get-Command python -ErrorAction SilentlyContinue)",
+      "PowerShell($env:PATH -split \";\" | Where-Object { $_ -match \"python|pip|uv|conda\" })",
+      "Bash(uv run *)",
+      "Bash(uv add *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git push *)",
+      "Bash(gh pr create --title 'feat: Phase 11 — Self-Improvement' --body ' *)",
+      "Bash(gh pr *)",
+      "Bash(gh run *)",
+      "Bash(git fetch *)",
+      "Bash(git checkout *)",
+      "Bash(git pull *)",
+      "Bash(git merge *)",
+      "Bash(gh release *)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(git tag *)",
+      "Bash(uv build *)"
+    ]
+  }
+}

miner_harness-0.1.0/.git

@@ -0,0 +1 @@
+gitdir: C:/Users/victo/Documents/Claude/Projects/Testing rules/miner-harness/.git/worktrees/hopeful-hypatia-9aec15

miner_harness-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,32 @@
+## Descricao
+
+<!-- Descreva brevemente o que este PR faz -->
+
+## Tipo de Mudanca
+
+- [ ] `feat:` Nova funcionalidade
+- [ ] `fix:` Correcao de bug
+- [ ] `refactor:` Refatoracao sem mudanca funcional
+- [ ] `test:` Adicao/correcao de testes
+- [ ] `docs:` Documentacao
+- [ ] `ci:` Mudancas de CI/CD
+- [ ] `chore:` Manutencao
+
+## Checklist
+
+- [ ] Testes passando (`pytest tests/ -v`)
+- [ ] Lint limpo (`ruff check src/ tests/`)
+- [ ] Mypy limpo (`mypy src/ --strict`)
+- [ ] Coverage >= 80%
+- [ ] Conventional Commits no titulo do PR
+
+## Rastreabilidade
+
+<!-- Vincule a RFC, ADR ou issue relevante -->
+- RFC: 
+- ADR: 
+- Issue: 
+
+## Notas para Revisao
+
+<!-- Algo que o revisor deve saber? -->

miner_harness-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install ruff
+        run: pip install ruff
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Format check
+        run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Type check
+        run: mypy src/ --strict
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests with coverage
+        run: pytest tests/ -v --tb=short --cov --cov-report=term-missing --cov-report=xml
+      - name: Check coverage threshold
+        run: coverage report --fail-under=80
+
+  security:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Security scan (bandit)
+        run: bandit -r src/ -ll --format json --output bandit-report.json || true
+      - name: Check bandit results
+        run: bandit -r src/ -ll
+      - name: Dependency audit
+        run: pip-audit --skip-editable
+
+  # Gate job — all checks must pass before merge is allowed
+  gate:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test, security]
+    if: always()
+    steps:
+      - name: Check all jobs passed
+        run: |
+          if [ "${{ needs.lint.result }}" != "success" ] || \
+             [ "${{ needs.typecheck.result }}" != "success" ] || \
+             [ "${{ needs.test.result }}" != "success" ] || \
+             [ "${{ needs.security.result }}" != "success" ]; then
+            echo "One or more required jobs failed:"
+            echo "  lint: ${{ needs.lint.result }}"
+            echo "  typecheck: ${{ needs.typecheck.result }}"
+            echo "  test: ${{ needs.test.result }}"
+            echo "  security: ${{ needs.security.result }}"
+            exit 1
+          fi
+          echo "All gates passed — merge allowed."

miner_harness-0.1.0/.github/workflows/e2e.yml

@@ -0,0 +1,62 @@
+name: E2E Tests
+
+# Disparado manualmente ou em schedule semanal (domingo 06:00 UTC)
+# Requer: runner com acesso à internet (GeoSGB) e Ollama instalado
+on:
+  workflow_dispatch:
+    inputs:
+      ollama_model:
+        description: "Modelo Ollama a usar"
+        default: "qwen3:8b-q4_K_M"
+        required: false
+  schedule:
+    - cron: "0 6 * * 0"  # domingo 06:00 UTC
+
+jobs:
+  e2e:
+    name: E2E (GeoSGB + Ollama)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Install Ollama
+        run: |
+          curl -fsSL https://ollama.com/install.sh | sh
+          ollama serve &
+          sleep 5
+
+      - name: Pull model
+        run: |
+          MODEL="${{ github.event.inputs.ollama_model || 'qwen3:8b-q4_K_M' }}"
+          ollama pull "$MODEL"
+        env:
+          OLLAMA_HOST: http://localhost:11434
+
+      - name: Run e2e tests
+        run: uv run pytest tests/e2e/ -v --tb=short --timeout=300
+        env:
+          MINER_E2E: "1"
+          MINER_OLLAMA_URL: "http://localhost:11434"
+          MINER_OLLAMA_MODEL: "${{ github.event.inputs.ollama_model || 'qwen3:8b-q4_K_M' }}"
+
+      - name: Upload e2e report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-report
+          path: |
+            .pytest_cache/
+          retention-days: 7

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

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Type check
+        run: mypy src/ --strict
+      - name: Run tests
+        run: pytest tests/ -v --tb=short --cov --cov-report=term-missing
+      - name: Coverage threshold
+        run: coverage report --fail-under=80
+      - name: Security scan
+        run: bandit -r src/ -ll
+
+  release:
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Generate changelog
+        id: changelog
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -z "$PREV_TAG" ]; then
+            CHANGES=$(git log --pretty=format:"- %s (%h)" HEAD)
+          else
+            CHANGES=$(git log --pretty=format:"- %s (%h)" ${PREV_TAG}..HEAD)
+          fi
+          echo "changes<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: |
+            ## Changes
+
+            ${{ steps.changelog.outputs.changes }}
+          generate_release_notes: true

miner_harness-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Data (large files)
+data/
+*.tif
+*.tiff
+*.shp
+*.dbf
+*.shx
+*.prj
+
+# Models
+models/
+*.gguf
+*.bin
+
+# Environment
+.env
+.env.local

miner_harness-0.1.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## [0.1.0] — 2026-05-17
+
+Primeira release — todas as 11 fases do ASO v3 completas.
+
+### Adicionado
+
+**Core**
+- `core/types.py` — modelos Pydantic para todos os domínios geológicos (OcorrenciaMineral, DadoGravimetrico, AmostraGeoquimica, DatacaoGeocronologica, UnidadeLitoestratigrafica, ProjetoAerogeofisico, ProspectionReport)
+- `core/config.py` — configuração hierárquica (MinerHarnessConfig, StorageConfig, GeoSGBConfig, OrchestratorConfig)
+- `core/exceptions.py` — hierarquia de exceções tipadas
+
+**Conectores**
+- `connectors/geosgb/` — connector completo para API GeoSGB: MapServer/identify (grid + dedup) + FeatureServer/query com paginação, rate limiting, alias mapping
+- `connectors/ollama/` — cliente async httpx para Ollama: chat, embeddings, list_models, health
+
+**Orquestrador**
+- `orchestrator/orchestrator.py` — pipeline principal: connector → cache → context → agentes → report
+- `orchestrator/report_validator.py` — validação e reparo automático de relatórios
+- `orchestrator/context_builder.py` — construção de contexto para agentes
+
+**Agentes**
+- `agents/` — 5 agentes especialistas: geólogo estrutural, geofísico, geoquímico, sensoriamento remoto, avaliador
+- `agents/base.py` — classe base com retry e logging estruturado
+
+**Cache**
+- `cache/manager.py` — CacheManager com TTL configurável
+- `cache/sqlite_store.py` — persistência SQLite
+
+**Índice**
+- `index/document_store.py` — índice vetorial via sqlite-vec
+- `index/search_engine.py` — busca semântica
+
+**Observabilidade**
+- `observability/health.py` — health checks async (disco, Ollama, cache, índice)
+- `observability/metrics.py` — MetricsCollector com structlog
+- `observability/logging_config.py` — configuração de logging estruturado
+
+**RCA**
+- `rca/classifier.py` — classificação automática de falhas
+- `rca/diagnostics.py` — diagnóstico estruturado
+- `rca/reporter.py` — geração de relatórios RCA em JSON
+- `rca/retry.py` — retry com backoff exponencial
+
+**Self-Improvement**
+- `self_improvement/profiler.py` — profiling de pipeline e identificação de gargalos
+- `self_improvement/tuner.py` — geração de recomendações de tuning
+- `self_improvement/rca_learner.py` — aprendizado a partir de histórico de RCA
+- `self_improvement/feedback_loop.py` — ciclo Profile → Tune → Apply → Learn
+
+**Wizard**
+- `wizard/checks.py` — verificações puras de pré-requisitos (Python, disco, Ollama, MINER_HOME)
+- `wizard/installer.py` — criação de MINER_HOME, config.json, env_hint.sh
+- `wizard/runner.py` — UI Rich com injeção de Console para testabilidade
+
+**CLI**
+- `miner-harness analyze` — pipeline completo de análise
+- `miner-harness validate` — validação de relatório JSON
+- `miner-harness install` — wizard de instalação (interativo e --non-interactive)
+- `miner-harness health` — health checks do sistema
+- `miner-harness cache stats/clear` — gestão do cache
+
+**Testes**
+- 447 testes unitários e de integração (92% cobertura)
+- 17 testes e2e opt-in (`MINER_E2E=1`) contra GeoSGB real e Ollama local
+
+**CI/CD**
+- GitHub Actions: lint (ruff), typecheck (mypy), test (3.11 + 3.12), security (bandit + pip-audit), gate
+- Workflow e2e separado (manual + schedule semanal)

miner_harness-0.1.0/CLAUDE.md

@@ -0,0 +1,122 @@
+# miner-harness — CLAUDE.md
+
+## Identidade do Projeto
+
+**miner-harness** é um sistema de prospecção mineral inteligente que utiliza agentes especialistas em geologia e geofísica para analisar dados da base GeoSGB. O sistema roda localmente, com LLMs embarcados, e disponibiliza um wizard de instalação para download.
+
+- **Repositório**: https://github.com/VictorAMM/miner-harness
+- **Metodologia**: Agentic SDLC Operating System v3 (ASO v3)
+- **Documentação ASO**: `../entrai-docs/`
+
+## Persona Principal
+
+**Dr. Augusto Valen** — Geólogo exploracionista e geofísico de elite (25+ anos). Define o tom técnico e o framework analítico dos agentes. Ver `docs/personas/dr-augusto-valen.md`.
+
+## Princípios Inegociáveis (ASO v3)
+
+1. **Contexto e segurança antes de velocidade** — nunca pular etapas de discovery
+2. **Decision-by-evidence** — proibido decisões por "vibe"; toda decisão com rationale explícito
+3. **Secure-by-Design** — segurança desde a Fase 0
+4. **Policy-as-Code** — bloquear avanço em caso de violação
+5. **Evaluator-Optimizer** — toda saída crítica passa por avaliação
+6. **Memória persistente e temporal** — semântica, episódica e procedural
+
+## Stack e Arquitetura
+
+### Decisão de Stack (Discovery-First)
+- **Python 3** — core do sistema: agentes, análise geoespacial, ML, integração com LLMs locais
+- **LLMs embarcados** — modelos rodando localmente (ollama/llama.cpp ou similar)
+- **Execução local** — aplicação instala e roda na máquina do usuário
+- **Wizard de instalação** — installer para download com setup guiado
+
+### Dependências esperadas
+- GeoSGB como fonte de dados principal
+- Bibliotecas geocientíficas (geopandas, rasterio, shapely, etc.)
+- Framework de agentes com LLM local
+- Interface de usuário para o wizard
+
+## Fases do Projeto (ASO v3)
+
+O desenvolvimento segue as fases 0→11 do Agentic SDLC OS:
+
+```
+Fase 0  — Fundação e Governança ✅ CONCLUÍDA (2026-05-11)
+Fase 1  — Discovery e Pesquisa Autônoma ✅ CONCLUÍDA (2026-05-11)
+Fase 2  — PRD Executável ✅ CONCLUÍDA (2026-05-11)
+Fase 3  — Technical Design e RFC Swarm ✅ CONCLUÍDA (2026-05-12)
+Fase 4  — Incepção de Infra ✅ CONCLUÍDA (2026-05-12)
+Fase 5  — Implementação ✅ CONCLUÍDA (2026-05-15)
+Fase 6  — Validation Harness ✅ CONCLUÍDA (2026-05-16)
+Fase 7  — Testing Swarm ✅ CONCLUÍDA (2026-05-16)
+Fase 8  — Governed CI/CD ✅ CONCLUÍDA (2026-05-16)
+Fase 9  — Observabilidade ✅ CONCLUÍDA (2026-05-16)
+Fase 10 — RCA Autônomo ✅ CONCLUÍDA (2026-05-17)
+Fase 11 — Self-Improvement ✅ CONCLUÍDA (2026-05-17)
+Wizard  — Instalação Guiada ✅ CONCLUÍDA (2026-05-17)
+```
+
+**Status**: Todas as fases concluídas. Próximo entregável: testes e2e com GeoSGB real + Ollama local.
+
+## Grafo de Rastreabilidade
+
+```
+Feature ↔ PRD ↔ RFC ↔ ADR ↔ Commit ↔ Deploy ↔ Incidente ↔ RCA
+```
+
+## Estrutura do Projeto
+
+```
+miner-harness/
+├── CLAUDE.md              # Este arquivo
+├── docs/
+│   ├── prd/               # Product Requirements Documents
+│   ├── rfc/               # Request for Comments (design técnico)
+│   ├── adr/               # Architecture Decision Records
+│   ├── rca/               # Root Cause Analysis
+│   ├── architecture/      # Diagramas e decisões de arquitetura
+│   └── personas/          # Personas dos agentes
+├── src/                   # Código-fonte
+├── tests/                 # Testes
+├── scripts/               # Scripts de automação e instalação
+├── infra/                 # Configuração de infraestrutura
+└── .github/workflows/     # GitHub Actions CI/CD
+```
+
+## Convenções de Código
+
+- **Linguagem principal**: Python 3.11+
+- **Formatação**: ruff (lint + format)
+- **Tipos**: type hints obrigatórios em funções públicas
+- **Testes**: pytest
+- **Commits**: Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
+- **Branches**: `main` (prod), `develop` (integração), `feature/*`, `fix/*`
+
+## Templates de Artefatos
+
+Usar os templates definidos em `../entrai-docs/docs/agentic-os/templates/README.md`:
+- **PRD** → `docs/prd/`
+- **RFC** → `docs/rfc/`
+- **ADR** → `docs/adr/` (com `valid_from`, `valid_until`, `review_trigger`)
+- **RCA** → `docs/rca/`
+
+## Gates de Qualidade
+
+Antes de avançar qualquer fase:
+- [ ] Checklist de segurança OWASP
+- [ ] Validação por Evaluator-Optimizer
+- [ ] Policy-as-Code sem violações
+- [ ] Testes passando
+- [ ] Documentação atualizada
+
+## CI/CD (GitHub Actions)
+
+- Lint e format check em todo PR
+- Testes automatizados
+- Security scan
+- Build do wizard de instalação
+
+## Notas
+
+- Toda decisão arquitetural deve ter ADR com validade temporal
+- Incertezas devem ser marcadas com `[NEEDS CLARIFICATION]`
+- PRD define O QUÊ e PORQUÊ, nunca o COMO

miner_harness-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contribuindo para miner-harness
+
+## Requisitos
+
+- Python 3.11+
+- Ferramentas de dev: `pip install -e ".[dev]"`
+
+## Fluxo de Desenvolvimento
+
+1. Criar branch a partir de `develop`:
+   ```bash
+   git checkout develop
+   git pull origin develop
+   git checkout -b feature/minha-feature
+   ```
+
+2. Implementar mudancas seguindo as convencoes abaixo.
+
+3. Verificar localmente antes de abrir PR:
+   ```bash
+   ruff check src/ tests/
+   ruff format --check src/ tests/
+   mypy src/ --strict
+   pytest tests/ -v --cov --cov-report=term-missing
+   coverage report --fail-under=80
+   bandit -r src/ -ll
+   ```
+
+4. Abrir PR para `develop` com titulo em Conventional Commits.
+
+## Conventional Commits
+
+Todos os commits devem seguir o formato:
+
+```
+<tipo>(<escopo>): <descricao>
+
+[corpo opcional]
+
+[footer opcional]
+```
+
+Tipos validos:
+- `feat` — Nova funcionalidade
+- `fix` — Correcao de bug
+- `docs` — Documentacao
+- `refactor` — Refatoracao sem mudanca funcional
+- `test` — Adicao/correcao de testes
+- `ci` — Mudancas de CI/CD
+- `chore` — Manutencao geral
+
+Exemplo:
+```
+feat(cache): adicionar TTL configuravel por servico
+
+Permite configurar TTL diferente para cada tipo de dado do GeoSGB.
+Dados gravimetricos mudam menos frequentemente que ocorrencias.
+
+Refs: RFC-003 §3.2
+```
+
+## Gates de Qualidade
+
+Nenhum PR sera mergeado se:
+- Ruff reportar erros de lint ou formatacao
+- Mypy (strict) reportar erros de tipo
+- Testes falharem
+- Coverage ficar abaixo de 80%
+- Bandit encontrar vulnerabilidades de severidade media+
+- pip-audit encontrar dependencias vulneraveis
+
+## Estrutura de Testes
+
+```
+tests/
+├── cache/          # Testes unitarios do CacheManager
+├── cli/            # Testes dos comandos CLI
+├── connectors/     # Testes dos connectors (GeoSGB, Ollama)
+├── contract/       # Testes de contrato entre modulos
+├── core/           # Testes dos tipos e config
+├── index/          # Testes do VectorIndex
+├── integration/    # Testes de integracao end-to-end
+├── orchestrator/   # Testes do Orchestrator
+└── property/       # Property-based tests (Hypothesis)
+```
+
+## Rastreabilidade
+
+Toda mudanca significativa deve referenciar:
+- RFC relevante (ex: `Refs: RFC-001 §4.1`)
+- ADR se houver decisao arquitetural
+- Issue/ticket se aplicavel