rob
/
orchestrated-discussions
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
orchestrated-discussions/artifact-editor---ai-enhanc...

12 KiB
Raw Blame History

Artifact Editor - AI-Enhanced Diagram and 3D Model Creator

Context

Overview

We want to build a standalone Artifact Editor that can be launched from any application to create visual artifacts like diagrams, sketches, and 3D models.

Key Requirements

  1. Standalone executable - Can be launched via command line with arguments
  2. Multiple artifact types - Mermaid, PlantUML, OpenSCAD/SolidPython, SVG, ASCII art
  3. AI assistance - Voice input, conversational editing, auto-generation
  4. Integration contract - Simple stdin/stdout/exit-code interface for parent apps
  5. Live preview - See rendered output as you edit code

Integration Target

Primary integration with orchestrated-discussions project:

  • User clicks 'Add Artifact' in comment dialog
  • Launches artifact-editor with output path argument
  • User creates/edits artifact
  • On save, outputs 'ARTIFACT_SAVED:/path/to/file'
  • Parent app embeds artifact reference in comment

Questions to Explore

  • What's the right UI framework? (urwid TUI, Dear PyGui, web-based?)
  • How should AI assistance work? (SmartTools integration?)
  • What's the MVP feature set?
  • How do we handle 3D model preview?
  • Should we support collaborative editing?

Project Scaffold

Initial scaffold already created at ~/PycharmProjects/artifact-editor with:

  • pyproject.toml
  • Basic CLI structure
  • Renderer base class
  • Mermaid and OpenSCAD renderer stubs

Requirements

  • [Requirement 1]
  • [Requirement 2]

Open Questions

  • [Question 1]

Discussion begins below.

Name: AI-Pragmatist

Practical Shipping Analysis

This is a classic case of solving tomorrow's problems today. Let me break down what we actually need vs what's being proposed.

CONCERN: COMPLEXITY - Overscoped for Integration Need

The stated goal is "User clicks 'Add Artifact' in orchestrated-discussions." But the proposed scope includes:

  • Multiple diagram types (Mermaid, PlantUML, OpenSCAD, SVG, ASCII)
  • Voice input
  • Conversational editing
  • Live preview
  • 3D model rendering
  • Collaborative editing (in questions)

This is 6+ months of work for a feature that needs to ship in weeks.

MVP: Single Artifact Type + Text Editor

What ships in 2 weeks:

  1. Launch editor with --output-path argument
  2. Simple text editor for PlantUML/Mermaid (pick ONE)
  3. Save button that outputs ARTIFACT_SAVED:/path
  4. Exit code 0 on save, 1 on cancel

That's it. No AI, no preview, no 3D. Just a working integration.

Defer to v2:

  • AI assistance (SmartTools)
  • Live preview (nice-to-have, not blocking)
  • Additional formats (add after first one works)
  • Voice input (future)
  • 3D models (separate project)

UI Framework Decision

Simplest that works: urwid TUI

  • Already in dependency tree (orchestrated-discussions uses it)
  • Zero preview complexity (just show code)
  • Fast to build
  • Terminal-native, no GUI frameworks

Defer: Dear PyGui, web-based - these add complexity without solving the core integration need.

Architecture: Just Enough

artifact-editor --type mermaid --output diagrams/foo.mmd
→ Opens text editor
→ User types Mermaid code
→ Saves to file
→ Prints ARTIFACT_SAVED:diagrams/foo.mmd
→ Exit 0

No renderers, no preview pipeline, no AI - just a glorified text editor with contract compliance.

What Success Looks Like (v1)

User can add a diagram to a discussion comment. That's it. Ship that, get feedback, iterate.

Recommendation

Q: What's the right UI framework? A: urwid - simplest, already a dependency

Q: How should AI assistance work? A: Don't build it yet - defer to v2

Q: What's the MVP feature set? A: Text editing + save contract for ONE format

Q: How do we handle 3D preview? A: Don't - that's a v3+ feature

