parselabs 0.1.2__tar.gz

parselabs-0.1.2/.claude/skills/code-clarity/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: code-clarity
+description: Code quality and clarity guidelines for Python - enforces flat orchestrator patterns, explicit error handling, and mandatory comments
+---
+
+# Code Clarity Skill
+
+## Core Rules
+
+### 1. Flat Orchestrator
+
+Main functions own all flow: max 2 indent levels, early returns as guards, helpers extracted for deeper logic.
+
+```python
+def process_single_pdf(pdf_path: Path) -> tuple[Path | None, list[dict]]:
+    """Process a single PDF: extract, standardize, save."""
+    # Initialize directory structure
+    doc_out_dir, csv_path, failed_pages = _setup_paths(pdf_path)
+
+    # Guard: Skip if no pages found
+    pages = _convert_to_images(pdf_path)
+    if not pages:
+        return None, []
+
+    # Extract lab data via vision model
+    try:
+        data = _extract_via_vision(pdf_path, pages)
+    except ExtractionError as e:
+        logger.error(f"Extraction failed: {e}")
+        return None, failed_pages
+
+    # Guard: No results extracted
+    if not data:
+        return _handle_empty_results(csv_path), failed_pages
+
+    # Normalize and save
+    _apply_standardization(data)
+    _save_results(data, csv_path)
+    return csv_path, failed_pages
+```
+
+**Rules embedded in this example:**
+- **Max 2 indent levels** — `try` block is the deepest nesting
+- **Early return over else** — guards exit early, remaining code stays flat
+- **Extract helpers** — `_extract_via_vision`, `_apply_standardization` keep orchestrator readable
+- **Verb-based helper names** — `_setup_paths`, `_convert_to_images`, `_extract_via_vision`
+- **Read top-to-bottom** — all decision points visible in main flow
+
+**When to extract a helper:**
+- Indentation would reach level 3+
+- Block exceeds 5-7 contiguous lines
+- Logic is independently testable or reusable
+
+### 2. Errors Propagate Up
+
+Helpers raise exceptions. Orchestrators catch and decide.
+
+```python
+# BAD - Helper hides failure
+def _fetch_data():
+    try:
+        return api.call()
+    except Exception:
+        return None  # Caller can't distinguish failure from empty
+
+# GOOD - Helper raises, orchestrator decides
+def _fetch_data():
+    return api.call()  # Let it raise
+
+def process():
+    try:
+        data = _fetch_data()
+    except APIError as e:
+        logger.error(f"Fetch failed: {e}")
+        return None
+    return transform(data)
+```
+
+### 3. Comment Every Branch
+
+Every guard clause, if/elif/else branch, and logical block gets a comment explaining intent.
+
+```python
+# Build and validate configuration
+config, errors = build_config(args)
+
+# Guard: Bail if validation failed
+if errors:
+    return None, errors
+
+# Check error type for appropriate response
+if "401" in error_msg:
+    # Authentication failure - credentials invalid
+    return False, "Auth failed"
+elif "timeout" in error_msg.lower():
+    # Server didn't respond in time
+    return False, "Server timeout"
+else:
+    # Unknown error - fail safe
+    return False, "Unknown error"
+```
+
+**Mandatory check** — verify a comment exists before every:
+- `return` / `continue` / `break` guard
+- `if` / `elif` / `else` branch
+- Logical block (group of related statements)
+
+### 4. Blank Lines Between Blocks
+
+Separate each comment-headed block with a blank line. This includes after the docstring.
+
+```python
+# WRONG - dense wall of code
+def _classify_server_error(error_msg: str, timeout: int) -> tuple[bool, str]:
+    """Classify a server connectivity error."""
+    # Authentication errors
+    if "401" in error_msg or "Unauthorized" in error_msg:
+        return False, f"Auth failed: {error_msg}"
+    # Timeout errors
+    if "timeout" in error_msg.lower():
+        return False, f"Timeout after {timeout}s"
+    # Connection failures
+    if "Connection" in error_msg or "refused" in error_msg.lower():
+        return False, f"Cannot connect: {error_msg}"
+    # Unknown errors
+    return False, f"Server check failed: {error_msg}"
+
+# RIGHT - each block breathes
+def _classify_server_error(error_msg: str, timeout: int) -> tuple[bool, str]:
+    """Classify a server connectivity error."""
+
+    # Authentication errors
+    if "401" in error_msg or "Unauthorized" in error_msg:
+        return False, f"Auth failed: {error_msg}"
+
+    # Timeout errors
+    if "timeout" in error_msg.lower():
+        return False, f"Timeout after {timeout}s"
+
+    # Connection failures
+    if "Connection" in error_msg or "refused" in error_msg.lower():
+        return False, f"Cannot connect: {error_msg}"
+
+    # Unknown errors
+    return False, f"Server check failed: {error_msg}"
+```
+
+**Rule:** Blank line after docstring and before each comment-headed block.
+
+### 5. Early Exit Over Branching
+
+When one branch of an `if/else` is short (log, return, continue), flip it into a guard clause and remove the `else`. This reduces cognitive load — the reader can forget the short case before reading the main logic.
+
+```python
+# BAD - reader must hold both branches in mind
+def _send_notifications(errors: list[dict], recipients: list[str]) -> None:
+    """Send error notifications to recipients."""
+
+    # Check for errors and notify
+    if errors:
+        summary = f"{len(errors)} errors detected"
+        for recipient in recipients:
+            _send_email(recipient, summary, errors)
+        logger.info(f"Notified {len(recipients)} recipients")
+    else:
+        logger.info("No errors to report")
+
+# GOOD - early exit eliminates the else branch
+def _send_notifications(errors: list[dict], recipients: list[str]) -> None:
+    """Send error notifications to recipients."""
+
+    # Nothing to report
+    if not errors:
+        logger.info("No errors to report")
+        return
+
+    # Notify each recipient
+    summary = f"{len(errors)} errors detected"
+    for recipient in recipients:
+        _send_email(recipient, summary, errors)
+    logger.info(f"Notified {len(recipients)} recipients")
+```
+
+**When to flip:** The short branch should be 1-3 lines. If both branches are equally complex, an `if/else` is fine.

