realtimex-manifest-ai 0.1.2
Add your description here
Requires Python: >=3.11

# RealTimeX.AI Manifest - Document Analysis & Validation

## 📁 Directory Structure

```
manifest-ai/
├── src/
│   └── realtimex_manifest_ai/     # Main package source
│       ├── main.py                 # MCP tools and server entry
│       ├── batch.py                # Batch ID generation
│       ├── registry.py             # Document registry
│       ├── master_records.py       # Master records extraction
│       ├── template_filler.py      # Template filling utility
│       ├── utils.py                # Utility functions
│       ├── schemas/                # JSON schemas
│       └── batch_data/             # Runtime batch data (git-ignored)
├── examples/                       # Sample data (not installed)
│   ├── README.md                   # Examples documentation
│   ├── setup_samples.py            # Script to copy samples to cache
│   └── sample_batch_data/          # Pre-generated sample batches
│       └── {batch_id}/             # Sample batch
│           ├── registry.json       # Document registry
│           ├── summary.json        # Batch summary
│           ├── data/               # Extracted structured data
│           ├── enhanced_data/      # AI-enhanced data
│           ├── images/             # Page images
│           ├── ocr_data/           # OCR results
│           ├── outputs/            # Generated outputs
│           └── documents/          # Original documents
├── templates/                      # Web UI templates
│   ├── index.html                  # Main dashboard
│   ├── summary.html                # Summary view
│   ├── css/                        # Stylesheets
│   └── js/                         # JavaScript modules
├── plannings/                      # Implementation plans
└── README.md
```

## 🚀 Quick Start

### Installation

```bash
pip install realtimex-manifest-ai
```

### Setup Sample Data

To test the package with pre-generated sample data:

```bash
python examples/setup_samples.py
```

This copies sample batches to `~/.realtimex.ai/Resources/agent-resources/manifest-ai/batch_data/`

See [examples/README.md](examples/README.md) for more details.

## 📋 MCP Tools

### Document Analysis
- `get_document_batch_id(file_path)` - Generate batch ID for document
- `get_document_registry(batch_id, file_path)` - Get document registry

### Master Records
- `get_master_records(batch_id)` - Map which document contains which field
- `extract_master_records_data(batch_id)` - Extract actual data values
- `export_payment_order(batch_id)` - Generate filled payment order

### Dashboard & Analysis
- `show_manifest_dashboard(batch_id)` - Show dashboard UI
- `analyze_with_bank_flow(batch_id)` - Analyze with banking context

## 📁 Batch Data Structure

Runtime batch data is stored in cache:
```
~/.realtimex.ai/Resources/agent-resources/manifest-ai/batch_data/
└── {batch_id}/             # Each batch has its own folder
    ├── registry.json       # Document registry for this batch
    ├── summary.json        # Batch summary
    ├── data/               # OCR JSON payloads
    │   └── bank/           # Banking-specific data
    │       └── master_records.json  # Final extracted data
    ├── enhanced_data/      # AI-enhanced data (optional)
    ├── images/             # Rendered page images
    ├── ocr_data/           # OCR results per document
    ├── outputs/            # Generated outputs (payment orders, etc.)
    ├── documents/          # Original documents
    └── master_records.json # Document-to-field mapping
```

## 🌐 Web Dashboard

### Start the Server

```bash
# From project root
python -m realtimex_manifest_ai.server
```

Or:
```bash
python src/realtimex_manifest_ai/server.py
```

**Expected Output:**
```
================================================================================
🚀 Manifest AI Server Starting
================================================================================

📁 Batch Data Directory: ~/.realtimex.ai/Resources/agent-resources/manifest-ai/batch_data
🎨 Templates Directory: /path/to/src/realtimex_manifest_ai/templates

✓ Found 1 batch(es) in cache:
  - c45cd2fbfa40c4663862ec723ef17a5fd17635dd

🌐 Server URL: http://localhost:8000
📊 Dashboard: http://localhost:8000/templates?batch_id=<BATCH_ID>

================================================================================
```

The server:
- Serves templates from package directory
- Reads/writes batch data from cache directory
- Provides API endpoints for user data (overrides, verifications, etc.)
- Auto-creates user_data folder for modifications

### Access the Dashboard

```
http://localhost:8000/templates?batch_id={BATCH_ID}&theme=light
```

**Example with Sample Data:**
```
http://localhost:8000/templates?batch_id=c45cd2fbfa40c4663862ec723ef17a5fd17635dd&theme=light
```

**Note:** If you see a warning about no batch data, run:
```bash
python examples/setup_samples.py
```

## 📚 Documentation

