kade/tamamo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Agent Integration Enhancement: Stdin/Stdout Support & Markdown Processing (Fox-Style CLI) #2

New issue
Closed
opened 2026-05-01 22:18:39 +02:00 by kade · 0 comments
kade commented 2026-05-01 22:18:39 +02:00
Owner
Copy link

Agent Integration Enhancement: Stdin/Stdout Support & Markdown Processing

Overview

Enhance Tamamo to support direct agent interaction without file writing requirements, including stdin/stdout workflows and markdown document processing.

Current Limitations

  • Agents must write temporary files for diagram validation
  • No direct stdin/stdout support for agent workflows
  • Cannot process markdown documents with embedded diagrams
  • Missing agent-friendly JSON output formats
  • No EOF-based batch processing for multiple diagrams

Proposed Features

1. Stdin/Stdout Support

Validation via stdin:

echo "flowchart TD\n    A --> B" | tamamo validate --stdin

Rendering via stdin to stdout:

echo "flowchart TD\n    A --> B" | tamamo render --stdin --output -

2. Markdown Document Processing

Extract and validate all diagrams:

tamamo validate --markdown document.md

Render all diagrams from markdown:

tamamo render --markdown document.md --output-dir images/

3. EOF Batch Processing

Multiple diagrams with EOF separator:

tamamo validate --batch-eof

4. Agent-Friendly JSON Output

Structured validation results:

tamamo validate --json --stdin

Output format:

{
  "valid": true,
  "diagrams": [
    {
      "index": 0,
      "valid": true,
      "type": "flowchart",
      "warnings": []
    }
  ],
  "errors": []
}

5. Fox-Style CLI Experience

Colorful, human-first design following 2026 CLI principles:

Based on research from CLI Guidelines and Atlassian's 10 CLI Design Principles:

  • Human-first design: Traditional UNIX philosophy updated for modern agents
  • Consistency across programs: Follow established CLI conventions
  • Visual progress indicators: Progress bars and spinners for long operations
  • Clear error messages: Human-readable with actionable suggestions
  • Support skim-readers: Concise output with visual emphasis

Implementation:

# Colorful output with emoji indicators
✅ Rendered to examples/agent_workflow.svg
   Format: svg
   Size: 28626 bytes
⏳ Processing markdown document...
🔍 Found 3 diagrams in document
❌ Parse error on line 4: Invalid syntax
💡 Suggestion: Check arrow syntax and node formatting

Research Sources

Agent Integration Patterns (2026)

CLI Agent Workflows

CLI Design Principles (2026)

  • clig.dev: "Command Line Interface Guidelines"

    • URL: https://clig.dev/
    • Key insights:
      • "Human-first design: Traditionally, UNIX commands were written under assumption they were going to be used primarily by other programs. Today, even though many CLI programs are used primarily (or even exclusively) by humans, a lot of their interaction design still carries baggage of the past. It's time to shed some of this baggage"
      • "Simple parts that work together: A core tenet of the original UNIX philosophy is the idea that small, simple programs with clean interfaces can be combined to build larger systems"
      • "Consistency across programs: The terminal's conventions are hardwired into our fingers. We had to pay an upfront cost by learning about command line syntax, flags, environment variables and so on, but it pays off in long-term efficiency"

  • Atlassian: "10 design principles for delightful CLIs"

    • URL: https://www.atlassian.com/blog/it-teams/10-design-principles-for-delightful-clis
    • Key insights:
      • "Align with established conventions: CLIs have pretty much been around since the dawn of computers themselves, so you don't need to reinvent the wheel to create a crowd-pleasing experience"
      • "Build --help into CLI: Adding a --help command to your CLI provides users with an essential piece of documentation"
      • "Show progress visually: Without a Graphical User Interface (GUI) to provide immediate visual feedback, CLIs don't always do a good job of keeping users informed about what's going on behind the scenes"
      • "Create a reaction for every action: For every action a user performs, your CLI should provide an equal and appropriate reaction, clearly highlighting the current system status"
      • "Craft human-readable error messages: Errors are expected and even an essential part of using any CLI. To help the user get back on track as quickly as possible, every error message that your CLI displays should not only contain a written description of what's gone wrong but also include suggestions for how to fix it"

