pyarchinit-mini
Advanced tools
Lightweight archaeological data management system with REST API, Web UI, Desktop GUI, CLI, multi-user authentication, real-time collaboration, analytics dashboard, PyArchInit import/export, Heriverse/ATON export integration, and 3D CRUD viewer
Lightweight Archaeological Data Management System - 100% Desktop GUI Parity
PyArchInit-Mini is a standalone, modular version of PyArchInit focused on core archaeological data management functionality without GIS dependencies. It provides multiple interfaces (Web, Desktop GUI, CLI, REST API) with a clean, scalable architecture for managing archaeological sites, stratigraphic units, and material inventories.
pyarchinit-mini-configure-claudeuvx for instant Claude Desktop accessComplete overhaul of media file handling with professional viewing capabilities:
Specialized Media Viewers:
Media Management Features:
Technical Improvements:
python-docx>=1.0.0 dependency for DOCX viewingUser Experience:
All interfaces now display the same version number dynamically from a single source:
--version flag shows v1.7.13Fixed hardcoded version strings across all interfaces to use centralized __version__ from main package, ensuring consistent versioning across Web, Desktop GUI, CLI, and API.
Complete implementation of Extended Matrix Framework with GraphML export for yEd Graph Editor, including PyArchInit-compatible edge styling and DOT-based workflow.
📖 Full Documentation: Extended Matrix Export Technical Guide
Extended Matrix Framework: PyArchInit-Mini supports the full Extended Matrix specification with 14 unit types and dual relationship symbols.
Stratigraphic Units (use > / < symbols):
Non-Stratigraphic Units (use >> / << symbols):
tipo_documento field: Image, PDF, DOCX, CSV, Excel, TXT)Standard Stratigraphic (> and <):
> indicates "above" or "more recent than"< indicates "below" or "older than"US 1001 > US 1002 (US 1001 covers US 1002)Special Non-Stratigraphic (>> and <<):
>> indicates "is connected to" or "derives from"<< indicates "receives from" or "is source for"DOC 8001 >> US 1001 (Document 8001 documents US 1001)DOC units have special functionality with tipo_documento field and file upload:
# Creating a DOC unit with file upload
us_data = {
'sito': 'Pompei',
'us': 'DOC-8001',
'unita_tipo': 'DOC',
'tipo_documento': 'Image', # or: PDF, DOCX, CSV, Excel, TXT
'file_path': 'DoSC/Pompei_DOC-8001_20251023_142530_photo.jpg',
'd_interpretativa': 'General excavation photo, Area A'
}
File Upload Features:
DoSC/ directory{SITE}_{US}_{TIMESTAMP}_{ORIGINALNAME}file_path field for retrievalAutomatic Field Display:
Usage:
DoSC/SITE_US_TIMESTAMP_filename.ext📖 Full Guide: DOC File Upload Documentation
Core Capabilities:
> or >> labeling based on unit typeEM_palette Node Styles:
Edge Styles (PyArchInit EM Palette): All edges are black with differentiated styles and arrowheads:
Usage Examples:
# Python API - Create Extended Matrix graph
import networkx as nx
graph = nx.DiGraph()
# Add stratigraphic units
graph.add_node(1001,
unita_tipo='US',
d_stratigrafica='Fill layer',
d_interpretativa='Medieval deposit')
graph.add_node(2001,
unita_tipo='USM',
d_stratigrafica='Wall',
d_interpretativa='Roman wall in opus reticulatum')
# Add DOC unit with document type
graph.add_node(8001,
unita_tipo='DOC',
tipo_documento='Image',
d_interpretativa='General photo of Area A')
# Add stratigraphic relationship (uses >)
graph.add_edge(1001, 1002, relationship='copre')
# Add document relationship (uses >>)
graph.add_edge(8001, 1001, relationship='documenta')
# Export to GraphML
from pyarchinit_mini.graphml_converter import convert_dot_to_graphml
# ... (see full documentation)
# Web Interface
# Navigate to: US List → Export Harris Matrix to GraphML (yEd)
# Select site, area, and options → Download .graphml
# Desktop GUI
# Tools → Export Harris Matrix (GraphML)
Database Migration: New installations have Extended Matrix support by default. Existing databases need migrations:
# Step 1: Add tipo_documento field (document type)
python run_tipo_documento_migration.py upgrade
# Step 2: Add file_path field (file upload support)
python run_file_path_migration.py upgrade
# Rollback if needed
python run_file_path_migration.py downgrade
python run_tipo_documento_migration.py downgrade
Available Interfaces:
from pyarchinit_mini.graphml_converter import convert_dot_to_graphmlpyarchinit-graphml convert|template|batch/api/graphml/* endpointsOutput:
>, >>) on edge labelsGraphviz-Free Export with Full Extended Matrix Support
PyArchInit-Mini now includes a pure Python GraphML exporter powered by NetworkX, eliminating the need for Graphviz software installation. This provides a streamlined, dependency-free way to generate yEd-compatible Harris Matrix exports.
The pure NetworkX exporter includes authentic SVG symbols from the EM palette:
BPMN Nodes with SVG Resources:
Standard Shapes:
The exporter applies intelligent label formatting based on node type:
# Property nodes - Extract first word from description
"Materiale pietra dura" → Visual label: "Materiale"
"Material hard stone" → Visual label: "Material"
# DOC nodes - File path in URL field
DOC4001:
URL: "DosCo\test1_1.graphml"
Description: "" (empty)
Visual Label: "D.4001"
# Extractor/Combinar - Prefixed labels
Extractor400 → Visual label: "D.400"
Combinar500 → Visual label: "C.500"
# Standard nodes - US prefix
US1001 → Visual label: "US1001"
Automatic hierarchical organization by archaeological periods:
<y:TableNode>
<y:NodeLabel>Site Name</y:NodeLabel>
<y:Rows>
<y:Row id="Et_contemporanea">Età contemporanea</y:Row>
<y:Row id="Et_moderna">Età moderna</y:Row>
<y:Row id="XV_secolo">XV secolo</y:Row>
<!-- Nodes nested in period rows -->
</y:Rows>
</y:TableNode>
Python API:
from pyarchinit_mini.harris_matrix.matrix_generator import HarrisMatrixGenerator
from pyarchinit_mini.database.manager import DatabaseManager
# Generate Harris Matrix
generator = HarrisMatrixGenerator(db_manager, us_service)
graph = generator.generate_matrix("Site Name")
# Export to GraphML (Pure NetworkX)
result = generator.export_to_graphml(
graph=graph,
output_path="harris_matrix.graphml",
site_name="Site Name",
title="Site Name Harris Matrix",
use_extended_labels=True, # Extended Matrix labels
include_periods=True, # Period clustering
apply_transitive_reduction=True, # Remove redundant edges
reverse_epochs=False # Chronological order (oldest→newest)
)
CLI Interface:
# Start interactive CLI
pyarchinit-mini
# Navigate to: Harris Matrix → Export Matrix
# Select site and options
# GraphML file generated with all features
Web Interface:
# Start web server
pyarchinit-mini-web
# Navigate to: Harris Matrix → Export GraphML
# Select site, configure options
# Download .graphml file
Desktop GUI:
# Start desktop application
pyarchinit-mini-gui
# Menu → Tools → Export Harris Matrix (GraphML)
# Configure export options
# Save dialog appears
Architecture:
pure_networkx_exporter.py: Main export logic with period groupinggraphml_builder.py: XML generation with yEd structuressvg_resources.py: EM palette SVG definitions (Extractor, Combinar, CON)Advantages over Graphviz-based Export:
Compatibility:
Performance:
The pure NetworkX exporter is fully compatible with existing workflows:
# Old way (requires Graphviz software)
from pyarchinit_mini.graphml_converter import convert_dot_to_graphml
convert_dot_to_graphml(dot_file, graphml_file)
# New way (pure Python, no Graphviz needed)
from pyarchinit_mini.harris_matrix.matrix_generator import HarrisMatrixGenerator
generator.export_to_graphml(graph, output_path, site_name)
# Same result: yEd-compatible GraphML with full EM palette support
All interfaces (CLI, Web, Desktop GUI) automatically use the pure NetworkX exporter when calling export_to_graphml().
User-Friendly Configuration Management for Extended Matrix Node Types
PyArchInit-Mini now features a flexible, extensible system for managing Extended Matrix node types. Add custom node types without modifying code, using either YAML configuration files or a user-friendly web interface.
✅ 14 Built-in Node Types - US, USM, VSF, SF, USD, USVA, USVB, USVC, TU, CON, DOC, property, Extractor, Combinar ✅ Add Custom Types - Create your own node types with custom styling ✅ Web Interface - Intuitive GUI for managing types (CRUD operations) ✅ YAML Configuration - Direct file editing for power users ✅ Validation - Automatic validation of colors, sizes, shapes ✅ Hot Reload - Changes take effect immediately
Via Web Interface (Recommended):
# Start web interface
cd web_interface
python app.py
# Navigate to: http://localhost:5000/em-node-config
The web interface provides:
Via YAML Configuration (Power Users):
# File: pyarchinit_mini/config/em_node_types.yaml
node_types:
SAMPLE: # Custom type ID
name: "Sample Unit"
description: "Custom sample unit type"
category: "stratigraphic" # or "non_stratigraphic"
symbol_type: "single_arrow" # > / < (or "double_arrow" for >> / <<)
visual:
shape: "diamond"
fill_color: "#FFE6E6" # Hex color
border_color: "#CC0000"
border_width: 2.5
width: 100.0
height: 40.0
font_family: "DialogInput"
font_size: 14
font_style: "bold"
text_color: "#000000"
label_format: "SAMPLE-{number}" # {number} or {first_word}
custom: true
from pyarchinit_mini.config.em_node_config_manager import get_config_manager
# Get configuration manager
config = get_config_manager()
# Get all node types
all_types = config.get_all_node_types()
# Get visual style for a type
visual = config.get_visual_style('US')
# Format a label
label = config.format_label('US', '123', '') # → "US123"
# Add custom type programmatically
visual = {
'shape': 'hexagon',
'fill_color': '#CCFFCC',
'border_color': '#00AA00',
'border_width': 2.0,
'text_color': '#000000',
'font_family': 'DialogInput',
'font_size': 16,
'font_style': 'bold'
}
success = config.add_custom_node_type(
tipo_id='FIND',
name='Find Unit',
description='Archaeological find',
category='stratigraphic',
symbol_type='single_arrow',
visual=visual,
label_format='FIND{number}'
)
if success:
config.save_config()
{number} - Replaced with US number (e.g., "US{number}" → "US1", "US2"){first_word} - First word from description (e.g., "Materiale", "Material")All node types are defined in pyarchinit_mini/config/em_node_types.yaml:
Node Categories:
> / <) for relationships>> / <<) for relationshipsVisual Properties:
#RRGGBB (e.g., #FFFFFF, #9B3333)Validation: Automatic validation ensures:
For complete documentation, see: Extended Matrix Framework Documentation
Interactive 3D Harris Matrix with Extended Matrix (EM) Palette Integration
s3Dgraphy provides a complete 3D visualization system for Harris Matrix diagrams, combining stratigraphic relationships with 3D models of archaeological contexts. The system uses GraphViz DOT layout for accurate positioning and supports OBJ, GLTF, and GLB 3D formats.
Automatic node coloring based on unita_tipo:
| Type | Color | RGB | Hex |
|---|---|---|---|
| Taglio | Brown | (139, 69, 19) | #8B4513 |
| Deposito | Chocolate | (210, 105, 30) | #D2691E |
| Riempimento | Peru | (205, 133, 63) | #CD853F |
| Humus | Dark Olive Green | (85, 107, 47) | #556B2F |
| Muro | Gray | (128, 128, 128) | #808080 |
| Pavimento | Dark Gray | (169, 169, 169) | #A9A9A9 |
| Crollo | Maroon | (128, 0, 0) | #800000 |
| Costruzione | Light Gray | (211, 211, 211) | #D3D3D3 |
| Distruzione | Dark Red | (139, 0, 0) | #8B0000 |
| Altro | Light Steel Blue | (176, 196, 222) | #B0C4DE |
Model Management:
# Upload 3D model for a specific US
POST /api/s3d/upload
Content-Type: multipart/form-data
Fields:
- site_name: str # Archaeological site name
- us_id: str # Stratigraphic unit ID
- file: File # 3D model file (OBJ/GLTF/GLB)
Response: {"message": str, "path": str}
Viewer Access:
# Get integrated 3D Harris Matrix viewer
GET /s3d/viewer/<site_name>
# Get models for a site
GET /api/s3d/models/<site_name>
Response: [
{
"name": str, # Display name
"path": str, # Relative path
"us_id": str, # US number or null for site-level
"format": str # "obj", "gltf", or "glb"
}
]
Harris Matrix Graph Structure:
# Input format for Harris Matrix visualization
{
"nodes": [
{
"id": str, # Unique node ID
"us_number": str, # US number for display
"type": str, # EM palette type (see table above)
"area": str, # Archaeological area/sector
"period": str, # Chronological period
"definition": str, # US description
"d_stratigrafica": str, # Stratigraphic description
"d_interpretativa": str # Archaeological interpretation
}
],
"edges": [
{
"source": str, # Source node ID
"target": str, # Target node ID
"stratigraphic_relation": str # COVERS, CUTS, FILLS, etc.
}
]
}
3D Model Requirements:
uploads/3d_models/<site_name>/site/model.objuploads/3d_models/<site_name>/US_<us_id>/model.objPython API - Upload and Visualize:
from pyarchinit_mini.s3d_integration import Model3DManager
import requests
# Upload 3D model via API
files = {'file': open('model.obj', 'rb')}
data = {
'site_name': 'Pompei',
'us_id': '1001'
}
response = requests.post(
'http://localhost:5001/api/s3d/upload',
files=files,
data=data
)
# Access viewer
viewer_url = f'http://localhost:5001/s3d/viewer/Pompei'
Python API - Direct Model Management:
from pyarchinit_mini.s3d_integration import Model3DManager
from pathlib import Path
manager = Model3DManager(base_dir='uploads/3d_models')
# Get models for a site
models = manager.get_models_for_site('Pompei')
for model in models:
print(f"US {model['us_id']}: {model['name']} ({model['format']})")
# Get model path for specific US
path = manager.get_model_path('Pompei', '1001')
cURL - Upload Model:
# Upload OBJ model
curl -X POST http://localhost:5001/api/s3d/upload \
-F "site_name=Pompei" \
-F "us_id=1001" \
-F "file=@US1001.obj"
# Upload GLTF model with vertex colors
curl -X POST http://localhost:5001/api/s3d/upload \
-F "site_name=Pompei" \
-F "us_id=1002" \
-F "file=@US1002.gltf"
# Upload site-level model (no US)
curl -X POST http://localhost:5001/api/s3d/upload \
-F "site_name=Pompei" \
-F "file=@site_overview.glb"
Web Interface - Upload and View:
Viewer Features:
For testing or creating proxy geometries:
from pyarchinit_mini.s3d_integration.test_model_generator import (
generate_test_models, EM_COLORS
)
# Generate colored box for each US type
us_data = {
'us': 1001,
'type': 'Deposito', # Will use chocolate color
'area': 'A',
'period': 'Medievale',
'position': (0, 0, 0), # X, Y, Z coordinates
'size': (2, 1, 2) # Width, Height, Depth in meters
}
generate_test_models(
us_list=[us_data],
output_dir='output/3d_models',
formats=['obj', 'gltf'] # Generate both formats
)
The 3D viewer automatically integrates with PyArchInit's Harris Matrix data:
unita_tipoComplete workflow for external applications:
import requests
import json
# 1. Define stratigraphic data
harris_data = {
"nodes": [
{
"id": "site_pompei_1001",
"us_number": "1001",
"type": "Deposito",
"area": "Regio VI",
"period": "Periodo Romano Imperiale",
"definition": "Strato di abbandono"
},
{
"id": "site_pompei_1002",
"us_number": "1002",
"type": "Pavimento",
"area": "Regio VI",
"period": "Periodo Romano Imperiale",
"definition": "Pavimento a mosaico"
}
],
"edges": [
{
"source": "site_pompei_1001",
"target": "site_pompei_1002",
"stratigraphic_relation": "COVERS"
}
]
}
# 2. Create site in PyArchInit (if not exists)
site_data = {
"site_name": "Pompei",
"location_region": "Campania",
"location_comune": "Pompei"
}
requests.post('http://localhost:5001/api/sites', json=site_data)
# 3. Upload 3D models
for us in ["1001", "1002"]:
with open(f'models/US{us}.gltf', 'rb') as f:
files = {'file': f}
data = {'site_name': 'Pompei', 'us_id': us}
requests.post('http://localhost:5001/api/s3d/upload',
files=files, data=data)
# 4. Access integrated viewer
print("Viewer: http://localhost:5001/s3d/viewer/Pompei")
Edit ~/.pyarchinit_mini/config/config.yaml:
s3dgraphy:
enabled: true
upload_dir: "web_interface/static/uploads/3d_models"
max_file_size: 104857600 # 100MB
allowed_formats: ["obj", "mtl", "gltf", "glb"]
default_camera:
position: [5, 5, 5]
target: [0, 0, 0]
Full CouchDB/Scene Wrapper for Heriverse and ATON Platforms
PyArchInit-Mini now supports complete Heriverse/ATON JSON export format with CouchDB wrapper, semantic shapes, and extended metadata for advanced 3D stratigraphic visualization on Heriverse and ATON platforms.
| Feature | s3Dgraphy JSON v1.5 | Heriverse JSON |
|---|---|---|
| Format | JSON v1.5 | Heriverse/CouchDB |
| Wrapper | No | CouchDB scene wrapper |
| UUIDs | No | Auto-generated |
| Environment | No | Panoramas, lighting |
| Scenegraph | No | 3D scene hierarchy |
| USVn Category | No | Yes (virtual negative units) |
| Semantic Shapes | No | Auto-generated GLB placeholders |
| Use Case | General web platforms | Heriverse/ATON platforms |
{site_name}_heriverse.jsonExport Heriverse JSON:
# Get Heriverse-formatted JSON with CouchDB wrapper
GET /3d/export/heriverse/<site_name>
# Example
curl http://localhost:5000/3d/export/heriverse/Pompeii \
-o pompeii_heriverse.json
Compare with standard s3Dgraphy export:
# Standard s3Dgraphy JSON v1.5
GET /3d/export/json/<site_name>
# Heriverse JSON (with wrapper)
GET /3d/export/heriverse/<site_name>
from pyarchinit_mini.s3d_integration import S3DConverter
converter = S3DConverter()
graph = converter.create_graph_from_us(us_list, "Pompeii")
# Export to Heriverse format
converter.export_to_heriverse_json(
graph,
"pompeii_heriverse.json",
site_name="Pompeii",
creator_id="user:abc123", # Optional: defaults to auto-generated UUID
resource_path="https://server.org/uploads" # Optional: defaults to placeholder
)
{
"_id": "scene:auto-generated-uuid",
"_rev": "1-auto-generated-revision",
"type": "scene",
"creator": "user:auto-generated-uuid",
"resource_path": "https://server/uploads/...",
"title": "Site Name Stratigraphy",
"resource_json": {
"environment": {
"mainpano": {"url": "s"},
"lightprobes": {"auto": "true"},
"mainlight": {"direction": ["0.0", "0.0", "0.0"]}
},
"scenegraph": {
"nodes": {},
"edges": {".": []}
},
"multigraph": {
"version": "1.5",
"context": {"absolute_time_Epochs": {}},
"graphs": {
"graph_id": {
"nodes": {
"stratigraphic": {
"US": {},
"USVs": {},
"USVn": {}, // Virtual negative units
"SF": {}
},
"semantic_shapes": {}, // 3D proxy models (GLB)
"representation_models": {}, // Full 3D models (GLTF)
"panorama_models": {} // 360° images
},
"edges": {
"is_before": [],
"generic_connection": [], // Paradata
"changed_from": [], // Evolution
"contrasts_with": [] // Interpretations
}
}
}
}
},
"wapp": "heriverse",
"visibility": "public"
}
Use Heriverse Export for:
Use Standard s3Dgraphy Export for:
The Heriverse export automatically creates semantic_shape placeholders for each stratigraphic unit:
# For each US, a semantic shape is auto-generated:
{
"shape_us_001": {
"name": "3D Model for US 001",
"description": "Proxy 3D model",
"url": "https://server/uploads/models/us_001.glb",
"format": "glb",
"us_reference": "site_us_001"
}
}
These placeholders are ready for integration with actual 3D models uploaded through the model management system.
PyArchInit-Mini v1.5.7 implements web interface integration with the chronological datazioni system:
✅ Web GUI Combobox: Datazione field now uses SelectField with database-driven choices ✅ Dynamic Choices: Dropdown populated from datazioni_table on both create and edit forms ✅ Italian Translation: Complete Italian language support for chronology fields ✅ Text Input Fields: Periodo/Fase fields changed to simple text input (no dropdowns) ✅ Form Consistency: Same behavior on both US create and edit routes ✅ Bootstrap 5 Integration: Proper form-select and form-control CSS classes
Web Interface Updates
datazione field: Changed from StringField to SelectField with database choicesperiodo_iniziale, periodo_finale: Changed from SelectField to StringField (removed 40+ hardcoded choices)fase_iniziale, fase_finale: Remain as StringField for flexible chronological data entry/us/create and /us/<us_id>/edit routesService Integration
DatazioneService initialized at app startupget_datazioni_choices() provides formatted dropdown data: [{'value': 'nome', 'label': 'Nome (Fascia)'}]User Experience
Next Steps (v1.6.0)
PyArchInit-Mini v1.5.6 introduces a comprehensive chronological dating system for standardized archaeological periodization:
✅ Datazioni Table: New datazioni_table with 36 pre-configured Italian archaeological periods
✅ Multi-Database Support: Compatible with both SQLite and PostgreSQL
✅ Service Layer: Complete CRUD operations via DatazioneService
✅ Default Initialization: Auto-populate with standard Italian periods from Paleolitico to Età Contemporanea
✅ API Ready: Choices endpoint for dropdown/combobox integration
Chronological Datazioni System
datazioni_table model with fields: nome_datazione, fascia_cronologica, descrizioneDatazioneService with complete CRUD operations and validationget_datazioni_choices() returns formatted data for form comboboxesinitialize_default_datazioni() populates table with standard periodsTesting and Quality
test_datazioni_table.py) with 7 test casesCritical fixes and improvements for GraphML export:
✅ All Interfaces Working: Web, Desktop GUI, CLI, and REST API fully operational
✅ GraphML Periodization Fixed: All archaeological periods now properly visible in yEd export (was showing only 3-4 instead of all 8 periods)
✅ Chronological Ordering: Periods arranged in correct archaeological sequence based on periodo/fase
✅ Large Site Support: Tested with Dom zu Lund (758 US nodes, 8 periods) - complete period display verified
✅ 3D Visualization: s3Dgraphy integration for stratigraphic unit visualization
✅ PyPI Package: All console commands work correctly after pip install
GraphML Export - Periodization Display Fixed
parse_clusters() to handle both quoted and unquoted label formats from GraphvizSee the CHANGELOG for complete version history.
The project is actively maintained with regular updates. Check the CHANGELOG for detailed version history.
By default, PyArchInit-Mini uses Pure NetworkX for GraphML export (no Graphviz required).
Graphviz software is optional and only needed if you want to:
tred commandThe Python module graphviz is installed automatically via pip, but the native Graphviz software requires manual installation if you need it.
Installation by Operating System:
sudo apt-get update
sudo apt-get install graphviz
sudo dnf install graphviz
brew install graphviz
sudo port install graphviz
Option 1 - Chocolatey (Recommended, automatically adds to PATH):
choco install graphviz
Option 2 - Direct Download (Requires manual PATH configuration):
Step 1: Download and Installation
.msiStep 2: Manually Add to PATH (if needed)
If Graphviz was not automatically added to PATH:
C:\Program Files\Graphviz\bin)Settings → System → About → Advanced system settingsC:\Program Files\Graphviz\binStep 3: Verification (IMPORTANT)
Open a new Command Prompt or PowerShell and verify:
dot -V
tred -V
If you see "command not found" or "not recognized":
C:\Program Files\Graphviz\bin contain dot.exe and tred.exe?Installation Verification:
# Check if dot command is available
dot -V
# Check if tred command is available (for transitive reduction)
tred -V
Expected output:
dot - graphviz version X.X.X (XXXXXXXX.XXXX)
Note: If Harris Matrix / GraphML export is not needed, you can skip Graphviz installation and use only other features.
pip install pyarchinit-mini
pip install 'pyarchinit-mini[cli]'
pip install 'pyarchinit-mini[web]'
pip install 'pyarchinit-mini[gui]'
pip install 'pyarchinit-mini[harris]'
pip install 'pyarchinit-mini[pdf]'
pip install 'pyarchinit-mini[export]'
pip install 'pyarchinit-mini[auth]'
pip install 'pyarchinit-mini[all]'
pip install 'pyarchinit-mini[dev]'
Note for zsh users: Quote the package name to avoid globbing issues:
'pyarchinit-mini[all]'
After installation, run the initialization command to set up the database and create an admin user:
pyarchinit-mini-init
This command will:
~/.pyarchinit_mini/For non-interactive setup with default credentials:
pyarchinit-mini-init --non-interactive
# Creates admin user with username: admin, password: admin
Note: If using the non-interactive mode, change the default password immediately after first login!
The setup creates the following structure in your home directory:
~/.pyarchinit_mini/
├── data/ # Database SQLite files
├── media/ # Images, videos, documents
│ ├── images/
│ ├── videos/
│ ├── documents/
│ └── thumbnails/
├── export/ # Generated PDF exports
├── backup/ # Automatic database backups
├── config/ # Configuration files
│ └── config.yaml
└── logs/ # Application logs
pyarchinit-mini-web
# Open http://localhost:5001 in your browser
# Login with the admin credentials created during initialization
pyarchinit-mini-gui
pyarchinit-mini-api
# API docs available at http://localhost:8000/docs
pyarchinit-mini
The Analytics Dashboard provides comprehensive data visualization with 8 different chart types.
pyarchinit-mini-webpyarchinit-guiCharts Update Automatically: All charts reflect the current state of your database in real-time.
PyArchInit-Mini provides 17 specialized commands for different tasks. Use pyarchinit-mini --list-commands to see this reference anytime.
pyarchinit-miniInteractive CLI with menu-driven interface
pyarchinit-mini [-d DATABASE_URL] [--version] [--list-commands]
# Examples
pyarchinit-mini # Start with default database
pyarchinit-mini -d "postgresql://user:pass@localhost/db"
pyarchinit-mini-apiREST API server (default port: 8000)
# Configuration via environment variables
PYARCHINIT_API_HOST=0.0.0.0 # Default: 0.0.0.0
PYARCHINIT_API_PORT=8000 # Default: 8000
PYARCHINIT_API_RELOAD=false # Default: false
# Example
PYARCHINIT_API_PORT=5000 pyarchinit-mini-api
pyarchinit-mini-webWeb interface (default port: 5001)
# Configuration via environment variables
PYARCHINIT_WEB_HOST=0.0.0.0 # Default: 0.0.0.0
PYARCHINIT_WEB_PORT=5001 # Default: 5001
PYARCHINIT_WEB_DEBUG=true # Default: true
# Example
PYARCHINIT_WEB_PORT=8080 PYARCHINIT_WEB_DEBUG=false pyarchinit-mini-web
pyarchinit-mini-guiDesktop GUI application (requires PyQt5)
pyarchinit-mini-gui
pyarchinit-mini-setupSetup user environment in ~/.pyarchinit_mini
pyarchinit-mini-setup
# Creates: data/, media/, export/, backup/, config/, logs/
# Copies sample database and default configuration
pyarchinit-mini-initInitialize database and create admin user
pyarchinit-mini-init # Interactive setup
pyarchinit-mini-init --non-interactive # Use defaults (admin/admin)
pyarchinit-mini-configure-claudeConfigure Claude Desktop MCP integration (requires uvx)
pyarchinit-mini-configure-claude
pyarchinit-mini-configure-claude --force # Force reconfigure
pyarchinit-mini-configure-claude --silent # No output
pyarchinit-mini-migrateRun database migrations
pyarchinit-mini-migrate --database-url "sqlite:///my_db.db"
pyarchinit-mini-mcp / pyarchinit-mcp-serverMCP server (stdio transport) for Claude Desktop
# Configured automatically via pyarchinit-mini-configure-claude
pyarchinit-mini-mcp
pyarchinit-mini-mcp-http / pyarchinit-mcp-httpMCP server (HTTP transport) for ChatGPT and web clients
# Configuration via environment variables
MCP_HOST=localhost # Default: localhost
MCP_PORT=8080 # Default: 8080
MCP_TRANSPORT=sse # Default: sse
# Example
MCP_PORT=9000 pyarchinit-mini-mcp-http
pyarchinit-export-importExport/import data to/from Excel and CSV
# Subcommands: export-sites, export-us, export-inventario
# Export sites to Excel
pyarchinit-export-import export-sites -f excel -o sites.xlsx
# Export US to CSV for specific site
pyarchinit-export-import export-us -f csv -o us.csv -s "Pompei"
# Export inventory
pyarchinit-export-import export-inventario -f excel -o inventory.xlsx
# Options:
# -f, --format [excel|csv] Output format (default: csv)
# -o, --output PATH Output file path (required)
# -s, --site TEXT Filter by site name
# -d, --database-url TEXT Database connection
pyarchinit-graphmlConvert Graphviz DOT files to yEd GraphML format
# Subcommands: convert, template
# Convert DOT to GraphML
pyarchinit-graphml convert harris.dot output.graphml -t "Pompei"
# Download yEd template
pyarchinit-graphml template my_palette.graphml
# Options (convert):
# -t, --title TEXT Diagram title
# --reverse-epochs Reverse epoch ordering
# -v, --verbose Verbose output
pyarchinit-mini-importImport from PyArchInit (full version) database
# Import all data from PyArchInit SQLite
pyarchinit-mini-import import-from-pyarchinit \
-s sqlite:////path/to/pyarchinit.db
# Import specific tables with filters
pyarchinit-mini-import import-from-pyarchinit \
-s postgresql://user:pass@host/db \
-T sites -T us --sites "Pompei" --dry-run
# Options:
# -s, --source-db TEXT Source database URL (required)
# -t, --target-db TEXT Target database URL
# -T, --tables [sites|us|inventario|periodizzazione|thesaurus|all]
# Tables to import (multiple allowed)
# --sites TEXT Filter by site names (multiple allowed)
# --import-relationships Import US relationships (default: yes)
# --dry-run Preview without changes
pyarchinit-harris-importImport Harris Matrix from Excel/CSV files
# Import Harris Matrix
pyarchinit-harris-import matrix.xlsx -s "Pompei"
# Import with GraphML and DOT export
pyarchinit-harris-import matrix.csv -s "Rome" -g -d -o ./exports
# Arguments:
# FILE_PATH Excel or CSV file
# Options:
# -s, --site TEXT Site name (required)
# -g, --export-graphml Export to GraphML format
# -d, --export-dot Export to DOT format
# -o, --output-dir TEXT Output directory (default: current)
# --db TEXT Database URL
# File Structure Required:
# Sheet 1 (NODES): us_number, unit_type, description, area, period, phase
# Sheet 2 (RELATIONSHIPS): from_us, to_us, relationship
pyarchinit-harris-templateGenerate Harris Matrix Excel/CSV template
# Generate template (creates harris_matrix_template.xlsx)
pyarchinit-harris-template
# Custom filename and format
pyarchinit-harris-template -f xlsx -o metro_c_template
# Options:
# -f, --format [xlsx|csv] Template format (default: xlsx)
# -o, --output TEXT Filename WITHOUT extension (default: harris_matrix_template)
# -e, --with-examples Include example data (default: yes)
# Complete Workflow:
# 1. Generate template: pyarchinit-harris-template -o my_template
# 2. Fill in your data: Edit my_template.xlsx with your US data
# 3. Import to database: pyarchinit-harris-import my_template.xlsx -s "Site Name"
View complete command reference anytime:
pyarchinit-mini --list-commands
View help for specific commands:
pyarchinit-export-import --help
pyarchinit-harris-import --help
pyarchinit-graphml --help
| Extra | Components | Installation |
|---|---|---|
cli | Click, Rich, Inquirer | pip install 'pyarchinit-mini[cli]' |
web | Flask, WTForms, Jinja2, Flask-SocketIO | pip install 'pyarchinit-mini[web]' |
gui | (Tkinter is in stdlib) | pip install 'pyarchinit-mini[gui]' |
harris | Matplotlib, Graphviz | pip install 'pyarchinit-mini[harris]' |
pdf | WeasyPrint | pip install 'pyarchinit-mini[pdf]' |
media | python-magic, moviepy | pip install 'pyarchinit-mini[media]' |
export | pandas, openpyxl | pip install 'pyarchinit-mini[export]' |
auth | passlib, bcrypt, python-jose, flask-login | pip install 'pyarchinit-mini[auth]' |
all | All of the above | pip install 'pyarchinit-mini[all]' |
dev | pytest, black, mypy, flake8 | pip install 'pyarchinit-mini[dev]' |
Edit ~/.pyarchinit_mini/config/config.yaml:
database:
# SQLite (default)
url: "sqlite:///~/.pyarchinit_mini/data/pyarchinit_mini.db"
# Or PostgreSQL
# url: "postgresql://user:password@localhost:5432/pyarchinit"
api:
host: "0.0.0.0"
port: 8000
reload: true
web:
host: "0.0.0.0"
port: 5001
debug: true
media:
base_dir: "~/.pyarchinit_mini/media"
max_upload_size: 104857600 # 100MB
export:
base_dir: "~/.pyarchinit_mini/export"
pdf_dpi: 300
backup:
enabled: true
frequency: "daily"
keep_count: 7
Alternatively, use environment variables:
export DATABASE_URL="postgresql://user:pass@localhost:5432/pyarchinit"
export PYARCHINIT_WEB_PORT=5001
export PYARCHINIT_API_PORT=8000
/docs, ReDoc at /redocperiod_area: Group by period and areaperiod: Group by period onlyarea: Group by area onlynone: No grouping# Export to Excel/CSV
pyarchinit-export-import export-sites -f excel -o sites.xlsx
pyarchinit-export-import export-us -f csv -s "SiteName" -o us.csv
pyarchinit-export-import export-inventario -f excel -o inventario.xlsx
# Import from CSV
pyarchinit-export-import import-sites sites.csv
pyarchinit-export-import import-us --skip-duplicates us.csv
pyarchinit-export-import import-inventario --no-skip-duplicates inv.csv
Complete authentication system with role-based access control for Web and API interfaces.
| Role | Permissions | Description |
|---|---|---|
| Admin | Full access + user management | Can create/edit/delete data and manage users |
| Operator | Create, Read, Update, Delete data | Can modify archaeological data but not users |
| Viewer | Read-only access | Can view data but cannot modify |
Install with authentication support:
pip install 'pyarchinit-mini[auth]'
# or
pip install 'pyarchinit-mini[all]'
Create users table and default admin:
python -m pyarchinit_mini.scripts.setup_auth
This creates:
admin, password: admin)Change default password (IMPORTANT):
# Login to web interface at http://localhost:5001/auth/login
# Navigate to Users → Edit admin user → Change password
http://localhost:5001/auth/loginadmin, password=adminPOST /api/auth/login to get access tokenAuthorization: Bearer <token> headerExample:
# Get token
curl -X POST http://localhost:8000/api/auth/login \
-d "username=admin&password=admin"
# Use token
curl -H "Authorization: Bearer <token>" \
http://localhost:8000/api/sites
Admins can manage users via:
POST /api/auth/register - Create user (admin only)GET /api/auth/users - List all users (admin only)PUT /api/auth/users/{id} - Update user (admin only)DELETE /api/auth/users/{id} - Delete user (admin only)| Permission | Admin | Operator | Viewer |
|---|---|---|---|
| View data | ✓ | ✓ | ✓ |
| Create data | ✓ | ✓ | ✗ |
| Edit data | ✓ | ✓ | ✗ |
| Delete data | ✓ | ✓ | ✗ |
| Manage users | ✓ | ✗ | ✗ |
| Export data | ✓ | ✓ | ✓ |
| Import data | ✓ | ✓ | ✗ |
~/.pyarchinit_mini?# Automatic setup
pyarchinit-mini-setup
Database created at: ~/.pyarchinit_mini/data/pyarchinit_mini.db
# config.yaml
database:
url: "postgresql://user:password@localhost:5432/pyarchinit"
Use the web interface:
.db file from PyArchInit Desktop~/.pyarchinit_mini/databases/git clone https://github.com/enzococca/pyarchinit-mini.git
cd pyarchinit-mini
pip install -e '.[dev]'
pytest
pytest --cov=pyarchinit_mini
black pyarchinit_mini/
isort pyarchinit_mini/
flake8 pyarchinit_mini/
mypy pyarchinit_mini/
# Verify installation
pip show pyarchinit-mini
# On Linux/Mac, ensure pip bin directory is in PATH
export PATH="$HOME/.local/bin:$PATH"
# On Windows, commands are in:
# C:\Users\<username>\AppData\Local\Programs\Python\PythonXX\Scripts\
# Re-run setup
pyarchinit-mini-setup
# Or manually specify database URL
export DATABASE_URL="sqlite:///path/to/your/database.db"
# Ubuntu/Debian
sudo apt-get install python3-tk
# Fedora/RHEL
sudo dnf install python3-tkinter
# Arch Linux
sudo pacman -S tk
# macOS
brew install graphviz
# Ubuntu/Debian
sudo apt-get install graphviz
# Windows
# Download from https://graphviz.org/download/
# Change web interface port
export PYARCHINIT_WEB_PORT=5002
pyarchinit-web
# Change API port
export PYARCHINIT_API_PORT=8001
pyarchinit-api
unita_tipo (US, USM, USD, USV, USV/s)d_stratigrafica + d_interpretativa visible in yEd<data key="d5"> elementContributions are welcome! Please:
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)git clone https://github.com/enzococca/pyarchinit-mini.git
cd pyarchinit-mini
pip install -e '.[dev]'
pre-commit install # Optional: install pre-commit hooks
PyArchInit-Mini includes an automated system to ensure documentation quality and consistency:
Features:
pyproject.toml, docs/conf.py, and CHANGELOG.mdQuick Usage:
# Run verification
python scripts/verify_docs.py
# Auto-fix version misalignments
python scripts/verify_docs.py --fix
# Install pre-commit hooks (runs verification before each commit)
bash scripts/setup_pre_commit.sh
Before Publishing a New Version:
# 1. Update version in pyproject.toml
# 2. Run auto-fix to sync all version numbers
python scripts/verify_docs.py --fix
# 3. Update CHANGELOG.md with new version entry
# 4. Verify everything is aligned
python scripts/verify_docs.py
# 5. Commit and push (pre-commit hook will run automatically)
git add pyproject.toml docs/conf.py CHANGELOG.md
git commit -m "chore: Bump version to X.Y.Z"
git push
# 6. Build and publish to PyPI
python -m build
twine upload dist/*
Documentation: See Contributing Guide for complete guide.
CI/CD: GitHub Actions automatically runs verification on every push and pull request.
This project is licensed under the GNU General Public License v2.0 - see the LICENSE file for details.
Made with ❤️ for the Archaeological Community
FAQs
Lightweight archaeological data management system with REST API, Web UI, Desktop GUI, CLI, multi-user authentication, real-time collaboration, analytics dashboard, PyArchInit import/export, Heriverse/ATON export integration, and 3D CRUD viewer
We found that pyarchinit-mini demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Impostor NuGet package Tracer.Fody.NLog typosquats Tracer.Fody and its author, using homoglyph tricks, and exfiltrates Stratis wallet JSON/passwords to a Russian IP address.
Security News
Deno 2.6 introduces deno audit with a new --socket flag that plugs directly into Socket to bring supply chain security checks into the Deno CLI.
Security News
New DoS and source code exposure bugs in React Server Components and Next.js: what’s affected and how to update safely.