paperfit-cli 1.0.0

package/scripts/render_pages.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+PDF 页图渲染器
+
+将 LaTeX 编译生成的 PDF 文件转换为逐页高分辨率 PNG 图片，
+供 layout-detective-agent 和 visual-inspector 使用。
+
+依赖:
+    - pdf2image
+    - Poppler (系统安装)
+
+用法:
+    python render_pages.py <pdf_file> [--output <dir>] [--dpi <value>] [--pages <range>]
+
+示例:
+    python render_pages.py main.pdf --output data/pages --dpi 220
+    python render_pages.py main.pdf --pages 1-5,7 --dpi 320
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import List, Optional, Tuple, Dict, Any
+
+try:
+    from pdf2image import convert_from_path
+    from PIL import Image
+except ImportError as e:
+    print(f"Error: Missing required library. {e}")
+    print("Install with: pip install pdf2image pillow")
+    sys.exit(1)
+
+
+class PDFRenderer:
+    """PDF 页图渲染器"""
+
+    def __init__(self, pdf_path: str, output_dir: str = "data/pages", dpi: int = 220):
+        self.pdf_path = Path(pdf_path)
+        self.output_dir = Path(output_dir)
+        self.dpi = dpi
+        self.page_files: List[Dict[str, Any]] = []
+        self.errors: List[str] = []
+
+    def render_pages(self, page_range: Optional[str] = None) -> Dict[str, Any]:
+        """渲染指定页码范围的页面"""
+        if not self.pdf_path.exists():
+            return {"status": "failed", "error": f"PDF not found: {self.pdf_path}"}
+
+        # 创建输出目录
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        try:
+            # 解析页码范围
+            page_numbers = self._parse_page_range(page_range)
+
+            # 渲染页面
+            pages = convert_from_path(
+                str(self.pdf_path),
+                dpi=self.dpi,
+                fmt='png',
+                thread_count=2,
+                grayscale=False,
+                first_page=min(page_numbers) if page_numbers else None,
+                last_page=max(page_numbers) if page_numbers else None
+            )
+
+            # 确定起始页码（如果指定了范围，first_page 已生效，但索引需对齐）
+            start_page = min(page_numbers) if page_numbers else 1
+
+            for i, page_image in enumerate(pages):
+                page_num = start_page + i
+                if page_numbers and page_num not in page_numbers:
+                    continue
+
+                file_name = f"page_{page_num:03d}.png"
+                file_path = self.output_dir / file_name
+                page_image.save(str(file_path), "PNG")
+
+                self.page_files.append({
+                    "page": page_num,
+                    "file": str(file_path),
+                    "width": page_image.width,
+                    "height": page_image.height
+                })
+
+            return self._build_report()
+
+        except Exception as e:
+            error_msg = f"PDF rendering failed: {str(e)}"
+            self.errors.append(error_msg)
+
+            # 检查是否是 Poppler 缺失
+            if "poppler" in str(e).lower() or "pdfinfo" in str(e).lower():
+                self.errors.append(
+                    "Poppler not found. Install with:\n"
+                    "  Ubuntu/Debian: sudo apt-get install poppler-utils\n"
+                    "  macOS: brew install poppler\n"
+                    "  Windows: download from http://blog.alivate.com.au/poppler-windows/"
+                )
+
+            return self._build_report(status="failed")
+
+    def render_cropped_region(
+        self,
+        page: int,
+        bbox: Tuple[int, int, int, int],
+        object_name: str,
+        high_dpi: int = 320
+    ) -> Optional[Dict[str, Any]]:
+        """
+        渲染指定页面的局部区域（用于表格/公式复查）
+
+        Args:
+            page: 页码
+            bbox: (x1, y1, x2, y2) 裁剪区域坐标
+            object_name: 对象标识，用于文件命名
+            high_dpi: 高精度渲染时的 DPI
+        """
+        try:
+            pages = convert_from_path(
+                str(self.pdf_path),
+                dpi=high_dpi,
+                fmt='png',
+                first_page=page,
+                last_page=page
+            )
+
+            if not pages:
+                self.errors.append(f"Page {page} not found")
+                return None
+
+            page_image = pages[0]
+            cropped = page_image.crop(bbox)
+
+            file_name = f"page_{page:03d}_{object_name}.png"
+            file_path = self.output_dir / file_name
+            cropped.save(str(file_path), "PNG")
+
+            return {
+                "page": page,
+                "object": object_name,
+                "file": str(file_path),
+                "bbox": bbox,
+                "width": cropped.width,
+                "height": cropped.height
+            }
+
+        except Exception as e:
+            self.errors.append(f"Cropped rendering failed: {str(e)}")
+            return None
+
+    def _parse_page_range(self, range_str: Optional[str]) -> List[int]:
+        """解析页码范围字符串，如 '1-5,7,9-11'"""
+        if not range_str:
+            return []
+
+        pages = set()
+        parts = range_str.split(',')
+
+        for part in parts:
+            part = part.strip()
+            if '-' in part:
+                start, end = part.split('-')
+                pages.update(range(int(start), int(end) + 1))
+            else:
+                pages.add(int(part))
+
+        return sorted(pages)
+
+    def _build_report(self, status: str = "success") -> Dict[str, Any]:
+        """构建渲染报告"""
+        report = {
+            "skill": "visual-inspector",
+            "status": status if not self.errors else "failed",
+            "pdf_path": str(self.pdf_path),
+            "output_dir": str(self.output_dir),
+            "dpi": self.dpi,
+            "pages_rendered": len(self.page_files),
+            "page_files": self.page_files,
+            "errors": self.errors
+        }
+
+        if status == "success" and not self.errors:
+            report["status"] = "success"
+        elif self.page_files and self.errors:
+            report["status"] = "partial"
+
+        return report
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Render PDF pages to PNG images for visual inspection"
+    )
+    parser.add_argument("pdf_file", help="Path to PDF file")
+    parser.add_argument("--output", "-o", default="data/pages", help="Output directory")
+    parser.add_argument("--dpi", type=int, default=220, help="Rendering DPI (default: 220)")
+    parser.add_argument("--pages", "-p", help="Page range (e.g., '1-5,7,9-11')")
+    parser.add_argument("--json", "-j", action="store_true", help="Output JSON report only")
+    parser.add_argument("--crop", help="Crop region: 'page,x1,y1,x2,y2,object_name'")
+
+    args = parser.parse_args()
+
+    renderer = PDFRenderer(args.pdf_file, args.output, args.dpi)
+
+    if args.crop:
+        # 解析裁剪参数
+        parts = args.crop.split(',')
+        if len(parts) != 6:
+            print("Error: --crop requires 'page,x1,y1,x2,y2,object_name'")
+            sys.exit(1)
+
+        page = int(parts[0])
+        bbox = (int(parts[1]), int(parts[2]), int(parts[3]), int(parts[4]))
+        object_name = parts[5]
+
+        result = renderer.render_cropped_region(page, bbox, object_name)
+        if result:
+            print(json.dumps(result, indent=2))
+        else:
+            print(json.dumps({"status": "failed", "errors": renderer.errors}, indent=2))
+            sys.exit(1)
+    else:
+        report = renderer.render_pages(args.pages)
+
+        if args.json:
+            print(json.dumps(report, indent=2, ensure_ascii=False))
+        else:
+            if report["status"] in ("success", "partial"):
+                print(f"Rendered {report['pages_rendered']} pages to {report['output_dir']}")
+                for pf in report["page_files"]:
+                    print(f"  Page {pf['page']}: {pf['file']} ({pf['width']}x{pf['height']})")
+            if report.get("errors"):
+                print("\nErrors:", file=sys.stderr)
+                for err in report["errors"]:
+                    print(f"  - {err}", file=sys.stderr)
+
+        sys.exit(0 if report["status"] == "success" else 1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/session_logger.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+PaperFit Session Logger
+
+Provides observability for PaperFit agent sessions.
+Inspired by ECC's observability features (dimension 8).
+
+Features:
+- Session-level logging
+- Agent decision tracking
+- Token usage estimation
+- Metrics collection
+
+Usage:
+    python session_logger.py start <session_id>
+    python session_logger.py log <session_id> <message>
+    python session_logger.py track <session_id> <agent> <action>
+    python session_logger.py metrics <session_id>
+    python session_logger.py export <session_id>
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+# Session log directory
+LOG_DIR = Path(__file__).parent.parent / 'data' / 'logs'
+LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+class SessionLogger:
+    """Manages session logging and metrics collection."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        self.log_file = LOG_DIR / f'{session_id}.jsonl'
+        self.meta_file = LOG_DIR / f'{session_id}.meta.json'
+
+    def start(self, user_id: str = 'anonymous', project: str = None):
+        """Initialize a new session."""
+        meta = {
+            'session_id': self.session_id,
+            'user_id': user_id,
+            'project': project,
+            'started_at': datetime.utcnow().isoformat(),
+            'ended_at': None,
+            'status': 'active',
+            'events': [],
+            'agents': {},
+            'metrics': {
+                'total_events': 0,
+                'agent_calls': 0,
+                'file_edits': 0,
+                'compile_runs': 0,
+                'visual_defects_found': 0,
+                'visual_defects_fixed': 0,
+                'iterations': 0
+            }
+        }
+
+        with open(self.meta_file, 'w', encoding='utf-8') as f:
+            json.dump(meta, f, indent=2)
+
+        # Write initial log entry
+        self._log_event('session_start', {
+            'user_id': user_id,
+            'project': project
+        })
+
+        print(f"✅ Session started: {self.session_id}")
+        print(f"   Log file: {self.log_file}")
+        print(f"   Meta file: {self.meta_file}")
+        return meta
+
+    def _log_event(self, event_type: str, data: dict):
+        """Append an event to the session log."""
+        event = {
+            'timestamp': datetime.utcnow().isoformat(),
+            'event_type': event_type,
+            'data': data
+        }
+
+        with open(self.log_file, 'a', encoding='utf-8') as f:
+            f.write(json.dumps(event) + '\n')
+
+        # Update meta
+        if self.meta_file.exists():
+            with open(self.meta_file, 'r', encoding='utf-8') as f:
+                meta = json.load(f)
+
+            meta['events'].append(event_type)
+            meta['metrics']['total_events'] += 1
+
+            with open(self.meta_file, 'w', encoding='utf-8') as f:
+                json.dump(meta, f, indent=2)
+
+    def log(self, message: str, category: str = 'info'):
+        """Log a general message."""
+        self._log_event(category, {'message': message})
+        print(f"[{category.upper()}] {message}")
+
+    def track_agent(self, agent_name: str, action: str, details: dict = None):
+        """Track an agent invocation."""
+        event_data = {
+            'agent': agent_name,
+            'action': action,
+            'details': details or {}
+        }
+        self._log_event('agent_call', event_data)
+
+        # Update agent stats
+        if self.meta_file.exists():
+            with open(self.meta_file, 'r', encoding='utf-8') as f:
+                meta = json.load(f)
+
+            if agent_name not in meta['agents']:
+                meta['agents'][agent_name] = {'calls': 0, 'actions': {}}
+
+            meta['agents'][agent_name]['calls'] += 1
+            if action not in meta['agents'][agent_name]['actions']:
+                meta['agents'][agent_name]['actions'][action] = 0
+            meta['agents'][agent_name]['actions'][action] += 1
+            meta['metrics']['agent_calls'] += 1
+
+            with open(self.meta_file, 'w', encoding='utf-8') as f:
+                json.dump(meta, f, indent=2)
+
+    def track_file_edit(self, file_path: str, reason: str):
+        """Track a file edit."""
+        self._log_event('file_edit', {
+            'file': file_path,
+            'reason': reason
+        })
+
+        if self.meta_file.exists():
+            with open(self.meta_file, 'r', encoding='utf-8') as f:
+                meta = json.load(f)
+            meta['metrics']['file_edits'] += 1
+            with open(self.meta_file, 'w', encoding='utf-8') as f:
+                json.dump(meta, f, indent=2)
+
+    def track_compile(self, success: bool, errors: list = None):
+        """Track a compilation run."""
+        self._log_event('compile', {
+            'success': success,
+            'errors': errors or []
+        })
+
+        if self.meta_file.exists():
+            with open(self.meta_file, 'r', encoding='utf-8') as f:
+                meta = json.load(f)
+            meta['metrics']['compile_runs'] += 1
+            with open(self.meta_file, 'w', encoding='utf-8') as f:
+                json.dump(meta, f, indent=2)
+
+    def track_defect(self, category: str, page: int, severity: str, fixed: bool = False):
+        """Track a visual defect."""
+        self._log_event('defect', {
+            'category': category,
+            'page': page,
+            'severity': severity,
+            'fixed': fixed
+        })
+
+        if self.meta_file.exists():
+            with open(self.meta_file, 'r', encoding='utf-8') as f:
+                meta = json.load(f)
+
+            if fixed:
+                meta['metrics']['visual_defects_fixed'] += 1
+            else:
+                meta['metrics']['visual_defects_found'] += 1
+
+            with open(self.meta_file, 'w', encoding='utf-8') as f:
+                json.dump(meta, f, indent=2)
+
+    def track_iteration(self, round_num: int, status: str):
+        """Track an iteration round."""
+        self._log_event('iteration', {
+            'round': round_num,
+            'status': status
+        })
+
+        if self.meta_file.exists():
+            with open(self.meta_file, 'r', encoding='utf-8') as f:
+                meta = json.load(f)
+            meta['metrics']['iterations'] += 1
+            with open(self.meta_file, 'w', encoding='utf-8') as f:
+                json.dump(meta, f, indent=2)
+
+    def end(self, status: str = 'completed'):
+        """End the session."""
+        self._log_event('session_end', {'status': status})
+
+        if self.meta_file.exists():
+            with open(self.meta_file, 'r', encoding='utf-8') as f:
+                meta = json.load(f)
+
+            meta['ended_at'] = datetime.utcnow().isoformat()
+            meta['status'] = status
+
+            with open(self.meta_file, 'w', encoding='utf-8') as f:
+                json.dump(meta, f, indent=2)
+
+        print(f"✅ Session ended: {self.session_id} ({status})")
+
+    def get_metrics(self) -> dict:
+        """Get session metrics."""
+        if not self.meta_file.exists():
+            return {'error': 'Session not found'}
+
+        with open(self.meta_file, 'r', encoding='utf-8') as f:
+            meta = json.load(f)
+
+        return {
+            'session_id': meta['session_id'],
+            'duration': self._calculate_duration(meta['started_at'], meta['ended_at']),
+            'status': meta['status'],
+            'metrics': meta['metrics'],
+            'agents': meta['agents']
+        }
+
+    def _calculate_duration(self, start: str, end: Optional[str]) -> str:
+        """Calculate session duration."""
+        try:
+            start_dt = datetime.fromisoformat(start)
+            end_dt = datetime.fromisoformat(end) if end else datetime.utcnow()
+            duration = end_dt - start_dt
+            return str(duration)
+        except Exception:
+            return 'unknown'
+
+    def export(self) -> str:
+        """Export full session data."""
+        if not self.meta_file.exists():
+            return json.dumps({'error': 'Session not found'})
+
+        # Load meta
+        with open(self.meta_file, 'r', encoding='utf-8') as f:
+            meta = json.load(f)
+
+        # Load events
+        events = []
+        if self.log_file.exists():
+            with open(self.log_file, 'r', encoding='utf-8') as f:
+                for line in f:
+                    events.append(json.loads(line))
+
+        return json.dumps({
+            'meta': meta,
+            'events': events,
+            'event_count': len(events)
+        }, indent=2, default=str)
+
+
+def generate_session_id() -> str:
+    """Generate a unique session ID."""
+    return datetime.utcnow().strftime('%Y%m%d_%H%M%S')
+
+
+def main():
+    parser = argparse.ArgumentParser(description='PaperFit Session Logger')
+    parser.add_argument('command', choices=['start', 'log', 'track', 'metrics', 'export', 'end'])
+    parser.add_argument('session_id', nargs='?', help='Session ID')
+    parser.add_argument('--user', default='anonymous', help='User ID')
+    parser.add_argument('--project', help='Project name')
+    parser.add_argument('--message', help='Log message')
+    parser.add_argument('--category', default='info', help='Log category')
+    parser.add_argument('--agent', help='Agent name')
+    parser.add_argument('--action', help='Agent action')
+    parser.add_argument('--details', help='Agent action details (JSON)')
+    parser.add_argument('--file', help='File path for file edit')
+    parser.add_argument('--reason', help='Reason for file edit')
+    parser.add_argument('--status', default='completed', help='End status')
+
+    args = parser.parse_args()
+
+    if args.command == 'start':
+        session_id = args.session_id or generate_session_id()
+        logger = SessionLogger(session_id)
+        logger.start(args.user, args.project)
+
+    elif args.command == 'log':
+        if not args.session_id:
+            print('Error: session_id required')
+            sys.exit(1)
+        logger = SessionLogger(args.session_id)
+        logger.log(args.message or 'No message', args.category)
+
+    elif args.command == 'track':
+        if not args.session_id:
+            print('Error: session_id required')
+            sys.exit(1)
+        logger = SessionLogger(args.session_id)
+        if args.agent and args.action:
+            details = json.loads(args.details) if args.details else None
+            logger.track_agent(args.agent, args.action, details)
+        else:
+            print('Error: --agent and --action required')
+            sys.exit(1)
+
+    elif args.command == 'metrics':
+        if not args.session_id:
+            print('Error: session_id required')
+            sys.exit(1)
+        logger = SessionLogger(args.session_id)
+        metrics = logger.get_metrics()
+        print(json.dumps(metrics, indent=2, default=str))
+
+    elif args.command == 'export':
+        if not args.session_id:
+            print('Error: session_id required')
+            sys.exit(1)
+        logger = SessionLogger(args.session_id)
+        print(logger.export())
+
+    elif args.command == 'end':
+        if not args.session_id:
+            print('Error: session_id required')
+            sys.exit(1)
+        logger = SessionLogger(args.session_id)
+        logger.end(args.status)
+
+
+if __name__ == '__main__':
+    main()