secondmate 0.3.0__tar.gz

secondmate-0.3.0/.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+    "name": "Spark SPA Dev",
+    "image": "mcr.microsoft.com/devcontainers/python:3.13",
+    "features": {
+        "ghcr.io/devcontainers/features/git:1": {},
+        "ghcr.io/devcontainers/features/node:1": {},
+        "ghcr.io/devcontainers/features/jdk:1": {
+            "version": "21"
+        }
+    },
+    "containerUser": "vscode",
+    "forwardPorts": [
+        5173
+    ],
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "dbaeumer.vscode-eslint",
+                "esbenp.prettier-vscode"
+            ]
+        }
+    },
+    "postCreateCommand": "npm install"
+}

secondmate-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [ "main" ]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        
+    - name: Install Node dependencies
+      run: npm ci
+      
+    - name: Build frontend
+      run: npm run build
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: ".python-version"
+
+    - name: Build Python package
+      run: uv build
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-artifacts
+        path: dist/
+
+  publish-to-pypi:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/secondmate
+    permissions:
+      id-token: write
+      contents: read
+      
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist-artifacts
+        path: dist/
+        
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@release/v1

secondmate-0.3.0/.gitignore

@@ -0,0 +1,45 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv
+venv/
+env/
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+*.egg-info
+
+# Spark / Iceberg
+warehouse/
+spark-warehouse/
+metastore_db/
+derby.log
+*.parquet
+*.avro

secondmate-0.3.0/.python-version

@@ -0,0 +1 @@
+3.13

