SAGE Dev Tools

Development tools and utilities for the SAGE framework ecosystem.

📋 Overview

sage-dev-tools provides a comprehensive suite of development utilities for SAGE framework maintainers and contributors. This repository consolidates development scripts, maintenance tools, and reporting utilities that were previously scattered across the SAGE monorepo.

🎯 Purpose

This repository serves as a central hub for:

1. Work Report Generation - Automated weekly/monthly/quarterly/yearly reports
2. Code Maintenance - Cluster sync, Git optimization, migration scripts
3. Quality Assurance - Code quality checks and validation tools
4. Documentation Tools - Doc validation and organization utilities
5. Development Scripts - Various helper scripts for SAGE development

🚀 Installation

From PyPI

# Basic installation
pip install isage-dev-tools

# With LLM support (for AI-powered work reports)
pip install isage-dev-tools[llm]

# Development installation
pip install isage-dev-tools[dev]

# Full installation
pip install isage-dev-tools[all]

From Source

git clone https://github.com/intellistream/sage-dev-tools.git
cd sage-dev-tools
pip install -e ".[dev]"

📦 Features

🗂️ Work Report Generator

Generate comprehensive work reports with AI-powered summaries:

# Weekly report
sage-dev-tools report --period weekly

# Monthly report with AI summaries
sage-dev-tools report --period monthly --use-llm

# Custom date range
sage-dev-tools report --days 14 --output my_report.md

# Specific repositories
sage-dev-tools report --repos "SAGE,sage-examples,sagellm"

🔧 Maintenance Tools

# Sync code to cluster
sage-dev-tools maintenance sync-cluster --config cluster.yaml

# Optimize Git repository
sage-dev-tools maintenance optimize-git

# Migrate tutorials
sage-dev-tools maintenance migrate-tutorials --from SAGE --to sage-tutorials

✅ Quality Tools

# Check intermediate file placement policy
sage-dev-tools quality check-placement --project-root .

# Find orphaned Python files
sage-dev-tools quality find-orphaned --project-root . --verbose

# Batch update ruff ignore rules
sage-dev-tools quality update-ruff --rules B904,C901

# Validate documentation metadata and structure
sage-dev-tools docs validate --project-root .

🛠️ Utility Scripts

Located in scripts/ directory:

• setup_workspace.sh - Set up development workspace
• verify_compliance.sh - Verify architectural compliance
• migrate_*.sh - Various migration scripts

📖 Usage

Work Report Generation

The work report generator analyzes Git history across SAGE repositories and generates comprehensive reports:

Features:

• Multi-repository support (SAGE main + submodules)
• Configurable time periods (weekly/monthly/quarterly/yearly)
• AI-powered commit summaries (optional)
• Multiple output formats (Markdown/JSON/Console)
• Bilingual support (中文/English)

Configuration:

Create a .env file:

# GitHub Token (required for private repos)
GITHUB_TOKEN=ghp_xxx
GIT_TOKEN=ghp_xxx

# LLM Configuration (optional, for AI summaries)
SAGE_CHAT_API_KEY=sk-xxx
SAGE_CHAT_BASE_URL=https://api.openai.com/v1
SAGE_CHAT_MODEL=gpt-4

# HuggingFace (optional)
HF_TOKEN=hf_xxx

Example:

# Generate weekly report with AI summaries
sage-dev-tools report \
    --period weekly \
    --branch main-dev \
    --format markdown \
    --language zh \
    --use-llm \
    --output reports/weekly_report.md

Maintenance Operations

Sync code to remote cluster:

sage-dev-tools maintenance sync-cluster \
    --config config/cluster.yaml \
    --target node1,node2

Optimize Git repository:

sage-dev-tools maintenance optimize-git \
    --gc \
    --prune \
    --repack

🏗️ Architecture

sage-dev-tools/
├── src/sage_dev_tools/
│   ├── cli/           # CLI commands (Click)
│   ├── work_report/   # Work report generator
│   ├── maintenance/   # Maintenance tools
│   ├── quality/       # Code quality tools
│   ├── docs/          # Documentation tools
│   └── utils/         # Shared utilities
├── scripts/           # Standalone helper scripts
├── tests/             # Test suite
└── docs/              # Documentation

🧭 Boundary Contract (L5)

This repository is an L5 developer-tooling package. Boundary rules:

• In scope:
  • Cross-repository developer workflows (report, maintenance, quality, docs)
  • CLI orchestration and reusable utility modules under sage_dev_tools/*
• Out of scope:
  • Runtime/service implementations from lower layers
  • Compatibility shim layers for legacy paths
• Forbidden patterns:
  • New fallback/shim/re-export compatibility entry points
  • Silent fallback behavior that masks missing dependencies/config

Reference design notes:

• docs/adr/0001-wave-d3-quality-command-regression.md
• docs/adr/0002-wave-d1-cli-thin-layer.md

🔗 Relationship with SAGE Ecosystem

sage-tools (isage-tools)

• Purpose: Framework-integrated development CLI
• PyPI: isage-tools
• Import: sage.tools
• CLI: sage-dev
• Scope: SAGE framework development (L5 layer)

sage-dev-tools (isage-dev-tools)

• Purpose: Standalone development utilities
• PyPI: isage-dev-tools
• Import: sage_dev_tools
• CLI: sage-dev-tools
• Scope: Cross-repository maintenance and reporting

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

See CONTRIBUTING.md for details.

📝 Migration Notes

This repository consolidates tools migrated from:

• SAGE/tools/scripts/
• SAGE/tools/maintenance/
• SAGE/tools/lib/
• Workflow-embedded utilities (work report generator)

Files that remain in SAGE main repo:

• tools/install/ - Installation scripts
• tools/hooks/ - Git hooks
• tools/config/ - Project-specific configs

📄 License

Apache License 2.0 - See LICENSE

🙋 Support

• Issues: https://github.com/intellistream/sage-dev-tools/issues
• SAGE Docs: https://sage.intellistream.com
• Team Info: https://github.com/intellistream/sage-team-info

🎯 Roadmap

• Project structure setup
• Work report generator implementation
• Maintenance tools migration
• Quality tools migration
• Documentation tools
• PyPI publication
• SAGE workflow integration
• Comprehensive test coverage

---

Part of the SAGE Framework Ecosystem - https://github.com/intellistream/SAGE