k-extract 0.1.0__tar.gz

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

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest

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

@@ -0,0 +1,124 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  # -----------------------------------------------------------
+  # Job 1: Determine version, tag, and create GitHub Release
+  # -----------------------------------------------------------
+  release:
+    runs-on: ubuntu-latest
+    if: github.repository == 'jsell-rh/k-extract'
+
+    permissions:
+      contents: write
+      id-token: write
+
+    outputs:
+      released: ${{ steps.semrel.outputs.released }}
+      version: ${{ steps.semrel.outputs.version }}
+      tag: ${{ steps.semrel.outputs.tag }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Configure Git credentials
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Python Semantic Release
+        id: semrel
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          root_options: "-vv"
+
+  # -----------------------------------------------------------
+  # Job 2: Build distribution artifacts
+  # -----------------------------------------------------------
+  build:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout released tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # -----------------------------------------------------------
+  # Job 3: Publish to PyPI using OIDC Trusted Publishing
+  # -----------------------------------------------------------
+  publish-pypi:
+    needs: [release, build]
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/k-extract/${{ needs.release.outputs.version }}/
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # -----------------------------------------------------------
+  # Job 4: Upload artifacts to the GitHub Release
+  # -----------------------------------------------------------
+  publish-github-release:
+    needs: [release, build]
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload to GitHub Release
+        uses: python-semantic-release/publish-action@v10
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ needs.release.outputs.tag }}

k_extract-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+extraction.yaml 
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.pytest_cache/
+graph.jsonl
+extraction.db
+extraction.db*
+logs/

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

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false

k_extract-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

k_extract-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.0 (2026-04-09)
+
+- Initial Release

k_extract-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: k-extract
+Version: 0.1.0
+Summary: General-purpose knowledge graph extraction framework
+Requires-Python: >=3.12
+Requires-Dist: claude-agent-sdk>=0.1.56
+Requires-Dist: click>=8.1
+Requires-Dist: pathspec>=0.12
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: structlog>=24.0

k_extract-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "k-extract"
+version = "0.1.0"
+description = "General-purpose knowledge graph extraction framework"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "claude-agent-sdk>=0.1.56",
+    "click>=8.1",
+    "rich>=13.0",
+    "sqlalchemy>=2.0",
+    "pydantic-settings>=2.0",
+    "structlog>=24.0",
+    "pyyaml>=6.0",
+    "pathspec>=0.12",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+    "pyright>=1.1",
+    "pre-commit>=3.0",
+    "pytest-asyncio>=1.3.0",
+]
+
+[project.scripts]
+k-extract = "k_extract.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/k_extract"]
+
+[tool.pytest.ini_options]
+markers = [
+    "e2e: end-to-end integration tests requiring a real Claude API key (deselected by default)",
+]
+
+[tool.ruff]
+src = ["src"]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+venvPath = "."
+venv = ".venv"
+include = ["src"]
+typeCheckingMode = "standard"
+
+# ---------------------------------------------------------------------------
+# Semantic Release
+# ---------------------------------------------------------------------------
+[tool.semantic_release]
+commit_parser = "conventional"
+version_toml = ["pyproject.toml:project.version"]
+allow_zero_version = true
+major_on_zero = false
+
+[tool.semantic_release.branches.main]
+match = "main"
+
+[tool.semantic_release.publish]
+upload_to_vcs_release = false
+
+[tool.semantic_release.commit_author]
+env = "GIT_COMMIT_AUTHOR"
+default = "github-actions[bot] <github-actions[bot]@users.noreply.github.com>"
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+parse_squash_commits = true
+ignore_merge_commits = true
+
+[tool.semantic_release.changelog]
+exclude_commit_patterns = [
+    '''chore(?:\([^)]*?\))?: .+''',
+    '''ci(?:\([^)]*?\))?: .+''',
+    '''refactor(?:\([^)]*?\))?: .+''',
+    '''style(?:\([^)]*?\))?: .+''',
+    '''test(?:\([^)]*?\))?: .+''',
+    '''docs(?:\([^)]*?\))?: .+''',
+    '''build(?:\([^)]*?\))?: .+''',
+    '''review(?:\([^)]*?\))?: .+''',
+]
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+output_format = "md"
+
+[tool.semantic_release.remote]
+type = "github"
+token = { env = "GH_TOKEN" }

