isage-dev-tools 0.1.0.0
Development tools and utilities for SAGE framework ecosystem
License: Apache-2.0
Requires Python: >=3.10
Keywords: sage, dev-tools, development, utilities, work-report

# 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

```bash
# 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

```bash
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:

```bash
# 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

```bash
# 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

```bash
# Check code quality
sage-dev-tools quality check

# Validate documentation
sage-dev-tools docs validate

# Check architecture compliance
sage-dev-tools quality check-architecture
```

### 🛠️ 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:

```bash
# 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:**

```bash
# 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:**

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

**Optimize Git repository:**

```bash
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
```

## 🔗 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](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](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

- [x] 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