secondmate-0.3.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: secondmate
+Version: 0.3.0
+Summary: Add your description here
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyspark>=4.1.0
+Requires-Dist: uvicorn>=0.40.0
+Description-Content-Type: text/markdown
+
+# SecondMate
+
+SecondMate is a modern data catalog and exploration tool built with a high-performance Python backend and a dynamic React frontend. It provides a seamless interface for managing data catalogs, namespaces, and tables, with built-in support for Apache Iceberg and PySpark.
+
+## 🚀 Key Features
+
+*   **Dynamic Catalog Browser**: Navigate through your data hierarchy (Catalogs -> Namespaces -> Tables) with an intuitive tree view.
+*   **Data Preview**: Instantly query and visualize data from your tables.
+*   **Integrated Querying**: Built-in support for executing queries against your data lake.
+*   **Iceberg Native**: Designed with Apache Iceberg in mind, including automatic sample data initialization.
+*   **Modern UI**: Built with React 19, TypeScript, and Vite, featuring a responsive design with resizable panels and a premier dark-mode aesthetic.
+
+## 🛠️ Tech Stack
+
+### Frontend
+*   **Framework**: React 19 + TypeScript
+*   **Build Tool**: Vite
+*   **State Management**: Zustand
+*   **Component**: Monaco Editor, React Resizable Panels
+*   **Styling**: Lucide React (Icons), CSS Modules
+
+### Backend
+*   **Framework**: FastAPI
+*   **Data Processing**: PySpark 4.0+ (Development build)
+*   **Table Format**: Apache Iceberg
+*   **Server**: Uvicorn
+
+## 📦 Installation & Setup
+
+### Prerequisites
+*   Node.js (v18+ recommended)
+*   Python 3.11+
+*   Java 17+ (for PySpark)
+*   [uv](https://github.com/astral-sh/uv) (recommended for Python dependency management)
+
+### 1. Development Environment
+
+SecondMate includes a unified development script that starts both the FastAPI backend and Vite frontend together.
+
+```bash
+# Clone the repository and enter the directory
+git clone <repository-url>
+cd secondmate
+
+# Install frontend dependencies
+npm install
+
+# Create a virtual environment and install backend dependencies using uv
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e .
+
+# Start the development server (runs both backend and frontend)
+./dev.sh
+```
+
+- The UI will be available at `http://localhost:5173`.
+- The API will be available at `http://localhost:8000`.
+- Automatic API docs at `http://localhost:8000/docs`.
+
+### 2. Manual/Separate Setup
+
+**Frontend (Vite Server):**
+```bash
+npm install
+npm run dev
+```
+
+**Backend (FastAPI Server):**
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+uvicorn secondmate.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 3. Production Build
+
+When building for production, the Vite frontend compiles into the Python package (`secondmate/static`), which is then served by FastAPI.
+
+```bash
+# Build the frontend (outputs to secondmate/static)
+npm run build
+
+# Install the Python package and run the CLI
+uv pip install -e .
+secondmate --port 4050
+```
+*The app will be available at `http://localhost:4050` serving both UI and API.*
+
+## 📚 API Endpoints
+
+The backend exposes several key endpoints for metadata and data retrieval:
+
+*   `GET /health`: Service health check.
+*   `GET /info`: Spark session and application details.
+*   `GET /catalogs`: List all available catalogs.
+*   `GET /catalogs/{catalog_name}/namespaces`: List namespaces within a catalog.
+*   `GET /catalogs/{catalog_name}/namespaces/{namespace}/tables`: List tables within a namespace.
+*   `GET /query`: Execute a sample query (currently fetches `user.ipgeo`).
+
+## 🧪 Sample Data
+
+On startup, the backend automatically initializes a local Spark Iceberg environment with the following sample tables:
+*   `user.ipgeo` (1000 rows)
+*   `user.sales.transactions`
+*   `user.finance.budget`
+
+Enjoy exploring your data with SecondMate!

secondmate-0.3.0/README.md

@@ -0,0 +1,109 @@
+# SecondMate
+
+SecondMate is a modern data catalog and exploration tool built with a high-performance Python backend and a dynamic React frontend. It provides a seamless interface for managing data catalogs, namespaces, and tables, with built-in support for Apache Iceberg and PySpark.
+
+## 🚀 Key Features
+
+*   **Dynamic Catalog Browser**: Navigate through your data hierarchy (Catalogs -> Namespaces -> Tables) with an intuitive tree view.
+*   **Data Preview**: Instantly query and visualize data from your tables.
+*   **Integrated Querying**: Built-in support for executing queries against your data lake.
+*   **Iceberg Native**: Designed with Apache Iceberg in mind, including automatic sample data initialization.
+*   **Modern UI**: Built with React 19, TypeScript, and Vite, featuring a responsive design with resizable panels and a premier dark-mode aesthetic.
+
+## 🛠️ Tech Stack
+
+### Frontend
+*   **Framework**: React 19 + TypeScript
+*   **Build Tool**: Vite
+*   **State Management**: Zustand
+*   **Component**: Monaco Editor, React Resizable Panels
+*   **Styling**: Lucide React (Icons), CSS Modules
+
+### Backend
+*   **Framework**: FastAPI
+*   **Data Processing**: PySpark 4.0+ (Development build)
+*   **Table Format**: Apache Iceberg
+*   **Server**: Uvicorn
+
+## 📦 Installation & Setup
+
+### Prerequisites
+*   Node.js (v18+ recommended)
+*   Python 3.11+
+*   Java 17+ (for PySpark)
+*   [uv](https://github.com/astral-sh/uv) (recommended for Python dependency management)
+
+### 1. Development Environment
+
+SecondMate includes a unified development script that starts both the FastAPI backend and Vite frontend together.
+
+```bash
+# Clone the repository and enter the directory
+git clone <repository-url>
+cd secondmate
+
+# Install frontend dependencies
+npm install
+
+# Create a virtual environment and install backend dependencies using uv
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e .
+
+# Start the development server (runs both backend and frontend)
+./dev.sh
+```
+
+- The UI will be available at `http://localhost:5173`.
+- The API will be available at `http://localhost:8000`.
+- Automatic API docs at `http://localhost:8000/docs`.
+
+### 2. Manual/Separate Setup
+
+**Frontend (Vite Server):**
+```bash
+npm install
+npm run dev
+```
+
+**Backend (FastAPI Server):**
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+uvicorn secondmate.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 3. Production Build
+
+When building for production, the Vite frontend compiles into the Python package (`secondmate/static`), which is then served by FastAPI.
+
+```bash
+# Build the frontend (outputs to secondmate/static)
+npm run build
+
+# Install the Python package and run the CLI
+uv pip install -e .
+secondmate --port 4050
+```
+*The app will be available at `http://localhost:4050` serving both UI and API.*
+
+## 📚 API Endpoints
+
+The backend exposes several key endpoints for metadata and data retrieval:
+
+*   `GET /health`: Service health check.
+*   `GET /info`: Spark session and application details.
+*   `GET /catalogs`: List all available catalogs.
+*   `GET /catalogs/{catalog_name}/namespaces`: List namespaces within a catalog.
+*   `GET /catalogs/{catalog_name}/namespaces/{namespace}/tables`: List tables within a namespace.
+*   `GET /query`: Execute a sample query (currently fetches `user.ipgeo`).
+
+## 🧪 Sample Data
+
+On startup, the backend automatically initializes a local Spark Iceberg environment with the following sample tables:
+*   `user.ipgeo` (1000 rows)
+*   `user.sales.transactions`
+*   `user.finance.budget`
+
+Enjoy exploring your data with SecondMate!

secondmate-0.3.0/dev.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Store PIDs
+BACKEND_PID=""
+FRONTEND_PID=""
+
+# Function to kill child processes
+cleanup() {
+    echo ""
+    echo "Stopping all services..."
+    if [ -n "$BACKEND_PID" ]; then
+        echo "Stopping Backend (PID: $BACKEND_PID)..."
+        kill $BACKEND_PID 2>/dev/null
+    fi
+    if [ -n "$FRONTEND_PID" ]; then
+        echo "Stopping Frontend (PID: $FRONTEND_PID)..."
+        kill $FRONTEND_PID 2>/dev/null
+    fi
+    exit 0
+}
+
+# Trap SIGINT and SIGTERM
+trap cleanup SIGINT SIGTERM
+
+echo "Starting SecondMate Development Environment..."
+
+# Start Backend
+echo "Starting Backend (FastAPI)..."
+(
+    # Activate virtual environment if it exists
+    if [ -d ".venv" ]; then
+        source .venv/bin/activate
+    elif [ -d "venv" ]; then
+        source venv/bin/activate
+    fi
+    uvicorn secondmate.main:app --reload --host 0.0.0.0
+) &
+BACKEND_PID=$!
+
+# Start Frontend
+echo "Starting Frontend (Vite)..."
+(
+    npm run dev
+) &
+FRONTEND_PID=$!
+
+# Wait for processes
+wait $BACKEND_PID $FRONTEND_PID

secondmate-0.3.0/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

secondmate-0.3.0/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>secondmate</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>