k_extract-0.1.0/scripts/loop.sh

@@ -0,0 +1,6 @@
+while true; do
+  claude --model opus[1m] --dangerously-skip-permissions < specs/prompts/project-manager.md
+  claude --model opus[1m] --dangerously-skip-permissions < specs/prompts/implementation.md
+  claude --model opus[1m] --dangerously-skip-permissions < specs/prompts/verifier.md
+  claude --model opus[1m] --dangerously-skip-permissions < specs/prompts/process-revision.md
+done

k_extract-0.1.0/scripts/stats.sh

@@ -0,0 +1,315 @@
+#!/usr/bin/env bash
+# k-extract Build Stats — tracks velocity, quality, and cost metrics across tasks.
+# Usage: ./scripts/stats.sh [--json]
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+TASKS_DIR="$REPO_ROOT/specs/tasks"
+REVIEWS_DIR="$REPO_ROOT/specs/reviews"
+JSON_MODE=false
+[[ "${1:-}" == "--json" ]] && JSON_MODE=true
+
+# --- Colors (disabled for JSON or non-tty) ---
+if $JSON_MODE; then
+    BOLD="" DIM="" RESET="" GREEN="" YELLOW="" RED="" CYAN="" BLUE="" MAGENTA=""
+else
+    BOLD=$'\033[1m' DIM=$'\033[2m' RESET=$'\033[0m'
+    GREEN=$'\033[32m' YELLOW=$'\033[33m' RED=$'\033[31m'
+    CYAN=$'\033[36m' BLUE=$'\033[34m' MAGENTA=$'\033[35m'
+fi
+
+# --- Task status counts ---
+total_tasks=0; complete=0; in_review=0; in_progress=0; not_started=0
+declare -a task_names=() task_statuses=() task_titles=()
+
+for f in "$TASKS_DIR"/task-*.md; do
+    [[ -f "$f" ]] || continue
+    total_tasks=$((total_tasks + 1))
+    name=$(basename "$f" .md)
+    status=$(grep -oP '(?<=\*\*(Status|Progress):\*\* `)[^`]+' "$f" 2>/dev/null | head -1 || echo "unknown")
+    title=$(head -1 "$f" | sed -E 's/^# (TASK-[0-9]+|Task [0-9]+): //')
+    # Replace em-dashes with plain dashes for consistent column width
+    title="${title//—/-}"
+    # Truncate to 38 chars with ellipsis in the middle
+    if [[ ${#title} -gt 38 ]]; then
+        title="${title:0:18}..${title: -18}"
+    fi
+    task_names+=("$name")
+    task_statuses+=("$status")
+    task_titles+=("$title")
+    case "$status" in
+        complete) complete=$((complete + 1)) ;;
+        ready-for-review|in-review) in_review=$((in_review + 1)) ;;
+        in-progress) in_progress=$((in_progress + 1)) ;;
+        not-started) not_started=$((not_started + 1)) ;;
+    esac
+done
+
+# --- Review metrics per task ---
+declare -A review_rounds=() review_findings=()
+
+for f in "$REVIEWS_DIR"/task-*.md; do
+    [[ -f "$f" ]] || continue
+    name=$(basename "$f" .md)
+    round_headers=$(grep -c '^## Round [0-9]' "$f" 2>/dev/null || true)
+    rn_headers=$(grep -c '^## R[0-9]' "$f" 2>/dev/null || true)
+    findings_headers=$(grep -c '^## Findings' "$f" 2>/dev/null || true)
+    rounds=$((${round_headers:-0} + ${rn_headers:-0} + ${findings_headers:-0}))
+    findings=$(grep -c 'process-revision-complete' "$f" 2>/dev/null || true)
+    findings=${findings:-0}
+    review_rounds[$name]=$((rounds))
+    review_findings[$name]=$((findings))
+done
+
+# --- Wall clock time per task (from git history) ---
+OUTLIER_GAP=3600  # 1 hour in seconds
+
+declare -A task_wall_clock=() task_first_commit=() task_last_commit=()
+declare -A task_active_seconds=()
+declare -A task_commits=()
+
+compute_task_time() {
+    local task_id="$1"
+    local commits
+    commits=$(cd "$REPO_ROOT" && git log --all --format="%at" --grep="$task_id" --reverse 2>/dev/null)
+    [[ -z "$commits" ]] && return
+
+    local first last prev elapsed active_time=0 count=0
+    while IFS= read -r ts; do
+        [[ -z "$ts" ]] && continue
+        if [[ $count -eq 0 ]]; then
+            first=$ts
+        else
+            local gap=$((ts - prev))
+            if [[ $gap -gt 0 && $gap -lt $OUTLIER_GAP ]]; then
+                active_time=$((active_time + gap))
+            fi
+        fi
+        last=$ts
+        prev=$ts
+        count=$((count + 1))
+    done <<< "$commits"
+
+    [[ $count -lt 2 ]] && return
+
+    task_first_commit[$task_id]=$first
+    task_last_commit[$task_id]=$last
+    task_wall_clock[$task_id]=$((last - first))
+    task_active_seconds[$task_id]=$active_time
+    task_commits[$task_id]=$count
+}
+
+for name in "${task_names[@]}"; do
+    compute_task_time "$name"
+done
+
+# --- Code metrics ---
+total_py_lines=$(find "$REPO_ROOT/src" -name "*.py" -not -path "*/.git/*" 2>/dev/null | xargs wc -l 2>/dev/null | tail -1 | awk '{print $1}')
+total_py_lines=${total_py_lines:-0}
+test_py_lines=$(find "$REPO_ROOT" -name "test_*.py" -o -name "*_test.py" -not -path "*/.git/*" 2>/dev/null | xargs wc -l 2>/dev/null | tail -1 | awk '{print $1}')
+test_py_lines=${test_py_lines:-0}
+prod_py_lines=$((total_py_lines - test_py_lines))
+
+total_commits=$(cd "$REPO_ROOT" && git log --all --oneline | wc -l)
+
+# Overall timeline
+first_commit_ts=$(cd "$REPO_ROOT" && git log --all --format="%at" --reverse | head -1)
+last_commit_ts=$(cd "$REPO_ROOT" && git log --all --format="%at" | head -1)
+total_wall_seconds=$((last_commit_ts - first_commit_ts))
+
+# Checklist items (process learning)
+checklist_items=$(cd "$REPO_ROOT" && git log --all --oneline --grep="fix(process)" | wc -l)
+
+# --- Format helpers ---
+fmt_duration() {
+    local secs=$1
+    local hrs=$((secs / 3600))
+    local mins=$(( (secs % 3600) / 60 ))
+    local s=$((secs % 60))
+    if [[ $hrs -gt 0 ]]; then
+        printf "%dh %dm %ds" "$hrs" "$mins" "$s"
+    else
+        printf "%dm %ds" "$mins" "$s"
+    fi
+}
+
+progress_bar() {
+    local total=$1 n_complete=$2 n_review=$3 n_progress=$4 n_not_started=$5
+    local width=30
+    local w_complete=$((n_complete * width / total))
+    local w_review=$((n_review * width / total))
+    local w_progress=$((n_progress * width / total))
+    local w_not_started=$((width - w_complete - w_review - w_progress))
+
+    local seg=""
+    for ((i=0; i<w_complete; i++)); do seg+="#"; done
+    printf "%s%s" "${GREEN}" "$seg"
+    seg=""
+    for ((i=0; i<w_review; i++)); do seg+="#"; done
+    printf "%s%s" "${MAGENTA}" "$seg"
+    seg=""
+    for ((i=0; i<w_progress; i++)); do seg+="#"; done
+    printf "%s%s" "${BLUE}" "$seg"
+    seg=""
+    for ((i=0; i<w_not_started; i++)); do seg+="-"; done
+    printf "%s%s%s" "${DIM}" "$seg" "${RESET}"
+}
+
+# --- JSON output ---
+if $JSON_MODE; then
+    echo "{"
+    echo "  \"summary\": {"
+    echo "    \"total_tasks\": $total_tasks,"
+    echo "    \"complete\": $complete,"
+    echo "    \"in_review\": $in_review,"
+    echo "    \"in_progress\": $in_progress,"
+    echo "    \"not_started\": $not_started,"
+    echo "    \"progress_pct\": $((complete * 100 / total_tasks)),"
+    echo "    \"total_commits\": $total_commits,"
+    echo "    \"prod_lines\": $prod_py_lines,"
+    echo "    \"test_lines\": $test_py_lines,"
+    if [[ $total_py_lines -gt 0 ]]; then
+        echo "    \"test_ratio\": \"$(printf '%.1f' "$(echo "scale=1; $test_py_lines * 100 / $total_py_lines" | bc)")%\","
+    else
+        echo "    \"test_ratio\": \"0.0%\","
+    fi
+    echo "    \"total_wall_clock_seconds\": $total_wall_seconds,"
+    echo "    \"checklist_items\": $checklist_items"
+    echo "  },"
+    echo "  \"tasks\": ["
+    first=true
+    for i in "${!task_names[@]}"; do
+        name="${task_names[$i]}"
+        status="${task_statuses[$i]}"
+        rounds=${review_rounds[$name]:-0}
+        findings=${review_findings[$name]:-0}
+        active=${task_active_seconds[$name]:-0}
+        wall=${task_wall_clock[$name]:-0}
+        $first || echo ","
+        first=false
+        commits=${task_commits[$name]:-0}
+        printf '    {"task": "%s", "status": "%s", "commits": %d, "review_rounds": %d, "findings": %d, "active_seconds": %d, "wall_seconds": %d}' \
+            "$name" "$status" "$commits" "$rounds" "$findings" "$active" "$wall"
+    done
+    echo ""
+    echo "  ]"
+    echo "}"
+    exit 0
+fi
+
+# --- Human output ---
+echo ""
+echo "${BOLD}k-extract Build Stats${RESET}"
+echo "${DIM}$(date '+%Y-%m-%d %H:%M')${RESET}"
+echo ""
+
+# Progress
+if [[ $total_tasks -gt 0 ]]; then
+    pct=$((complete * 100 / total_tasks))
+    echo "${BOLD}Progress${RESET}"
+    printf "  [$(progress_bar $total_tasks $complete $in_review $in_progress $not_started)] %d%% (%d/%d tasks)\n" "$pct" "$complete" "$total_tasks"
+    echo "  ${GREEN}$complete complete${RESET}  ${MAGENTA}$in_review in review${RESET}  ${BLUE}$in_progress in progress${RESET}  ${DIM}$not_started not started${RESET}"
+else
+    echo "${BOLD}Progress${RESET}"
+    echo "  ${DIM}No tasks found in $TASKS_DIR${RESET}"
+fi
+echo ""
+
+# Timeline
+echo "${BOLD}Timeline${RESET}"
+echo "  Total wall clock:  $(fmt_duration $total_wall_seconds)"
+echo "  Total commits:     $total_commits"
+echo "  Checklist items:   $checklist_items (accumulated process learnings)"
+echo ""
+
+# Code
+echo "${BOLD}Code${RESET}"
+echo "  Production:  $prod_py_lines lines"
+echo "  Test:        $test_py_lines lines"
+if [[ $total_py_lines -gt 0 ]]; then
+    echo "  Test ratio:  $(printf '%.0f' "$(echo "scale=1; $test_py_lines * 100 / $total_py_lines" | bc)")% of total"
+fi
+if [[ $total_wall_seconds -gt 0 && $prod_py_lines -gt 0 ]]; then
+    echo "  Throughput:  ~$(( prod_py_lines * 3600 / total_wall_seconds )) prod lines/hr"
+fi
+echo ""
+
+# Per-task breakdown
+if [[ $total_tasks -gt 0 ]]; then
+    echo "${BOLD}Task Breakdown${RESET}"
+    printf "  ${DIM}%-8s  %-38s  %-16s  %7s  %6s  %8s  %14s${RESET}\n" "TASK" "TITLE" "STATUS" "COMMITS" "ROUNDS" "FINDINGS" "ACTIVE TIME"
+    printf "  %s%s%s\n" "${DIM}" "------------------------------------------------------------------------------------------------------" "${RESET}"
+
+    total_rounds=0; total_findings=0; total_active=0; total_task_commits=0
+    for i in "${!task_names[@]}"; do
+        name="${task_names[$i]}"
+        status="${task_statuses[$i]}"
+        rounds=${review_rounds[$name]:-0}
+        findings=${review_findings[$name]:-0}
+        active=${task_active_seconds[$name]:-0}
+        commits=${task_commits[$name]:-0}
+
+        total_rounds=$((total_rounds + rounds))
+        total_findings=$((total_findings + findings))
+        total_active=$((total_active + active))
+        total_task_commits=$((total_task_commits + commits))
+
+        case "$status" in
+            complete)         status_label="complete";         status_color="$GREEN" ;;
+            ready-for-review) status_label="ready-for-review"; status_color="$MAGENTA" ;;
+            needs-revision)   status_label="needs-revision";   status_color="$YELLOW" ;;
+            in-review)        status_label="in-review";        status_color="$YELLOW" ;;
+            in-progress)      status_label="in-progress";      status_color="$BLUE" ;;
+            not-started)      status_label="not-started";      status_color="$DIM" ;;
+            *)                status_label="$status";          status_color="" ;;
+        esac
+        sc="${status_color}$(printf '%-16s' "$status_label")${RESET}"
+
+        rpad=$(printf "%6d" "$rounds")
+        if [[ $rounds -eq 0 ]]; then
+            rc="${DIM}${rpad}${RESET}"
+        elif [[ $rounds -le 3 ]]; then
+            rc="${GREEN}${rpad}${RESET}"
+        elif [[ $rounds -le 7 ]]; then
+            rc="${YELLOW}${rpad}${RESET}"
+        else
+            rc="${RED}${rpad}${RESET}"
+        fi
+
+        fpad=$(printf "%8d" "$findings")
+
+        if [[ $active -gt 0 ]]; then
+            at=$(printf "%14s" "$(fmt_duration $active)")
+        else
+            at="$(printf '%12s' '')${DIM}--${RESET}"
+        fi
+
+        cpad=$(printf "%7d" "$commits")
+        title="${task_titles[$i]}"
+        printf "  %-8s  %-38s  %s  %s  %s  %s  %s\n" "$name" "$title" "$sc" "$cpad" "$rc" "$fpad" "$at"
+    done
+
+    printf "  %s%s%s\n" "${DIM}" "------------------------------------------------------------------------------------------------------" "${RESET}"
+    printf "  ${BOLD}%-8s  %-38s  %-16s  %7d  %6d  %8d  %14s${RESET}\n" "TOTAL" "" "" "$total_task_commits" "$total_rounds" "$total_findings" "$(fmt_duration $total_active)"
+    echo ""
+
+    # Review efficiency
+    if [[ $total_findings -gt 0 ]]; then
+        echo "${BOLD}Review Efficiency${RESET}"
+        echo "  Total findings:        $total_findings"
+        echo "  Total review rounds:   $total_rounds"
+        echo "  Findings per round:    $(printf '%.1f' "$(echo "scale=1; $total_findings / $total_rounds" | bc)")"
+        if [[ $complete -gt 0 ]]; then
+            echo "  Avg rounds per task:   $(printf '%.1f' "$(echo "scale=1; $total_rounds / $complete" | bc)") (completed tasks only)"
+        fi
+        echo ""
+
+        echo "  ${DIM}Highest review effort:${RESET}"
+        for name in "${task_names[@]}"; do
+            r=${review_rounds[$name]:-0}
+            f=${review_findings[$name]:-0}
+            [[ $r -gt 0 ]] && echo "    $r rounds, $f findings  $name"
+        done | sort -rn | head -3
+        echo ""
+    fi
+fi