Q: Collaborative editing? A: Hard no for MVP

DIAGRAM: diagrams/artifact-editor-ai-enhanced-diagram-and-3d-model-creator_mvp_5.puml

VOTE: CHANGES - Scope needs 80% reduction to ship something useful

VOTE: CHANGES

Name: AI-Security

Security Analysis

I've reviewed the Artifact Editor proposal and identified several security concerns that need to be addressed:

High Priority Threats

1. Command Injection via Renderer Execution

CONCERN: PlantUML, OpenSCAD, and Mermaid renderers execute external processes. User-controlled content could escape sandboxing.

  • PlantUML Java execution with user diagrams
  • OpenSCAD code compilation and execution
  • SVG rendering with embedded scripts
  • ASCII art could contain terminal escape sequences

Mitigation: Strict input validation, sandboxed execution (containers/firejail), disable network access for renderers, CSP for web-based previews.

2. Path Traversal in File Operations

CONCERN: The --output argument could be exploited to write files outside intended directories.

artifact-editor --output ../../../etc/cron.d/backdoor

Mitigation: Validate and canonicalize all file paths, restrict writes to specific directories, check for .. sequences.

3. Voice Input Attack Surface

CONCERN: Voice-to-AI pipeline introduces new vectors:

  • Audio injection attacks
  • Prompt injection via transcribed speech
  • Privacy concerns (recording storage)

Mitigation: Sanitize transcriptions before AI processing, ephemeral audio storage, user consent for recording.

4. AI-Generated Code Execution

CONCERN: AI might generate malicious code in OpenSCAD/PlantUML that gets auto-executed.

  • OpenSCAD can read/write files
  • PlantUML can include external files
  • SVG can contain JavaScript

Mitigation: Review-before-execute workflow, static analysis of generated code, disable dangerous language features.

Medium Priority

5. Stdout/Stdin Protocol Security

The parent app integration uses stdout for communication. Malicious artifact content could inject fake protocol messages:

ARTIFACT_SAVED:/fake/path\nARTIFACT_SAVED:/actual/malicious/path

Mitigation: Structured format (JSON over stdout), message signing/verification.

6. Dependency Chain Attacks

External renderers (PlantUML JAR, OpenSCAD binary) could be compromised.

Mitigation: Checksum verification, pinned versions, consider alternative pure-Python implementations where possible.

7. Resource Exhaustion

CONCERN: Complex diagrams could cause DoS:

  • Infinite loops in OpenSCAD
  • Massive PlantUML graphs consuming memory
  • SVG bomb attacks

Mitigation: Execution timeouts, memory limits, input size restrictions.

Recommendations

For MVP:

  1. Start with read-only ASCII art and Mermaid (client-side rendering)
  2. Defer executable formats (OpenSCAD, PlantUML) until sandboxing is implemented
  3. Use JSON protocol for parent communication
  4. Implement strict path validation immediately
  5. Add --safe-mode flag that disables AI features for security-critical contexts

Architecture:

  • Separate renderer processes with minimal privileges
  • Filesystem access only to designated artifact directory
  • Network isolation for all renderers
  • Audit logging of all file operations

Voice/AI:

  • Disable by default, require explicit --enable-ai flag
  • Clear user warning about data being sent to AI providers
  • Local speech-to-text option for privacy

DIAGRAM: diagrams/artifact-editor-ai-enhanced-diagram-and-3d-model-creator_security_5.puml

VOTE: CHANGES

Name: AI-Architect

Architectural Analysis

Strong Foundation

The Unix philosophy alignment with orchestrated-discussions is excellent. The stdin/stdout/exit-code contract keeps integration clean and testable.

Critical Architectural Decisions Needed

1. UI Framework Choice Has Long-Term Implications

  • urwid TUI: Aligns with project ecosystem, SSH-friendly, but 3D preview severely limited
  • Dear PyGui: Native performance, better for 3D/live preview, but desktop-only
  • Web-based (local server): Most flexible for preview/3D, cross-platform, but adds complexity

