Agent Integration Enhancement: Stdin/Stdout Support & Markdown Processing #1

New issue

Closed

opened 2026-05-01 22:10:09 +02:00 by kade · 0 comments

kade commented 2026-05-01 22:10:09 +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": []
}

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"

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: Agent Integration

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

Phase 4: 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

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

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

Labels

enhancement, agent-integration, stdin-stdout, markdown-processing, json-output, batch-processing

Next Steps

1. Implement stdin/stdout support in CLI
2. Add markdown document processing capabilities
3. Create JSON output format for agents
4. Add comprehensive testing for agent workflows
5. Update documentation with agent integration examples
6. Performance optimization for batch processing

# 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": [] } ``` ## 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" ### 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: Agent Integration - Design JSON schema for agent communication - Implement structured error reporting - Add performance metrics for agent workflows - Create agent-specific documentation ### Phase 4: 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 ### 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 ## 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 ## Labels enhancement, agent-integration, stdin-stdout, markdown-processing, json-output, batch-processing ## Next Steps 1. Implement stdin/stdout support in CLI 2. Add markdown document processing capabilities 3. Create JSON output format for agents 4. Add comprehensive testing for agent workflows 5. Update documentation with agent integration examples 6. Performance optimization for batch processing

kade closed this issue 2026-05-01 22:52:07 +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

Subscribe

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#1

No description provided.