Skip to content

VDP89/marco-istram

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
backend
backend
 
 
frontend
frontend
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 

Repository files navigation

MARCO — AI Co-pilot for ISTRAM/ISPOL

An AI assistant that works alongside ISTRAM/ISPOL v25.09, the road design CAD software by Buhodra Ingeniería. Built by DG Ingeniería SRL (Paraguay).

MARCO reads your ISTRAM project files in real time, understands the geometry, profiles, and earthworks, and lets you talk to your project — by text or voice — using Claude Opus 4 as its brain.

The Problem

ISTRAM/ISPOL is one of the most capable road design platforms in Latin America and Spain. It has no AI integration. Every session with Claude meant re-explaining formats, conventions, and project context from scratch.

MARCO solves this by:

  • Parsing ISTRAM's proprietary file formats directly
  • Loading a verified knowledge base built from official ISTRAM documentation
  • Watching the project folder in real time for file changes
  • Maintaining persistent memory per project

What MARCO Can Do

Capability Status
Parse .cej, .vol, .ras, .ttp, .pol, .per, .edm, .cod Working
Read project geometry (alignments, profiles, cross-sections) Working
Analyze design: Rmin, max grade, elevation range Working
Compute earthworks volumes between PKs Working
Generate valid ISTRAM files from chat Working
Validate files before writing (format rules) Working
Watch project folder for real-time changes Working
Voice input (Whisper STT) Working
Voice output (OpenAI TTS) Working (web)
Persistent memory per project Working
Query 487-section knowledge base Working
3D viewer (DXF + TIN surface) Planned (v4)

Knowledge Base

MARCO's KB was built by a 4-agent pipeline processing all official ISTRAM documentation:

  • Source: 33 tutorial PDFs + 338 official HTML help files (C:/Ispol/util/ayuda/)
  • Result: 26 Markdown files (KB v1, 128KB) + 6 compiled files (KB v2, 4.8MB)
  • Confidence score: 91% (cross-verified by 3 agents)
  • Formats documented: .cej, .edm, .per, .vol, .3do, .pol, .ras, .cod
  • Modules: ISEDM (cartography), ISPOL (road design, 11 tutorials), ISMOS (earthworks, 6 tutorials)
  • Workflows: highways, railways, intersections (roundabouts, T-junctions, crossings), volumetrics

The KB is structured in kb/MARCO_KB/:

01_FORMATOS/    — file format specs
02_MODULOS/     — module documentation (ISEDM, ISPOL, ISMOS)
03_FLUJOS/      — step-by-step workflows
04_MENUS/       — menu hierarchies
05_GLOSARIO/    — ~130 verified technical terms
06_EDICION/     — editing rules + file templates
07_REFERENCIA/  — available standards (Paraguay 2011, AASHTO)

Architecture

Current: MARCO v3 (Desktop — PySide6)

PySide6 Window
    |
    +-- MarcoBrain (Claude Opus 4, streaming)
    |       |-- knowledge.py (KB v1 always in prompt, KB v2 via tool)
    |       |-- 8 tools: read_file, list_files, memory, compute_volumes,
    |               validate_file, generate_file, workflow_guide, query_kb
    |
    +-- Core Parsers (9 formats)
    +-- Engine (alignment, profile, earthworks, cross-section, volumes)
    +-- IstramWatcher (watchdog, real-time file monitoring)
    +-- VoiceRecorder (Whisper STT)
    +-- VoiceSpeaker (OpenAI TTS)
    +-- MarcoMemory (persistent, per-project)

Next: MARCO v4 (Tauri + Svelte + FastAPI)

Tauri v2 (Rust shell, ~4MB installer)
    |
    +-- Svelte 5 + Tailwind (WebView — real CSS, animations, WebAudio)
            |
            +-- WebSocket / SSE
                    |
                    +-- Python FastAPI sidecar
                            |-- Same parsers + engine (unchanged)
                            |-- Claude Opus 4 streaming
                            |-- Whisper via WebAudio (no PyAudio)
                            |-- TTS via <audio> HTML (no winsound)
                            |-- watchdog SSE feed

Why Tauri over Electron: 3-5MB vs 100MB+ installer. 30MB vs 200-400MB RAM idle. Native WebView (no bundled Chromium).