parselabs-0.1.2/.claude-sandbox.Dockerfile

@@ -0,0 +1,4 @@
+FROM claude-sandbox:latest
+USER root
+RUN apt-get update && apt-get install -y poppler-utils && rm -rf /var/lib/apt/lists/*
+USER claude

parselabs-0.1.2/.env.example

@@ -0,0 +1,26 @@
+# ===========================================
+# Labs Parser Configuration
+# ===========================================
+
+# Required: OpenRouter API key (get one at https://openrouter.ai/keys)
+OPENROUTER_API_KEY=<your API key>
+
+# Required: Model configuration
+# Vision model for extraction
+# Options by provider (updated January 2026):
+#   Anthropic: anthropic/claude-opus-4.5, anthropic/claude-sonnet-4, anthropic/claude-haiku-4.5
+#   Google:    google/gemini-3-flash-preview, google/gemini-3-flash-preview
+#   OpenAI:    openai/gpt-5.2, openai/gpt-4.1, openai/gpt-4.1-mini
+#   Qwen:      qwen/qwen3-max, qwen/qwen3-vl-32b-instruct
+EXTRACT_MODEL_ID=google/gemini-3-flash-preview
+
+# ===========================================
+# Optional Settings
+# ===========================================
+
+# Parallel workers for PDF processing (default: CPU count)
+# MAX_WORKERS=4
+
+# OpenRouter API base URL (default: https://openrouter.ai/api/v1)
+# Useful for proxies or alternative endpoints
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

parselabs-0.1.2/.github/dependabot.yml

@@ -0,0 +1,8 @@
+# Dependabot configuration for automated dependency updates
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

parselabs-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "parselabs/__init__.py"
+
+jobs:
+  test:
+    uses: tsilva/.github/.github/workflows/test.yml@main
+
+  pii-scan:
+    uses: tsilva/.github/.github/workflows/pii-scan.yml@main
+
+  build-and-publish:
+    needs: [test, pii-scan]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/parselabs
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

parselabs-0.1.2/.gitignore

@@ -0,0 +1,135 @@
+# >>> MANAGED BY GITGUARD - DO NOT EDIT THIS SECTION <<<
+.claude/*.local.json
+.claude/*.local.json.bak
+.claude-sandbox.json
+.mcp.json
+.env
+.env.*
+!.env.example
+!.env.*.example
+.env.*.local
+.env.local
+*.pem
+*.key
+*.p12
+*.pfx
+*.gpg
+*.secret
+*-credentials.json
+service-account*.json
+credentials.json
+secrets.json
+.secrets/
+.aws/
+.ssh/
+config.local.*
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*.code-workspace
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+env/
+*.egg-info/
+node_modules/
+.npm/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dist/
+build/
+logs/
+*.log
+# >>> END MANAGED <<<
+
+# Worktrees
+.worktrees/
+
+# Project-specific rules
+!profiles/_*
+*$py.class
+*.cover
+*.egg
+*.manifest
+*.mo
+*.pot
+*.py,cover
+*.sage.py
+*.so
+*.spec
+.cache
+.coverage
+.coverage.*
+.dmypy.json
+.eggs/
+.hypothesis/
+.installed.cfg
+.ipynb_checkpoints
+.mypy_cache/
+.nox/
+.pdm-build/
+.pdm-python
+.pdm.toml
+.pybuilder/
+.pyre/
+.pytest_cache/
+.Python
+.pytype/
+.ropeproject
+.scrapy
+.spyderproject
+.spyproject
+.tox/
+.venv
+.webassets-cache
+/site
+__pypackages__/
+celerybeat-schedule
+celerybeat.pid
+config/cache/
+cover/
+coverage.xml
+cython_debug/
+db.sqlite3
+db.sqlite3-journal
+develop-eggs/
+dmypy.json
+docs/_build/
+downloads/
+eggs/
+env.bak/
+ENV/
+htmlcov/
+input/
+instance/
+ipython_config.py
+lib/
+lib64/
+local_settings.py
+MANIFEST
+nosetests.xml
+output.zip
+output/
+parts/
+pip-delete-this-directory.txt
+pip-log.txt
+plots/
+profile_default/
+profiles/*.json
+profiles/*.yaml
+profiles/*.yml
+sdist/
+share/python-wheels/
+target/
+test/outputs/
+tests/fixtures/*
+user.json
+user_stats.json
+var/
+venv.bak/
+wheels/

parselabs-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/tsilva/.github
+    rev: v0.1.0
+    hooks:
+      - id: gitleaks