TimberSync

FW_Timber → ForestHQ Data Translation Agent

TimberSync is an AI-powered ETL (Extract, Transform, Load) agent that translates forestry inventory data from the legacy FW_Timber system into ForestHQ format.

Overview

┌─────────────────────┐         ┌─────────────────────┐
│     FW_TIMBER       │         │     ForestHQ        │
│  (Legacy System)    │         │   (PostgreSQL)      │
├─────────────────────┤         ├─────────────────────┤
│ • Excel files       │         │ • blocks            │
│ • Shapefiles        │  ─────► │ • compartments      │
│ • SQL Server (ref)  │         │ • strata            │
│                     │         │ • trees             │
└─────────────────────┘         │ • species           │
                                └─────────────────────┘

Features

• Intelligent Extraction - Parse FW_Timber Excel files and Shapefiles
• Unit Conversion - Automatic conversion (acres→sq meters, inches→meters)
• Coordinate Transformation - Reproject from Goode Homolosine to WGS84
• Species Mapping - Map FW_Timber species codes to ForestHQ IDs
• Validation - Compare source and target counts
• Interactive Mode - Chat-based interface for ad-hoc operations

Installation

# Clone or copy to your workspace
cd /path/to/MCP_Servers/TimberSync

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env with your API key and database credentials

Usage

Interactive Mode

cd src
python main.py

TimberSync - FW_Timber → ForestHQ Data Translation

You: connect
TimberSync: Connected to tm_api_development on localhost

You: extract stands from /path/to/Stand.shp
TimberSync: Extracted 127 stands from shapefile...

You: transform and load into layer 2476
TimberSync: Transformed 127 stands to blocks, inserted 127 records...

Automated Sync

python main.py --sync /path/to/FW_Timber/data \
    --db-host localhost \
    --db-name tm_api_development \
    --db-user postgres

Extract Only (Preview)

python main.py --extract /path/to/StandSummary.xlsx

Data Mappings

Entity Mapping

FW_Timber	ForestHQ	Notes
Tracts	layers	Container for sites
Compartments	compartments	Management units
Stands	blocks	With PostGIS geometry
Plots	inventory_samples	Sample points
Trees	trees	With species mapping
Inventory (PER_ACR2)	strata	Aggregated data

Unit Conversions

From	To	Formula
Acres	Square meters	× 4046.86
Inches (DBH)	Meters	× 0.0254
Feet (height)	Meters	× 0.3048
US Tons	Metric Tons	× 0.907185

Product Code Mapping

Code	FW_Timber	ForestHQ Grade
1	Pulpwood	Pulpwood
2	Small Sawtimber	Small Sawtimber
3	Large Sawtimber	Large Sawtimber
4	Premerchantable	Premerchantable
8	Topwood	Topwood
9	Cull	Cull

Project Structure

TimberSync/
├── src/
│   ├── __init__.py      # Package exports
│   ├── main.py          # Entry point (CLI)
│   ├── agent.py         # Pydantic AI agent + tools
│   ├── models.py        # Data models (Pydantic)
│   ├── db_client.py     # ForestHQ PostgreSQL client
│   └── extractors.py    # Excel/Shapefile extractors
├── tests/               # Unit tests
├── data/                # Sample data (gitignored)
├── requirements.txt
├── .env.example
└── README.md

API Reference

Agent Tools

# Extraction
extract_from_excel(file_path, data_type="all")
extract_from_shapefile(file_path, entity_type="stands")

# Transformation
transform_stands_to_blocks(layer_id, compartment_id)
transform_trees(layer_id, sample_id)

# Loading
load_blocks()
connect_database(host, database, user, password)

# Validation
validate_import(layer_id)
get_species_mapping()

Programmatic Usage

from timbersync import run_sync, interactive_chat, TimberSyncDeps

# Full sync
result = await run_sync(
    source_folder="/path/to/FW_Timber",
    db_host="localhost",
    db_name="tm_api_development"
)

# Interactive
deps = TimberSyncDeps()
response = await interactive_chat("Extract stands from Stand.shp", deps)

Configuration

Environment Variables

Variable	Description	Default
ANTHROPIC_API_KEY	Claude API key	Required
FORESTHQ_HOST	Database host	localhost
FORESTHQ_PORT	Database port	5432
FORESTHQ_DATABASE	Database name	tm_api_development
FORESTHQ_USER	Database user	postgres
FORESTHQ_PASSWORD	Database password
FW_ORGANISATION_ID	F&W org ID in ForestHQ	65

Architecture

TimberSync uses Pydantic AI with Claude to create an intelligent ETL agent:

1. Agent Layer - Natural language interface, orchestrates tools
2. Tool Layer - Extraction, transformation, loading operations
3. Model Layer - Pydantic models for type safety
4. Data Layer - asyncpg for PostgreSQL, pandas/pyshp for files

Related Projects

• Crann - AI forestry assistant with satellite imagery
• ForestHQ - Full forestry management platform

License

Internal use - F&W Forestry / TreeMetrics