Why migrate from PySide6: TTS broken (winsound incompatible with Qt event loop on Windows). Streaming not visible in real time. QSS is CSS2 subset — no flexbox, no animations, no modern UI.

Stack

Layer Technology
AI Brain Claude Opus 4 (Anthropic)
Voice In OpenAI Whisper API
Voice Out OpenAI TTS API
Desktop Shell PySide6 (v3) → Tauri v2 (v4)
Frontend Svelte 5 + TypeScript + Tailwind CSS
Backend Python 3.13 + FastAPI
File Watching watchdog
ISTRAM Parsing Custom parsers (9 formats)

Project Structure

marco-istram/
├── backend/
│   ├── main.py              # PySide6 desktop app (v3)
│   ├── brain.py             # Claude Opus 4 integration
│   ├── knowledge.py         # KB loader (2-level system)
│   ├── config.py            # Config + API keys (from .env)
│   ├── memory.py            # Persistent memory
│   ├── server.py            # FastAPI server
│   ├── watcher.py           # File system watcher
│   ├── core/
│   │   ├── parsers/         # .cej, .vol, .ras, .ttp, .pol, .per, .edm, .cod, .cv
│   │   ├── engine/          # alignment, profile, earthworks, cross_section, volumes
│   │   ├── generators/      # file_generator, safe_write (auto-backup)
│   │   └── validators/      # file_validator
│   ├── marco/
│   │   ├── voice_in.py      # Whisper STT
│   │   └── voice_out.py     # OpenAI TTS
│   └── api/
│       ├── routes_chat.py
│       ├── routes_project.py
│       ├── routes_realtime.py
│       ├── routes_voice.py
│       └── ws_chat.py       # WebSocket streaming
├── frontend/                # Svelte + TS + Tailwind
│   └── src/
│       ├── components/      # Chat, VoiceOrb, VoiceWave, ProjectStatus
│       └── lib/             # api, audio, stores
└── kb/
    └── MARCO_KB/            # 26-file knowledge base (91% confidence)

Setup

# 1. Clone
git clone https://github.com/VDP89/marco-istram.git
cd marco-istram

# 2. Python dependencies
cd backend
pip install anthropic openai pyside6 watchdog numpy fastapi uvicorn

# 3. API keys
cp .env.example .env
# Edit .env: add ANTHROPIC_API_KEY and OPENAI_API_KEY

# 4. Run (current v3)
python main.py

# 5. Frontend dev (optional)
cd ../frontend
npm install
npm run dev

Critical Rules for ISTRAM File Generation

Any file written to an ISTRAM project must use:

  • Encoding: ISO-8859-1 (latin-1) — UTF-8 will corrupt the files
  • Line endings: CRLF (\r\n) — LF only will cause parse errors in ISTRAM

This is enforced in core/generators/safe_write.py.

Roadmap

  • 9 ISTRAM file parsers
  • 4-agent KB pipeline (91% confidence, 26 files)
  • KB v2 from 338 official HTML docs (4.8MB, 487 sections)
  • Claude Opus 4 brain with 8 tools
  • Real-time file watcher
  • Voice in/out (Whisper + OpenAI TTS)
  • Persistent memory per project
  • File generator + validator
  • 25 tests
  • Migrate to Tauri v4 + Svelte 5 (in progress)
  • 3D viewer: DXF + TIN surface (three.js)
  • faster-whisper local (offline STT)
  • Kokoro TTS local (offline voice)
  • Multi-project support
  • .msi installer

Context

Built by Víctor Del Puerto — civil engineer and developer at DG Ingeniería SRL, Asunción, Paraguay.

MARCO is the internal AI tooling layer of DG Ingeniería. It demonstrates what's possible when a domain expert builds AI tools for their own workflow — not a generic assistant, but a system that understands the specific data formats, conventions, and workflows of one particular piece of professional software.

The parsers + KB took weeks of reverse engineering and multi-agent processing. That knowledge is the core value here.

MARCO = AI co-pilot for road design. Built with Claude Opus 4.

About

AI co-pilot for ISTRAM/ISPOL road design software. Parses proprietary formats, real-time file watching, voice in/out, Claude Opus 4 brain. Built by DG Ingeniería SRL (Paraguay).

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages