featcat 0.1.0__tar.gz

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

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: uv pip install --system ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: uv pip install --system -e ".[dev]"
+      - run: mypy featcat/
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv pip install --system -e ".[dev,tui]"
+      - run: pytest --cov=featcat --cov-report=xml --cov-report=term-missing
+      - if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v6
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  build-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: uv pip install --system build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - run: uv pip install --system dist/*.whl && featcat --help

featcat-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,94 @@
+# SETUP REQUIRED (one-time):
+# 1. Go to https://pypi.org/manage/account/publishing/
+#    Add trusted publisher:
+#    - Owner: codepawl
+#    - Repository: featcat
+#    - Workflow: publish.yml
+#    - Environment: pypi
+#
+# 2. Same for TestPyPI: https://test.pypi.org/manage/account/publishing/
+#    - Environment: testpypi
+#
+# 3. In GitHub repo Settings > Environments:
+#    - Create "pypi" environment with required reviewers (optional but recommended)
+#    - Create "testpypi" environment (no protection needed)
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: uv pip install --system -e ".[dev,tui]"
+      - run: pytest --cov=featcat --cov-report=xml --cov-report=term-missing
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: uv pip install --system build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  verify-testpypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - run: sleep 30
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: uv pip install --system --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ featcat
+      - run: featcat --help
+      - name: Verify version matches tag
+        run: |
+          INSTALLED=$(python -c "import featcat; print(featcat.__version__)")
+          TAG="${GITHUB_REF_NAME#v}"
+          echo "Installed: $INSTALLED, Tag: $TAG"
+          [ "$INSTALLED" = "$TAG" ]
+
+  publish-pypi:
+    needs: verify-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

featcat-0.1.0/.github/workflows/release-draft.yml

@@ -0,0 +1,57 @@
+name: Draft Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "featcat/__init__.py"
+
+jobs:
+  draft-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Extract version
+        id: version
+        run: |
+          VERSION=$(python -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('featcat/__init__.py').read()).group(1))")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Detected version: $VERSION"
+
+      - name: Check if tag exists
+        id: check_tag
+        run: |
+          if git rev-parse "v${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "Tag v${{ steps.version.outputs.version }} already exists, skipping."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Extract changelog entry
+        if: steps.check_tag.outputs.exists == 'false'
+        id: changelog
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          # Extract the section for this version from CHANGELOG.md
+          BODY=$(awk "/^## \[$VERSION\]/{found=1; next} /^## \[/{if(found) exit} found{print}" CHANGELOG.md)
+          if [ -z "$BODY" ]; then
+            BODY="Release v$VERSION"
+          fi
+          # Write to file to preserve multiline
+          echo "$BODY" > /tmp/release_body.md
+          echo "Changelog entry extracted."
+
+      - name: Create draft release
+        if: steps.check_tag.outputs.exists == 'false'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          name: "featcat v${{ steps.version.outputs.version }}"
+          body_path: /tmp/release_body.md
+          draft: true

featcat-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+wheels/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project runtime
+catalog.db
+docs/features.md
+docs/monitoring_report.md
+.env
+.env.local
+
+# Parquet fixtures (keep test ones)
+*.parquet
+!tests/fixtures/*.parquet
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/

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

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - 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-added-large-files
+        args: [--maxkb=500]
+      - id: debug-statements

featcat-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-03
+
+### Added
+
+- **Catalog**: Register data sources (local + S3/MinIO), scan Parquet files, auto-extract schema and statistics
+- **AI Discovery**: Describe a use case, get ranked feature recommendations and new feature suggestions via LLM
+- **Auto-doc**: LLM-powered documentation generation for features, with batch processing and Markdown export
+- **NL Query**: Natural language search across the feature catalog, with Vietnamese language detection and fuzzy fallback
+- **Quality Monitoring**: PSI drift detection, null spike alerts, range violation checks, zero variance detection
+- **LLM Backends**: Ollama and llama.cpp server support with streaming, retry logic, and JSON extraction
+- **Response Caching**: SQLite-backed LLM response cache with configurable TTL per plugin
+- **TUI**: Terminal UI with dashboard, feature browser, monitoring view, and AI chat (Textual)
+- **S3 Support**: Read Parquet metadata directly from AWS S3 and MinIO via PyArrow S3FileSystem
+- **CLI Commands**: `init`, `source add/list/scan`, `feature list/info/tag/search`, `discover`, `ask`, `doc generate/show/export/stats`, `monitor baseline/check/report`, `doctor`, `stats`, `export`, `cache stats/clear`, `ui`
+- **Configuration**: Pydantic settings loaded from `FEATCAT_*` environment variables
+- **Documentation**: README, setup guide, user guide, and admin guide (Vietnamese with English technical terms)
+
+[0.1.0]: https://github.com/codepawl/featcat/releases/tag/v0.1.0

featcat-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to featcat
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/codepawl/featcat.git
+cd featcat
+
+# Create virtual environment
+uv venv && source .venv/bin/activate
+
+# Install with dev dependencies + pre-commit hooks
+make install
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage report
+make test-cov
+
+# Run a specific test file
+pytest tests/test_catalog.py -v
+```
+
+## Code Quality
+
+```bash
+# Lint (check only)
+make lint
+
+# Auto-format + auto-fix
+make format
+
+# Type checking
+make type-check
+
+# Run all checks (lint + type-check + test)
+make check
+```
+
+## PR Workflow
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes
+4. Run checks: `make check`
+5. Commit with a descriptive message (see convention below)
+6. Push and open a Pull Request
+7. Wait for CI to pass and a review
+
+## Commit Message Convention
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add S3 support for MinIO endpoints
+fix: handle null stats in monitoring PSI computation
+docs: update admin guide with S3 troubleshooting
+chore: bump pyarrow to 16.0
+refactor: simplify JSON extraction in LLM base
+test: add integration tests for autodoc batch mode
+```
+
+## Code Style
+
+- **Formatter/Linter**: ruff (enforced via pre-commit and CI)
+- **Type hints**: Required for all public functions
+- **Line length**: 120 characters
+- **Docstrings**: Required for modules and public classes/functions
+- **Imports**: Sorted by ruff (isort-compatible)
+
+## Project Structure
+
+```
+featcat/
+├── catalog/    # Data models, SQLite DB, Parquet scanner, storage backends
+├── llm/        # LLM abstraction layer (Ollama, llama.cpp, caching)
+├── plugins/    # AI plugins (discovery, autodoc, monitoring, NL query)
+├── utils/      # Prompts, catalog context formatters, statistics, cache
+├── tui/        # Terminal UI (Textual screens and widgets)
+├── config.py   # Pydantic settings
+└── cli.py      # Typer CLI entry point
+```
+
+## Releasing
+
+1. Update version in `featcat/__init__.py`
+2. Update `CHANGELOG.md`
+3. Commit: `git commit -am "release: v0.x.0"`
+4. Push to main — a draft GitHub Release is auto-created
+5. Review the draft, click "Publish"
+6. The publish workflow handles TestPyPI verification and PyPI upload

featcat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codepawl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

featcat-0.1.0/Makefile

@@ -0,0 +1,34 @@
+.PHONY: install lint format type-check test test-cov build clean check release-check
+
+install:
+	pip install -e ".[dev,tui,s3]"
+	pre-commit install
+
+lint:
+	ruff check .
+	ruff format --check .
+
+format:
+	ruff check --fix .
+	ruff format .
+
+type-check:
+	mypy featcat/
+
+test:
+	pytest
+
+test-cov:
+	pytest --cov=featcat --cov-report=html
+	@echo "Open htmlcov/index.html to view coverage report"
+
+build:
+	python -m build
+
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage coverage.xml
+
+check: lint type-check test
+
+release-check: clean check build
+	twine check dist/*

featcat-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: featcat
+Version: 0.1.0
+Summary: AI-Powered Feature Catalog for Data Science teams
+Project-URL: Homepage, https://github.com/codepawl/featcat
+Project-URL: Documentation, https://github.com/codepawl/featcat/tree/main/docs
+Project-URL: Repository, https://github.com/codepawl/featcat
+Project-URL: Issues, https://github.com/codepawl/featcat/issues
+Project-URL: Changelog, https://github.com/codepawl/featcat/blob/main/CHANGELOG.md
+Author-email: Codepawl <hi@codepawl.dev>
+License: MIT
+License-File: LICENSE
+Keywords: ai,data-science,feature-catalog,feature-store,mlops
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: rich>=13.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: typer>=0.9
+Provides-Extra: all
+Requires-Dist: s3fs>=2024.0; extra == 'all'
+Requires-Dist: textual>=0.50; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: boto3>=1.28; extra == 'dev'
+Requires-Dist: moto[s3]>=5.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-tmp-files>=0.0.2; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: s3
+Requires-Dist: s3fs>=2024.0; extra == 's3'
+Provides-Extra: tui
+Requires-Dist: textual>=0.50; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# featcat
+
+![CI](https://github.com/codepawl/featcat/actions/workflows/ci.yml/badge.svg)
+![PyPI](https://img.shields.io/pypi/v/featcat)
+![Python](https://img.shields.io/pypi/pyversions/featcat)
+![License](https://img.shields.io/pypi/l/featcat)
+
+**AI-Powered Feature Catalog for Data Science Teams**
+
+[Tiếng Việt](docs/README-vi.md)
+
+featcat is a lightweight Feature Catalog designed for Data Science teams. It is **not** a Feature Store (no online serving) — it's a metadata management tool with an AI layer for searching, documenting, and monitoring feature quality.
+
+## The Problem
+
+- **Features scattered everywhere**: Parquet files stored across local disks, S3, and MinIO — nobody knows what features exist
+- **Missing documentation**: Dataset columns have no descriptions; new team members don't know what `avg_session_duration` means
+- **Hard to find the right features**: Starting a new project (e.g. churn prediction) with no idea which features are already available
+- **Undetected data drift**: Feature distributions change silently until model performance degrades
+
+## Key Features
+
+| Module | Description | Phase |
+|--------|-------------|-------|
+| **Catalog** | Register data sources, scan Parquet to auto-extract schema + stats | 1 |
+| **AI Discovery** | Describe a use case → AI recommends relevant features + suggests new ones | 2 |
+| **Auto-doc** | LLM automatically generates documentation for each feature | 2 |
+| **NL Query** | Ask in natural language (English or Vietnamese), AI finds relevant features | 2 |
+| **Monitoring** | PSI drift detection, null spikes, range violations | 3 |
+| **TUI** | Terminal UI with dashboard, feature browser, AI chat | 3 |
+| **S3 Support** | Read Parquet directly from S3/MinIO — never copies data locally | 1 |
+| **Caching** | Cache LLM responses to speed up doc generation and NL queries | 3 |
+
+## Quick Start
+
+```bash
+# 1. Clone and install
+git clone https://github.com/codepawl/featcat.git && cd featcat
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# 2. Initialize catalog
+featcat init
+
+# 3. Register and scan a data source
+featcat source add device_perf /data/features/device_performance.parquet
+featcat source scan device_perf
+
+# 4. Browse features
+featcat feature list
+featcat feature info device_perf.cpu_usage
+
+# 5. (Optional) Enable AI features — requires Ollama
+ollama serve &
+ollama pull qwen2.5:7b
+featcat discover "churn prediction for telecom customers"
+featcat ask "features related to user behavior"
+```
+
+## TUI (Terminal UI)
+
+```bash
+uv pip install -e ".[tui]"
+featcat ui
+```
+
+<!-- Screenshot placeholder -->
+<!-- ![featcat TUI](docs/assets/tui-screenshot.png) -->
+
+Keybindings: `D` Dashboard | `F` Features | `M` Monitor | `C` Chat | `Q` Quit | `?` Help
+
+## System Health Check
+
+```bash
+featcat doctor
+```
+
+```
+[x] Python 3.10+
+[x] SQLite catalog exists (catalog.db)
+[x] Ollama running at localhost:11434
+[x] Model qwen2.5:7b available
+[x] 14 features registered
+[x] 10 features have docs (71.4%)
+[ ] 2 features have drift warnings
+```
+
+## Tech Stack
+
+- **Python 3.10+** | **SQLite** (metadata only, never copies data)
+- **Typer** + **Rich** (CLI) | **Textual** (TUI)
+- **PyArrow** (Parquet schema + stats) | **s3fs** (S3/MinIO)
+- **Ollama** (local LLM) | **Pydantic** (models + config)
+
+## Project Structure
+
+```
+featcat/
+├── catalog/        # Models, DB, scanner, storage backends
+├── llm/            # LLM abstraction (Ollama, llama.cpp)
+├── plugins/        # Discovery, Autodoc, Monitoring, NL Query
+├── utils/          # Prompts, catalog context, statistics, cache
+├── tui/            # Textual TUI (screens, widgets)
+├── config.py       # Pydantic settings
+└── cli.py          # Typer CLI entry point
+```
+
+## License
+
+MIT