Markdown Mermaid Processing

Implementation Plan

Phase 1: Stdin/Stdout Support

  • Add --stdin flag to validate and render commands
  • Implement --output - for stdout rendering
  • Add EOF detection for batch processing
  • Create JSON output format option

Phase 2: Markdown Processing

  • Implement markdown parser for mermaid block extraction
  • Add --markdown flag for document processing
  • Support multiple diagram extraction and validation
  • Create batch rendering from markdown sources

Phase 3: Fox-Style CLI Enhancement

  • Add colorful output with emoji indicators
  • Implement progress bars for long operations
  • Create human-readable error messages with suggestions
  • Add visual feedback for every action
  • Support skim-reading with concise output

Phase 4: Agent Integration

  • Design JSON schema for agent communication
  • Implement structured error reporting
  • Add performance metrics for agent workflows
  • Create agent-specific documentation

Phase 5: Testing & Documentation

  • Add comprehensive tests for stdin/stdout workflows
  • Create agent integration examples
  • Update CLI documentation with agent patterns
  • Add performance benchmarks

Technical Requirements

Dependencies

  • markdown: Python package for markdown parsing
  • beautifulsoup4: HTML processing for mermaid extraction
  • json-schema: Validation for agent communication
  • rich: Terminal formatting and progress bars
  • click: Enhanced CLI argument parsing

CLI Enhancements

# New command options
tamamo validate --stdin --json
tamamo render --stdin --output -
tamamo validate --markdown document.md
tamamo render --markdown document.md --output-dir images/
tamamo validate --batch-eof

API Changes

  • Enhanced TamamoValidator.validate_syntax() for stdin input
  • New extract_mermaid_from_markdown() function
  • JSON result formatting utilities
  • EOF batch processing logic
  • Colorful output formatting with rich library

Mermaid Diagrams

Agent Workflow Integration

flowchart TD
    A[Agent Input] --> B{Input Type}
    B -->|Stdin| C[Direct Processing]
    B -->|Markdown| D[Extract Diagrams]
    C --> E[Validate Syntax]
    D --> F[Parse Blocks]
    E --> G{Valid?}
    F --> G
    G -->|Yes| H[Render Output]
    G -->|No| I[Show Errors]
    H --> J[Return Result]
    I --> J
    J --> K[Agent Feedback]
    K --> L[Next Action]
    style A fill:#ff9999,stroke:#333,stroke-width:2px
    style B fill:#ffcc99,stroke:#333,stroke-width:2px
    style C fill:#99ff99,stroke:#333,stroke-width:2px
    style D fill:#99ff99,stroke:#333,stroke-width:2px
    style E fill:#ccffcc,stroke:#333,stroke-width:2px
    style F fill:#ccffcc,stroke:#333,stroke-width:2px
    style G fill:#ffcccc,stroke:#333,stroke-width:2px
    style H fill:#99ccff,stroke:#333,stroke-width:2px
    style I fill:#ff9999,stroke:#333,stroke-width:2px
    style J fill:#ccffcc,stroke:#333,stroke-width:2px
    style K fill:#ffcc99,stroke:#333,stroke-width:2px
    style L fill:#99ff99,stroke:#333,stroke-width:2px

Stdin Workflow

flowchart TD
    A[Agent] --> B["echo diagram"]
    B --> C["tamamo validate --stdin"]
    C --> D{Valid?}
    D -->|Yes| E[Continue]
    D -->|No| F[Error Message]
    E --> G[Next Step]
    F --> G
    style A fill:#ff6b6b,stroke:#333,stroke-width:2px
    style B fill:#4ecdc4,stroke:#333,stroke-width:2px
    style C fill:#45b7d1,stroke:#333,stroke-width:2px
    style D fill:#96ceb4,stroke:#333,stroke-width:2px
    style E fill:#45b7d1,stroke:#333,stroke-width:2px
    style F fill:#ff6b6b,stroke:#333,stroke-width:2px
    style G fill:#4ecdc4,stroke:#333,stroke-width:2px

Markdown Processing