For detailed documentation:
- [Documentation Index](docs/README.md)
- [Implementation Guides](docs/implementation/)
- [Architecture Docs](docs/architecture/)
- [Example Usage](examples/README.md)
- [Test Suite](tests/README.md)
- [Utility Scripts](scripts/README.md)

## 📝 Files

### 1. **index.html**
- Basic HTML shell
- Links to CSS and JavaScript modules
- Minimal body placeholder

### 2. **CSS modules (templates/css/...)**
- `main.css`: Global styles and CSS variables
- `modal.css`: Modal, grid view, and AI enhancement styles
- `tree.css`: Tree view styles
- `components.css`: UI components (tabs, badges, buttons)

### 3. **JavaScript modules (templates/js/...)**
- `state.js`: Shared data structures and UI state
- `analysis.js`: Data loading, validation logic, and batch URL parameter handling
- `tree.js`: Builds and renders the validation tree + related handlers
- `render.js`: List/document/table/grid rendering helpers
- `canvas.js`: Drawing utilities for the viewer and cropped previews
- `viewer.js`: Modal/viewer controls, zooming, and master evidence logic
- `overrides.js`: Data override management system for editing field values
- `changelog.js`: Changelog viewer UI for tracking all data modifications
- `verification.js`: Field verification system
- `ai-enhancements.js`: AI enhancement loading and application
- `events.js`: Global event wiring, search/tabs, resize handling, and document toggles
- `icons.js` & `utils.js`: Shared SVG icons + formatting helpers

## ✨ Features

### Batch Data Loading
Load different batches using URL parameter:
```
?batch_id=BATCH-VN-CN-2021-9982
```
The app automatically loads from `batch_data/{batch_id}/` folder.

### Data Override System
The application includes a powerful override system that allows you to edit field values without modifying the original JSON files:

- **Edit Values**: Click the edit button (✏️) on any field value in the grid view to modify it
- **Visual Indicators**: Edited fields are highlighted with an "EDITED" badge
- **Revert Changes**: Use the revert button (↺) to restore original values
- **File-based Storage**: All overrides are automatically saved to `user_data/overrides.json`
- **Change Log**: View all modifications in the change log panel (clock icon in bottom-right)
- **Auto-Save**: Every change is immediately saved to disk

### AI Enhancement System
If a document has AI-enhanced data in `enhanced_data/` folder:
- **Banner Notification**: A banner appears at the top of the document fields panel
- **Apply All**: Click ✓ to apply all AI suggestions at once
- **Dismiss**: Click ✕ to hide the banner
- **Individual Suggestions**: Apply or dismiss suggestions field by field

### Verification System
- **Mark Fields as Verified**: Toggle verification status on any validation
- **Verification Statistics**: Track verified vs. total fields
- **Persistent State**: Verifications are saved to `user_data/verifications.json`

### Change Log Features
- **Track All Changes**: Every edit, revert, and clear action is recorded with timestamp
- **Export/Import Backup**: Create backups of your overrides or import from a backup file
- **Clear All**: Remove all overrides at once (with confirmation)
- **Real-time Updates**: Change count badge updates automatically

### Responsive Design
- **Desktop (≥1024px)**: Split-view with validation list and viewer side-by-side
- **Mobile (<1024px)**: Full-screen modal viewer
- **Auto-resize**: UI automatically updates when resizing browser window

### Dark/Light Theme
The application supports dark and light themes controlled via URL parameter:

**Main Dashboard (index.html):**
```
http://localhost:8000/templates?batch_id=BATCH-VN-CN-2021-9982&theme=dark
http://localhost:8000/templates?batch_id=BATCH-VN-CN-2021-9982&theme=light
```

**Summary Page (summary.html):**
```
http://localhost:8000/templates/summary.html?batch_id=BATCH-VN-CN-2021-9982&theme=dark
```

- Default theme is **light** if no parameter is specified
- Theme parameter: `?theme=dark` or `?theme=light`
- Summary page is designed for iframe embedding with minimal UI

## 🔧 Maintenance

### Update CSS
Edit the modules under `templates/css/`

### Update JavaScript
Edit the modules under `templates/js/`

### Update HTML shell
Edit `templates/index.html`

## ⚠️ Notes

- **Use `python3 server.py` instead of the basic HTTP server** — the override system requires API endpoints for saving/loading data.
- JavaScript modules use `batch_id` URL parameter to determine data paths.
- On XL screens the dashboard/tree view stays on the left (scrollable) and previews render on the right.
- **Data overrides are stored in files** (in the `user_data/` folder) — they persist across sessions and browsers.
- The `user_data/` folder is automatically git-ignored to prevent committing user-specific data.