Merge pull request #8 from Ganymede-Bio/ci-cleanup

CI / general cleanup

Author: bensonlee5

.github/workflows/ci.yml

@@ -9,14 +9,17 @@ on:
 jobs:
   test:
     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.11
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
-        python-version: "3.11"
+        python-version: ${{ matrix.python-version }}
 
     - name: Install uv
       uses: astral-sh/setup-uv@v6
@@ -33,6 +36,10 @@ jobs:
       run: |
         uv run ruff check src/ tests/
 
+    - name: Type check with mypy
+      run: |
+        uv run mypy src/
+
     - name: Test with pytest
       run: |
         uv run pytest tests/ -v --cov=gridgulp --cov-report=xml

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for git info
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.cache/uv
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          pip install uv
+          uv pip install --system -e ".[docs]"
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy-docs:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build-docs
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-outputs.yml

@@ -5,6 +5,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        exclude: mkdocs.yml
       - id: check-added-large-files
         args: ['--maxkb=1000']
       - id: check-json
@@ -22,3 +23,27 @@ repos:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.5.1
+    hooks:
+      - id: mypy
+        args: [--config-file=pyproject.toml]
+        additional_dependencies: [
+          "types-aiofiles",
+          "pandas-stubs>=2.0.0",
+          "pydantic>=2.0,<3.0",
+          "python-magic"
+        ]
+        files: ^src/
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true
+        args: [--tb=short, -q]

.pre-commit-config.yaml

@@ -5,6 +5,26 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2025-07-29
+
+### Changed
+- **Project Rename**: Renamed from GridPorter to GridGulp
+  - Updated all package references throughout codebase
+  - Renamed source directory from `src/gridporter/` to `src/gridgulp/`
+  - Updated project metadata and documentation
+- CI improvements:
+  - Added Python version matrix testing (3.10, 3.11, 3.12, 3.13)
+  - Updated ruff target version to py310 (minimum supported)
+
+### Fixed
+- Fixed build configuration to match new project name
+- Fixed all linting issues identified by ruff
+- Added appropriate lint rule exceptions for tests, examples, and scripts
+- Fixed CellRange/TableRange instantiation to use keyword arguments
+- Fixed StructuredTextDetector dimension calculations
+- Fixed header extraction in StructuredTextDetector
+- Fixed test compatibility issues in DataFrameExtractor tests
+
 ## [0.3.0] - 2025-07-28
 
 ### Added
@@ -19,9 +39,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - **BREAKING**: Simplified architecture - removed all agent dependencies
-- Reduced codebase by ~77% while maintaining functionality
+- Reduced codebase substantially while maintaining functionality
 - Replaced complex agent orchestration with direct detection approach
-- SimpleCaseDetector and IslandDetector now handle 97% of use cases
+- SimpleCaseDetector and IslandDetector now handle most use cases
 - Improved file type detection to handle UTF-16 files correctly
 - capture_detection_outputs.py now processes ALL files in examples directory
 

CHANGELOG.md

@@ -1,7 +1,7 @@
 # GridGulp Project Instructions
 
 ## Overview
-GridGulp is a lightweight, efficient spreadsheet table detection framework with zero external dependencies. It automatically detects and extracts tables from spreadsheets (Excel, CSV, and text files) using proven algorithmic detection methods that handle 97% of real-world use cases.
+GridGulp is a lightweight, efficient spreadsheet table detection framework with zero external dependencies. It automatically detects and extracts tables from spreadsheets (Excel, CSV, and text files) using proven algorithmic detection methods that handle most real-world use cases.
 
 ## Core Architecture
 

CLAUDE.md

@@ -4,7 +4,7 @@ Automatically detect and extract tables from Excel, CSV, and text files.
 
 ## What is GridGulp?
 
-GridGulp finds tables in your spreadsheets - even when there are multiple tables on one sheet or when tables don't start at cell A1. No configuration required.
+GridGulp finds tables in your spreadsheets - even when there are multiple tables on one sheet or when tables don't start at cell A1. It comes with reasonable defaults and is fully configurable.
 
 **Supported formats:** `.xlsx`, `.xls`, `.xlsm`, `.xlsb`, `.csv`, `.tsv`, `.txt`
 