flowchart TD
    A[Markdown File] --> B[Parser]
    B --> C{Contains ```mermaid?}
    C -->|Yes| D[Extract Blocks]
    C -->|No| E[Skip Processing]
    D --> F[Validate Each]
    F --> G{All Valid?}
    G -->|Yes| H[Render All]
    G -->|No| I[Show Errors]
    H --> J[Output Files]
    I --> J
    E --> K[Continue]
    style A fill:#e1f5fe,stroke:#333,stroke-width:2px
    style B fill:#a8dadc,stroke:#333,stroke-width:2px
    style C fill:#ffd93d,stroke:#333,stroke-width:2px
    style D fill:#6bcf7f,stroke:#333,stroke-width:2px
    style E fill:#e74c3c,stroke:#333,stroke-width:2px
    style F fill:#4caf50,stroke:#333,stroke-width:2px
    style G fill:#ff9800,stroke:#333,stroke-width:2px
    style H fill:#4caf50,stroke:#333,stroke-width:2px
    style I fill:#f44336,stroke:#333,stroke-width:2px
    style J fill:#2196f3,stroke:#333,stroke-width:2px
    style K fill:#9e9e9e,stroke:#333,stroke-width:2px

JSON Output Format

flowchart TD
    A[Agent Request] --> B[Tamamo CLI]
    B --> C[Validate Diagram]
    C --> D{JSON Output?}
    D -->|Yes| E[Return JSON]
    D -->|No| F[Return Text]
    E --> G[Parse Response]
    F --> G
    G --> H[Agent Processing]
    H --> I[Next Action]
    style A fill:#9c27b0,stroke:#333,stroke-width:2px
    style B fill:#03a9f4,stroke:#333,stroke-width:2px
    style C fill:#27ae60,stroke:#333,stroke-width:2px
    style D fill:#f39c12,stroke:#333,stroke-width:2px
    style E fill:#27ae60,stroke:#333,stroke-width:2px
    style F fill:#dc3545,stroke:#333,stroke-width:2px
    style G fill:#27ae60,stroke:#333,stroke-width:2px
    style H fill:#03a9f4,stroke:#333,stroke-width:2px
    style I fill:#9c27b0,stroke:#333,stroke-width:2px

Integration Points

Windsurf/Cascade Agents

  • Direct stdin/stdout communication
  • JSON-based result processing
  • Error handling for agent workflows
  • Performance optimization for batch processing

Forgejo Client Integration

  • Enhanced issue creation with diagram validation
  • Markdown document processing in issue descriptions
  • Batch diagram validation in pull requests
  • Automated diagram rendering in documentation

.windsurf Skills Integration

  • autumn-palette skill integration
  • Agent workflow examples
  • Template generation for common patterns
  • Error recovery and suggestion systems

Success Metrics

  • Agent Integration: 100% stdin/stdout workflow support
  • Markdown Processing: Support for embedded diagram extraction
  • Performance: <50ms validation time for single diagrams
  • Compatibility: Full backward compatibility with existing CLI
  • Documentation: Complete agent integration guide
  • Fox-Style UX: Colorful output with progress indicators and human-readable errors

Labels

enhancement, agent-integration, stdin-stdout, markdown-processing, json-output, batch-processing, fox-style-cli, colorful-output

Next Steps

  1. Implement stdin/stdout support in CLI
  2. Add markdown document processing capabilities
  3. Create JSON output format for agents
  4. Add fox-style colorful output with progress indicators
  5. Add comprehensive testing for agent workflows
  6. Update documentation with agent integration examples
  7. Performance optimization for batch processing
  8. Create examples directory with rendered diagrams
  9. Add pycache to .gitignore

Bonus Challenge: Self-Rendering

All mermaid diagrams in this issue were created and rendered using Tamamo itself:

  • agent_workflow.svg: 28,626 bytes
  • stdin_workflow.svg: 19,701 bytes
  • markdown_processing.svg: 26,205 bytes
  • json_output.svg: 22,817 bytes

Files saved in ./tools/tamamo/examples/ directory with .gitignore cleanup.

# Agent Integration Enhancement: Stdin/Stdout Support & Markdown Processing ## Overview Enhance Tamamo to support direct agent interaction without file writing requirements, including stdin/stdout workflows and markdown document processing. ## Current Limitations - Agents must write temporary files for diagram validation - No direct stdin/stdout support for agent workflows - Cannot process markdown documents with embedded diagrams - Missing agent-friendly JSON output formats - No EOF-based batch processing for multiple diagrams ## Proposed Features ### 1. Stdin/Stdout Support **Validation via stdin:** ```bash echo "flowchart TD\n A --> B" | tamamo validate --stdin ``` **Rendering via stdin to stdout:** ```bash echo "flowchart TD\n A --> B" | tamamo render --stdin --output - ``` ### 2. Markdown Document Processing **Extract and validate all diagrams:** ```bash tamamo validate --markdown document.md ``` **Render all diagrams from markdown:** ```bash tamamo render --markdown document.md --output-dir images/ ``` ### 3. EOF Batch Processing **Multiple diagrams with EOF separator:** ```bash tamamo validate --batch-eof ``` ### 4. Agent-Friendly JSON Output **Structured validation results:** ```bash tamamo validate --json --stdin ``` Output format: ```json { "valid": true, "diagrams": [ { "index": 0, "valid": true, "type": "flowchart", "warnings": [] } ], "errors": [] } ``` ### 5. Fox-Style CLI Experience **Colorful, human-first design following 2026 CLI principles:** Based on research from [CLI Guidelines](https://clig.dev/) and [Atlassian's 10 CLI Design Principles](https://www.atlassian.com/blog/it-teams/10-design-principles-for-delightful-clis): - **Human-first design**: Traditional UNIX philosophy updated for modern agents - **Consistency across programs**: Follow established CLI conventions - **Visual progress indicators**: Progress bars and spinners for long operations - **Clear error messages**: Human-readable with actionable suggestions - **Support skim-readers**: Concise output with visual emphasis **Implementation:** ```bash # Colorful output with emoji indicators ✅ Rendered to examples/agent_workflow.svg Format: svg Size: 28626 bytes ⏳ Processing markdown document... 🔍 Found 3 diagrams in document ❌ Parse error on line 4: Invalid syntax 💡 Suggestion: Check arrow syntax and node formatting ``` ## Research Sources ### Agent Integration Patterns (2026) - **Composio**: "APIs for AI Agents: The 5 Integration Patterns" - URL: https://composio.dev/content/apis-ai-agents-integration-patterns - Key insight: "The LLM analyzes the user's request and outputs structured JSON that specifies which tool to call and arguments to pass" ### CLI Agent Workflows - **Medium**: "CLI Based AI Agent: Tool Calling with CLI" - URL: https://medium.com/@visrow/cli-based-ai-agent-tool-calling-with-cli-19d773add372 - Key insight: "Chain CLIs by connecting stdout to stdin" ### CLI Design Principles (2026) - **clig.dev**: "Command Line Interface Guidelines" - URL: https://clig.dev/ - Key insights: - "Human-first design: Traditionally, UNIX commands were written under assumption they were going to be used primarily by other programs. Today, even though many CLI programs are used primarily (or even exclusively) by humans, a lot of their interaction design still carries baggage of the past. It's time to shed some of this baggage" - "Simple parts that work together: A core tenet of the original UNIX philosophy is the idea that small, simple programs with clean interfaces can be combined to build larger systems" - "Consistency across programs: The terminal's conventions are hardwired into our fingers. We had to pay an upfront cost by learning about command line syntax, flags, environment variables and so on, but it pays off in long-term efficiency" - **Atlassian**: "10 design principles for delightful CLIs" - URL: https://www.atlassian.com/blog/it-teams/10-design-principles-for-delightful-clis - Key insights: - "Align with established conventions: CLIs have pretty much been around since the dawn of computers themselves, so you don't need to reinvent the wheel to create a crowd-pleasing experience" - "Build --help into CLI: Adding a --help command to your CLI provides users with an essential piece of documentation" - "Show progress visually: Without a Graphical User Interface (GUI) to provide immediate visual feedback, CLIs don't always do a good job of keeping users informed about what's going on behind the scenes" - "Create a reaction for every action: For every action a user performs, your CLI should provide an equal and appropriate reaction, clearly highlighting the current system status" - "Craft human-readable error messages: Errors are expected and even an essential part of using any CLI. To help the user get back on track as quickly as possible, every error message that your CLI displays should not only contain a written description of what's gone wrong but also include suggestions for how to fix it" ### Markdown Mermaid Processing - **md-mermaid PyPI**: Python-Markdown extension for Mermaid diagram extraction - URL: https://pypi.org/project/md-mermaid/ - Key insight: "Extension to add support for mermaid graph inside markdown file" - **PyMdown Extensions**: Advanced Mermaid processing - URL: https://facelessuser.github.io/pymdown-extensions/extras/mermaid/ - Key insight: "Custom loader for personal aesthetics to render diagrams in code blocks" ## Implementation Plan ### Phase 1: Stdin/Stdout Support - Add `--stdin` flag to validate and render commands - Implement `--output -` for stdout rendering - Add EOF detection for batch processing - Create JSON output format option ### Phase 2: Markdown Processing - Implement markdown parser for mermaid block extraction - Add `--markdown` flag for document processing - Support multiple diagram extraction and validation - Create batch rendering from markdown sources ### Phase 3: Fox-Style CLI Enhancement - Add colorful output with emoji indicators - Implement progress bars for long operations - Create human-readable error messages with suggestions - Add visual feedback for every action - Support skim-reading with concise output ### Phase 4: Agent Integration - Design JSON schema for agent communication - Implement structured error reporting - Add performance metrics for agent workflows - Create agent-specific documentation ### Phase 5: Testing & Documentation - Add comprehensive tests for stdin/stdout workflows - Create agent integration examples - Update CLI documentation with agent patterns - Add performance benchmarks ## Technical Requirements ### Dependencies - **markdown**: Python package for markdown parsing - **beautifulsoup4**: HTML processing for mermaid extraction - **json-schema**: Validation for agent communication - **rich**: Terminal formatting and progress bars - **click**: Enhanced CLI argument parsing ### CLI Enhancements ```bash # New command options tamamo validate --stdin --json tamamo render --stdin --output - tamamo validate --markdown document.md tamamo render --markdown document.md --output-dir images/ tamamo validate --batch-eof ``` ### API Changes - Enhanced `TamamoValidator.validate_syntax()` for stdin input - New `extract_mermaid_from_markdown()` function - JSON result formatting utilities - EOF batch processing logic - Colorful output formatting with rich library ## Mermaid Diagrams ### Agent Workflow Integration ```mermaid flowchart TD A[Agent Input] --> B{Input Type} B -->|Stdin| C[Direct Processing] B -->|Markdown| D[Extract Diagrams] C --> E[Validate Syntax] D --> F[Parse Blocks] E --> G{Valid?} F --> G G -->|Yes| H[Render Output] G -->|No| I[Show Errors] H --> J[Return Result] I --> J J --> K[Agent Feedback] K --> L[Next Action] style A fill:#ff9999,stroke:#333,stroke-width:2px style B fill:#ffcc99,stroke:#333,stroke-width:2px style C fill:#99ff99,stroke:#333,stroke-width:2px style D fill:#99ff99,stroke:#333,stroke-width:2px style E fill:#ccffcc,stroke:#333,stroke-width:2px style F fill:#ccffcc,stroke:#333,stroke-width:2px style G fill:#ffcccc,stroke:#333,stroke-width:2px style H fill:#99ccff,stroke:#333,stroke-width:2px style I fill:#ff9999,stroke:#333,stroke-width:2px style J fill:#ccffcc,stroke:#333,stroke-width:2px style K fill:#ffcc99,stroke:#333,stroke-width:2px style L fill:#99ff99,stroke:#333,stroke-width:2px ``` ### Stdin Workflow ```mermaid flowchart TD A[Agent] --> B["echo diagram"] B --> C["tamamo validate --stdin"] C --> D{Valid?} D -->|Yes| E[Continue] D -->|No| F[Error Message] E --> G[Next Step] F --> G style A fill:#ff6b6b,stroke:#333,stroke-width:2px style B fill:#4ecdc4,stroke:#333,stroke-width:2px style C fill:#45b7d1,stroke:#333,stroke-width:2px style D fill:#96ceb4,stroke:#333,stroke-width:2px style E fill:#45b7d1,stroke:#333,stroke-width:2px style F fill:#ff6b6b,stroke:#333,stroke-width:2px style G fill:#4ecdc4,stroke:#333,stroke-width:2px ``` ### Markdown Processing ```mermaid flowchart TD A[Markdown File] --> B[Parser] B --> C{Contains ```mermaid?} C -->|Yes| D[Extract Blocks] C -->|No| E[Skip Processing] D --> F[Validate Each] F --> G{All Valid?} G -->|Yes| H[Render All] G -->|No| I[Show Errors] H --> J[Output Files] I --> J E --> K[Continue] style A fill:#e1f5fe,stroke:#333,stroke-width:2px style B fill:#a8dadc,stroke:#333,stroke-width:2px style C fill:#ffd93d,stroke:#333,stroke-width:2px style D fill:#6bcf7f,stroke:#333,stroke-width:2px style E fill:#e74c3c,stroke:#333,stroke-width:2px style F fill:#4caf50,stroke:#333,stroke-width:2px style G fill:#ff9800,stroke:#333,stroke-width:2px style H fill:#4caf50,stroke:#333,stroke-width:2px style I fill:#f44336,stroke:#333,stroke-width:2px style J fill:#2196f3,stroke:#333,stroke-width:2px style K fill:#9e9e9e,stroke:#333,stroke-width:2px ``` ### JSON Output Format ```mermaid flowchart TD A[Agent Request] --> B[Tamamo CLI] B --> C[Validate Diagram] C --> D{JSON Output?} D -->|Yes| E[Return JSON] D -->|No| F[Return Text] E --> G[Parse Response] F --> G G --> H[Agent Processing] H --> I[Next Action] style A fill:#9c27b0,stroke:#333,stroke-width:2px style B fill:#03a9f4,stroke:#333,stroke-width:2px style C fill:#27ae60,stroke:#333,stroke-width:2px style D fill:#f39c12,stroke:#333,stroke-width:2px style E fill:#27ae60,stroke:#333,stroke-width:2px style F fill:#dc3545,stroke:#333,stroke-width:2px style G fill:#27ae60,stroke:#333,stroke-width:2px style H fill:#03a9f4,stroke:#333,stroke-width:2px style I fill:#9c27b0,stroke:#333,stroke-width:2px ``` ## Integration Points ### Windsurf/Cascade Agents - Direct stdin/stdout communication - JSON-based result processing - Error handling for agent workflows - Performance optimization for batch processing ### Forgejo Client Integration - Enhanced issue creation with diagram validation - Markdown document processing in issue descriptions - Batch diagram validation in pull requests - Automated diagram rendering in documentation ### .windsurf Skills Integration - autumn-palette skill integration - Agent workflow examples - Template generation for common patterns - Error recovery and suggestion systems ## Success Metrics - **Agent Integration**: 100% stdin/stdout workflow support - **Markdown Processing**: Support for embedded diagram extraction - **Performance**: <50ms validation time for single diagrams - **Compatibility**: Full backward compatibility with existing CLI - **Documentation**: Complete agent integration guide - **Fox-Style UX**: Colorful output with progress indicators and human-readable errors ## Labels enhancement, agent-integration, stdin-stdout, markdown-processing, json-output, batch-processing, fox-style-cli, colorful-output ## Next Steps 1. Implement stdin/stdout support in CLI 2. Add markdown document processing capabilities 3. Create JSON output format for agents 4. Add fox-style colorful output with progress indicators 5. Add comprehensive testing for agent workflows 6. Update documentation with agent integration examples 7. Performance optimization for batch processing 8. Create examples directory with rendered diagrams 9. Add __pycache__ to .gitignore ## Bonus Challenge: Self-Rendering All mermaid diagrams in this issue were created and rendered using Tamamo itself: - **agent_workflow.svg**: 28,626 bytes - **stdin_workflow.svg**: 19,701 bytes - **markdown_processing.svg**: 26,205 bytes - **json_output.svg**: 22,817 bytes Files saved in `./tools/tamamo/examples/` directory with `.gitignore` cleanup.
kade closed this issue 2026-05-01 22:52:34 +02:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
kade/tamamo#2
No description provided.