Metadata-Version: 2.4
Name: cobol-intel
Version: 0.3.0
Summary: Open-source platform for understanding, documenting, and analyzing legacy COBOL codebases using static analysis and LLM
Project-URL: Homepage, https://github.com/WwzFwz/cobol-intel
Project-URL: Documentation, https://github.com/WwzFwz/cobol-intel/tree/main/docs
Project-URL: Repository, https://github.com/WwzFwz/cobol-intel
Project-URL: Issues, https://github.com/WwzFwz/cobol-intel/issues
Project-URL: Changelog, https://github.com/WwzFwz/cobol-intel/blob/main/CHANGELOG.md
License: MIT
Keywords: cobol,fintech,legacy,llm,modernization,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.30.0
Requires-Dist: antlr4-python3-runtime>=4.13.0
Requires-Dist: lark>=1.2.0
Requires-Dist: networkx>=3.0
Requires-Dist: ollama>=0.2.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: api
Requires-Dist: fastapi>=0.115.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: jsonschema>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: tach>=0.9.0; extra == 'dev'
Provides-Extra: local
Requires-Dist: peft>=0.11.0; extra == 'local'
Requires-Dist: torch>=2.2.0; extra == 'local'
Requires-Dist: transformers>=4.40.0; extra == 'local'
Provides-Extra: train
Requires-Dist: accelerate>=0.30.0; extra == 'train'
Requires-Dist: bitsandbytes>=0.43.0; (platform_system != 'Windows') and extra == 'train'
Requires-Dist: datasets>=2.19.0; extra == 'train'
Requires-Dist: peft>=0.11.0; extra == 'train'
Requires-Dist: torch>=2.2.0; extra == 'train'
Requires-Dist: transformers>=4.40.0; extra == 'train'
Description-Content-Type: text/markdown

# cobol-intel