@@ -30,13 +30,40 @@ for sheet in result.sheets:
         print(f"  - {table.range.excel_range}")
 ```
 
+### Jupyter Notebook Usage
+
+In Jupyter notebooks, you can use synchronous methods for simplicity:
+
+```python
+from gridgulp import GridGulp
+
+# Create GridGulp instance
+gg = GridGulp()
+
+# Use the sync method - works in Jupyter without any async complexity
+result = gg.detect_tables_sync("sales_report.xlsx")
+
+# Display results
+print(f"📄 File: {result.file_info.path.name}")
+print(f"📊 Total tables found: {result.total_tables}\n")
+
+for sheet in result.sheets:
+    print(f"Sheet: {sheet.name}")
+    for table in sheet.tables:
+        print(f"  - Table at {table.range.excel_range}")
+        print(f"    Size: {table.shape[0]} rows × {table.shape[1]} columns")
+        print(f"    Confidence: {table.confidence:.1%}")
+```
+
 ### Extract DataFrames
 
+Extract detected tables as pandas DataFrames with automatic type inference and quality scoring:
+
 ```python
 from gridgulp.extractors import DataFrameExtractor
 from gridgulp.readers import get_reader
 
-# Extract detected tables as pandas DataFrames
+# Example: Extract tables from a sales report
 reader = get_reader("sales_report.xlsx")
 file_data = reader.read_sync()
 
@@ -47,12 +74,17 @@ for sheet_result in result.sheets:
     for table in sheet_result.tables:
         df, metadata, quality = extractor.extract_dataframe(sheet_data, table.range)
         if df is not None:
-            print(f"Extracted {len(df)} rows with quality score: {quality:.2f}")
+            print(f"\n📊 Extracted table from {table.range.excel_range}")
+            print(f"   Shape: {df.shape} | Quality: {quality:.1%}")
+            print(f"   Headers: {', '.join(df.columns[:5])}{'...' if len(df.columns) > 5 else ''}")
+            print(f"\nFirst few rows:")
+            print(df.head())
 ```
 
 ## Key Features
 
-- **Automatic Detection** - Finds all tables without configuration
+- **Automatic Detection** - Finds all tables with sensible defaults
+- **Fully Configurable** - Customize detection thresholds and behavior
 - **Smart Headers** - Detects single and multi-row headers automatically
 - **Multiple Tables** - Handles sheets with multiple separate tables
 - **Quality Scoring** - Confidence scores for each detected table

README.md

@@ -6,7 +6,7 @@ GridGulp is a streamlined table detection framework that uses proven algorithms
 
 ## Core Design Principles
 
-1. **Fast Path First**: 97% of use cases handled by simple algorithms
+1. **Fast Path First**: most use cases handled by simple algorithms
 2. **No External Dependencies**: Pure algorithmic detection without AI/ML services
 3. **Format Agnostic**: Unified interface for Excel, CSV, and text files
 4. **Memory Efficient**: Streaming processing for large files
@@ -16,25 +16,25 @@ GridGulp is a streamlined table detection framework that uses proven algorithms
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                    GridGulp API                        │
+│                    GridGulp API                         │
 ├─────────────────────────────────────────────────────────┤
-│                  File Type Detection                     │
-│                  (Magika + Magic)                        │
+│                  File Type Detection                    │
+│                  (Magika + Magic)                       │
 ├─────────────────────────────────────────────────────────┤
-│                    File Readers                          │
-│  ┌─────────────┬──────────────┬────────────────────┐   │
-│  │ ExcelReader │  CSVReader   │    TextReader      │   │
-│  │ (openpyxl)  │  (csv.reader)│ (encoding detect)  │   │
-│  └─────────────┴──────────────┴────────────────────┘   │
+│                    File Readers                         │
+│  ┌─────────────┬──────────────┬────────────────────┐    │
+│  │ ExcelReader │  CSVReader   │    TextReader      │    │
+│  │ (openpyxl)  │  (csv.reader)│ (encoding detect)  │    │
+│  └─────────────┴──────────────┴────────────────────┘    │
 ├─────────────────────────────────────────────────────────┤
-│                 Detection Pipeline                       │
-│  ┌─────────────────────────────────────────────────┐   │
-│  │ 1. SimpleCaseDetector (single table near A1)    │   │
-│  │ 2. IslandDetector (multi-table detection)       │   │
-│  │ 3. ExcelMetadataExtractor (ListObjects)         │   │
-│  └─────────────────────────────────────────────────┘   │
+│                 Detection Pipeline                      │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │ 1. SimpleCaseDetector (single table near A1)    │    │
+│  │ 2. IslandDetector (multi-table detection)       │    │
+│  │ 3. ExcelMetadataExtractor (ListObjects)         │    │
+│  └─────────────────────────────────────────────────┘    │
 ├─────────────────────────────────────────────────────────┤
-│                   Output Models                          │
+│                   Output Models                         │
 │  DetectionResult → SheetResult → TableInfo              │
 └─────────────────────────────────────────────────────────┘
 ```