SynTechRev-PolyCodCal

Polymathic CodCal - A feedback monitoring system with sliding-window aggregation and alerting, including legal data ingestion and processing capabilities.

Install & CLI Quickstart

Install from PyPI (example)

Replace syntechrev-polycodcal with the actual package name if different.

pip install syntechrev-polycodcal

CLI Quickstart

The package provides three command-line entry points:

• syntech-monitor — monitor & feedback tooling
• genesis-gateway — gateway interface
• legal-generator — legal data generator CLI

Try the built-in help:

syntech-monitor --help
genesis-gateway --help
legal-generator --help

Example: run a quick help check locally (after installing dev deps)

git checkout main
git pull origin main
python -m venv .venv
.\.venv\Scripts\Activate.ps1    # Windows PowerShell
pip install -e ".[dev]"
syntech-monitor --help

📦 Installation

From Source (Development)

git clone https://github.com/SynTechRev/SynTechRev-PolyCodCal.git
cd SynTechRev-PolyCodCal
pip install -e .

From PyPI (Coming Soon - Phase 7)

pip install syntechrev-polycodcal

🚀 Quick Start

⚠️ Having VS Code sync issues? See Environment Reset Guide for restoring a clean local state aligned with main.

New to the project? Start here:

• GETTING_STARTED.md - Complete setup guide with VS Code & Copilot integration
• QUICKSTART.md - Alternative 5-minute setup guide

Quick Setup

Set up the workspace virtual environment (we use .venv):

python -m venv .venv

# On Windows
.venv\Scripts\Activate.ps1

# On macOS/Linux
source .venv/bin/activate

pip install -r dev-requirements.txt

Run tests:

# The src directory is automatically added to PYTHONPATH in VS Code
# For command-line testing:
PYTHONPATH=src pytest -v

Run pre-commit hooks locally:

pre-commit run --all-files

VS Code Setup (Recommended)

This project is fully configured for VS Code with GitHub Copilot:

1. Open in VS Code: code . or code SynTechRev-PolyCodCal.code-workspace
2. Install Extensions: Click "Install All" when prompted
3. Select Interpreter: Choose .venv interpreter
4. Start Coding: PYTHONPATH is automatically configured!

See GETTING_STARTED.md for detailed instructions.

FeedbackMonitor usage

The repository includes a small FeedbackMonitor utility in src/syntechrev_polycodcal/feedback_monitor.py.

Example (programmatic):

from syntechrev_polycodcal.feedback_monitor import FeedbackMonitor

mon = FeedbackMonitor(window_seconds=60, threshold=0.2)
mon.ingest({"timestamp": None, "outcome": "ok"})
alert = mon.check()
if alert:
	print("Alert:", alert)

CLI example (one-off processing of newline-delimited JSON):

# Using the installed console script (after pip install)
syntech-monitor examples/events.jsonl

# Or directly via Python
python scripts/feedback_monitor.py examples/events.jsonl

Console Scripts

After installation, the following console scripts are available:

• syntech-monitor - Feedback monitoring CLI
• genesis-gateway - Genesis Gateway processing pipeline
• legal-generator - Legal data ingestion and query tool

# View help for each command
syntech-monitor --help
genesis-gateway --help
legal-generator --help

Development

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

• Setting up your development environment
• Code standards and style guide
• Testing requirements
• Pull request process

Code Quality

This project maintains high code quality standards:

• Testing: 100% code coverage with pytest
• Linting: Enforced with ruff and black
• Type Checking: Static analysis with mypy
• CI/CD: Automated testing on Python 3.11, 3.12, and 3.13

Development Workflow

1. Clone the repository
2. Create a virtual environment
3. Install dependencies: pip install -r dev-requirements.txt
4. Install pre-commit hooks: pre-commit install
5. Make your changes
6. Run tests: pytest -v
7. Check code quality:

   black src tests scripts
   ruff check .
   mypy src

8. Submit a pull request

Code Repair Strategy

For detailed information on our systematic approach to maintaining and repairing code quality, see CODE_REPAIR_STRATEGY.md. This document covers:

• Assessment and issue identification
• Prioritization methodology
• Systematic repair process
• Verification and testing
• Best practices and common solutions

Environment Reset

Having issues with your development environment or VSCode integration? See docs/ENVIRONMENT_RESET.md for:

• Quick environment reset procedures
• VSCode integration troubleshooting
• Cross-platform compatibility fixes
• GitHub sync and merge conflict resolution
• GitHub Copilot setup verification

Agent Collaboration

Working with multiple AI agents or coordinating automated tasks? See docs/AGENT_COLLABORATION.md for:

• Cross-platform communication protocols
• Task coordination between agents
• Quality standards and handoff procedures
• GitHub Copilot integration patterns
• Conflict resolution strategies

Project Structure

SynTechRev-PolyCodCal/
├── src/
│   └── syntechrev_polycodcal/
│       ├── __init__.py
│       ├── core.py
│       └── feedback_monitor.py
├── tests/
│   ├── test_core.py
│   ├── test_feedback_monitor.py
│   └── test_feedback_monitor_extra.py
├── scripts/
│   └── feedback_monitor.py
├── examples/
│   └── events.jsonl
├── .github/
│   └── workflows/
│       └── ci.yml
├── CODE_REPAIR_STRATEGY.md
├── CONTRIBUTING.md
└── README.md

VS Code & GitHub Copilot Integration

This project includes comprehensive VS Code and GitHub Copilot integration:

🤖 AI-Assisted Development: GitHub Copilot integration with project-specific instructions

• Open SynTechRev-PolyCodCal.code-workspace for optimal setup
• Copilot understands project standards (100% coverage, type hints, Black formatting)
• Real-time type checking with Pylance (no mypy CLI required)

See COPILOT_INTEGRATION.md for complete setup and usage guide.

⚙️ Pre-configured VS Code Settings:

• Auto-format on save (Black)
• Integrated testing (pytest)
• Type checking (Pylance)
• One-click quality checks (Ctrl+Shift+B)

See .vscode/README.md for VS Code configuration details.

Resources

Getting Started

• Getting Started Guide - Complete setup guide
• Quick Start - 5-minute setup
• Environment Reset - Troubleshooting and reset procedures

Development

• Contributing Guide - How to contribute to this project
• Development Workflow - Visual workflow guide
• Code Repair Strategy - Systematic approach to code quality
• Tagging Guide - Creating release tags and repository cleanup
• Phase 5 Completion Guide - End-to-end Phase 5 steps and rationale
• VS Code Tagging Quick Reference - Tagging from within VS Code

Tools & IDE

• Copilot Integration Guide - GitHub Copilot setup and usage
• VS Code Setup - Editor configuration and shortcuts
• VS Code Tagging - Quick reference for tagging releases in VS Code
• GitHub Integration - Set up GitHub authentication in VS Code
• Workspace Status - Complete workspace verification and status

Reference

• CI/CD Pipeline - Automated testing and quality checks
• Changelog - Version history and release notes
• Roadmap - Project roadmap and future plans

Roadmap

See the evolving project roadmap in ROADMAP.md for phased enhancements (hysteresis thresholds, batched ingest, metrics extensibility, CLI tooling, and more).

Phase 5: AI Legal Data Generator Framework

Phase 5 introduces a lightweight AI generator for legal data augmentation:

• LegalDataGenerator – produces ai_summary, ai_primary_doctrine, and ai_embedding
• Integration via load_legal_records(augment=True)
• See docs: AI_LEGAL_DATA_GENERATOR_OVERVIEW.md