RECOMMENDATION: Hybrid approach - TUI for text-based formats (PlantUML, Mermaid, ASCII), launch external viewer for 3D. Matches orchestrated-discussions pattern (text-first, viewer on demand).

2. Renderer Architecture

ARTIFACT: diagrams/artifact-editor-architecture.puml

Key principle: Renderers are stateless SmartTools

artifact-editor (orchestration)
  ↓ subprocess
artifact-render-{format} (SmartTools)
  ↓
External tools (plantuml.jar, mermaid-cli, openscad)

DON'T: Build rendering logic into the editor DO: Each renderer is a SmartTool that can be tested independently:

echo '@startuml\nA -> B\n@enduml' | artifact-render-plantuml > out.svg

3. AI Assistance Integration

Two architectural patterns emerge:

Pattern A: AI as orchestrator (RECOMMENDED)

  • User voice → artifact-assistant SmartTool → generates code → editor displays
  • Conversational loop: user refines → tool regenerates
  • Editor remains thin, AI in separate SmartTool

Pattern B: AI embedded in editor

  • Tighter coupling, harder to test, breaks Unix philosophy

4. State Management Concern

Current scaffold suggests single-process architecture. Consider:

  • Long-running edit sessions
  • Undo/redo state
  • Unsaved changes handling

RECOMMENDATION: File-based state

  • Auto-save to temp file (e.g., /tmp/artifact-edit-{pid}.state)
  • On crash/kill, can recover
  • Aligns with "discussion file is source of truth" principle

Architecture Risks

  1. 3D Preview Complexity: OpenSCAD rendering is SLOW. Need async architecture to prevent UI blocking.

    • Solution: Render process pool, preview throttling

  2. Voice Input Dependencies: Adds heavyweight deps (speech recognition). Could bloat the tool.

    • Solution: Separate artifact-voice SmartTool, optional integration

  3. Format Proliferation: Supporting 7+ formats means 7+ external tool dependencies.

    • Solution: Plugin architecture, core ships with Mermaid+PlantUML only

Proposed System Architecture

artifact-editor                    # Thin orchestrator (urwid TUI)
├── Core loop: edit → render → display
├── Calls SmartTools via subprocess
└── File-based state persistence

SmartTools ecosystem:
├── artifact-render-{format}       # Stateless renderers
├── artifact-assistant             # AI code generation
├── artifact-voice                 # Speech → text (optional)
└── artifact-validate-{format}     # Syntax checking

External tools (user-installed):
├── plantuml.jar
├── mermaid-cli  
├── openscad
└── dot (graphviz)

MVP Scope Recommendation

Phase 1 (MVP):

  • TUI editor (urwid)
  • Mermaid + PlantUML support (most common in orchestrated-discussions)
  • Basic artifact-assistant SmartTool (text prompt → diagram code)
  • File output contract

Phase 2:

  • OpenSCAD/3D support with external viewer
  • Voice input via artifact-voice tool
  • Live preview split-pane

Phase 3:

  • Plugin system for custom formats
  • Collaborative editing (shared state file)

Open Architectural Questions

Q1: Should artifact-editor support editing existing artifacts or only creation?

  • Editing adds complexity (need to parse existing files, detect format)
  • Creation-only is cleaner but less useful

Q2: How to handle format-specific validation?

  • Pre-render validation prevents invalid saves
  • But adds per-format complexity

Q3: Should the editor be modal (vim-style) or modeless?

  • Modal fits TUI better, smaller learning curve
  • Modeless more familiar to non-terminal users

VOTE: CHANGES

Required Decisions Before Implementation

  1. ✅ Confirm hybrid TUI + external viewer approach
  2. ✅ Confirm SmartTools-based renderer architecture
  3. ❓ Define MVP format support (recommend: Mermaid + PlantUML only)
  4. ❓ Decide on edit-existing vs. create-only
  5. ❓ Choose modal vs. modeless editing

VOTE: CHANGES