[![CI](https://github.com/WwzFwz/cobol-intel/actions/workflows/ci.yml/badge.svg)](https://github.com/WwzFwz/cobol-intel/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Open-source static analysis and LLM explanation platform for legacy COBOL
codebases. Built for banking, fintech, and regulated modernization workflows.

## Why This Exists

Legacy COBOL systems fail the same way: key maintainers retire, documentation
goes stale, impact analysis is manual, and regulators still need clear
explanations. `cobol-intel` fixes that with a structured pipeline:

```
COBOL source → parser & AST → call graph & business rules → LLM explanation
                                                           → impact analysis
                                                           → documentation
```

The LLM consumes clean, traceable artifacts — not raw COBOL.

## Quickstart

```bash
pip install cobol-intel

# Optional extras
pip install "cobol-intel[api]"    # REST API
pip install "cobol-intel[local]"  # local HuggingFace inference
pip install "cobol-intel[train]"  # fine-tuning scripts

# Analyze a COBOL directory
cobol-intel analyze samples/ --copybook-dir copybooks

# Explain with an LLM backend
cobol-intel explain samples/complex/payment.cbl --model claude --mode business

# Generate documentation
cobol-intel docs artifacts/samples/run_xxx --format html

# Analyze change impact
cobol-intel impact artifacts/samples/run_xxx --changed-program PAYMENT --changed-field WS-BALANCE
```

Output:

```
[cobol-intel] analyze: samples/
Run ID: run_20260401_001
Status: completed
Artifacts: artifacts/samples/run_20260401_001
```

## Features

### Static Analysis
- ANTLR4-based parser (fixed + free format COBOL)
- COPYBOOK resolution with circular dependency detection
- Call graph builder and business rules extractor
- Control flow graph (CFG) with branch, perform, and fallthrough edges
- Field-level data flow analysis (MOVE, COMPUTE, READ INTO, WRITE FROM, CALL)
- Dead code detection: unreachable paragraphs, unused data items, dead branches
- Field reference indexer with read/write/condition classification
- Data item hierarchy with PIC, COMP-3, REDEFINES, OCCURS, level-88

### LLM Explanation
- Multi-backend: Claude, OpenAI, Ollama
- Three modes: `technical`, `business`, `audit`
- Governance: audit logging, sensitivity classification, prompt redaction
- Policy enforcement, token budgets, retry/timeout
- Parallel processing with bounded concurrency
- File-based cache with composite keys

### Change Impact Analysis
- "If I change field X, what breaks?"
- BFS traversal on reverse call graph
- Field reference scanning across ASTs and business rules
- Configurable depth limit

### Output & Documentation
- Versioned JSON artifact contracts (Pydantic v2)
- Markdown + HTML report generation
- Self-contained HTML with sidebar nav, search, and Mermaid graphs
- Structured error codes for operational monitoring

### Fine-Tuning
- Dataset builder: generates instruction-tuning pairs from pipeline output
- LoRA/PEFT fine-tuning script for CodeLlama-7B or similar (QLoRA supported)
- Local fine-tuned model backend for fully offline inference
- Prompt comparison benchmark: raw source vs structured pipeline prompts

### API & Distribution
- Versioned REST API (`/api/v1/`) with OpenAPI docs and typed error responses
- Docker image + docker-compose with optional Ollama sidecar
- Cross-platform CI (Linux + Windows, Python 3.11 + 3.12)
- PyPI-ready wheel with PEP 561 type stubs

## CLI Commands

| Command | Description |
|---------|-------------|
| `analyze` | Parse COBOL files, build AST, call graph, business rules |
| `explain` | Run analysis + LLM explanation |
| `graph` | Build dependency and call graph artifacts |
| `impact` | Analyze change impact from a completed run |
| `docs` | Generate documentation (Markdown or HTML) |

Global:

```bash
cobol-intel --version           # Show version
```

Key flags:

```bash
--model claude|openai|ollama|local  # LLM backend
--mode technical|business|audit # Explanation style
--parallel                      # Enable parallel LLM processing
--max-workers N                 # Override concurrency limit
--cache / --no-cache            # Explanation cache toggle
--strict-policy                 # Hard block policy violations
--max-tokens-per-run N          # Token budget cap
--format markdown|html          # Documentation format
```

## API Usage

```bash
pip install "cobol-intel[api]"
cobol-intel-api  # starts on port 8000

curl http://localhost:8000/api/v1/health
curl http://localhost:8000/api/v1/runs?output_dir=artifacts
curl http://localhost:8000/api/v1/version
```

See [docs/API_GUIDE.md](docs/API_GUIDE.md) for full endpoint reference.

## Output Artifacts

Each run produces a stable artifact tree:

```
artifacts/<project>/<run_id>/
  manifest.json          # Run metadata, governance, errors
  ast/                   # Per-program AST JSON
  graphs/                # Call graph JSON + Mermaid
  rules/                 # Business rules JSON + Markdown
  analysis/              # CFG, data flow, dead code, references
  docs/                  # Explanations, documentation
  logs/                  # Audit event log
```

See [docs/OUTPUT_GALLERY.md](docs/OUTPUT_GALLERY.md) for sample artifacts.

## COBOL Subset Coverage

- Fixed-format and free-format COBOL
- `COPY`, circular copy detection, `COPY ... REPLACING`
- `WORKING-STORAGE`, `FILE`, `LINKAGE` sections
- `PROCEDURE DIVISION USING`
- `PIC`, `COMP-3`, `REDEFINES`, `OCCURS`, level-88 conditions
- `IF`, `EVALUATE`, `PERFORM`, `CALL`, `STRING`, `UNSTRING`, `INSPECT`
- File I/O: `OPEN`, `READ`, `WRITE`, `REWRITE`, `CLOSE`
- `EXEC SQL` subset for static-analysis context

## Development

```bash
git clone https://github.com/WwzFwz/cobol-intel.git
cd cobol-intel
pip install -e ".[dev]"

make lint    # ruff + tach
make test    # pytest
make bench   # benchmark suite
make build   # build wheel
```

Offline inference and training extras:

```bash
pip install -e ".[local]"  # local HuggingFace backend
pip install -e ".[train]"  # dataset + fine-tuning tooling
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for full dev setup and guidelines.

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Architecture Decisions](docs/DECISIONS.md)
- [API Guide](docs/API_GUIDE.md)
- [Output Gallery](docs/OUTPUT_GALLERY.md)
- [Fintech Readiness](docs/FINTECH_READINESS.md)
- [Parser Evaluation](docs/PARSER_EVALUATION.md)
- [Project Plan](docs/PLAN.md)
- [Progress](docs/PROGRESS.md)
- [Changelog](CHANGELOG.md)

## License

MIT
