cohzen 0.2.0__tar.gz

cohzen-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Create a report to help us improve Cohzen
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Run command: `cz scan <path>`
+2. Target codebase structure:
+3. See error output:
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Code Snippet / LangGraph Architecture**
+If applicable, add the Python snippet causing the issue (e.g. `StateGraph`, `add_node`, `ToolNode`, custom routing):
+```python
+# Paste snippet here
+```
+
+**Environment (please complete the following information):**
+ - OS: [e.g. macOS, Ubuntu, Windows]
+ - Python Version: [e.g. 3.10.12, 3.11.8, 3.12.2]
+ - Cohzen Version: [e.g. `cz version` output]
+ - LangGraph Version: [e.g. 0.2.x]
+
+**Additional context**
+Add any other context about the problem here.

cohzen-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

cohzen-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest an idea or architectural detector for Cohzen
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what detector, manifest field, or command enhancement you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Supported Agent Framework / Pattern**
+- Framework: [e.g. LangGraph, CrewAI, AutoGen, LlamaIndex Workflows]
+- Code Pattern Example:
+```python
+# Example graph or agent construction pattern
+```
+
+**Additional context**
+Add any other context, screenshots, or manifest examples here.

cohzen-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Description
+Briefly describe the change, rationale, and problem it solves.
+
+## Type of Change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds architectural detection capability)
+- [ ] Manifest schema update (versioned contract change)
+- [ ] Documentation update
+- [ ] Refactoring / performance optimization
+
+## How Has This Been Tested?
+- [ ] Added unit test in `tests/`
+- [ ] Added/verified real-world fixture in `tests/fixtures/`
+- [ ] Full pytest suite passed (`pytest tests/ -v`)
+- [ ] CLI smoke test verified (`cz scan ...`)
+
+## Checklist
+- [ ] My code adheres to the project style guidelines
+- [ ] I have updated documentation accordingly (`docs/` and `README.md`)
+- [ ] All new and existing tests passed with zero regressions
+- [ ] Analysis remains 100% static AST parsing with zero runtime code execution

cohzen-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release & Publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip build hatchling
+
+      - name: Build sdist and wheel
+        run: |
+          python -m build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

cohzen-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run test suite with pytest & coverage
+        run: |
+          pytest --cov=cz --cov-report=xml --cov-report=term-missing tests/
+
+      - name: Verify CLI smoke test
+        run: |
+          cz --help
+          cz version
+          cz scan examples/langgraph-basic

cohzen-0.2.0/.gitignore

@@ -0,0 +1,54 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+# Legacy distutils build artifact
+/MANIFEST
+
+# Virtual environments
+.env
+.env.local
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Cohzen telemetry and local runtime data
+.cohzen/

cohzen-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# `cz` Architecture & Design Decisions
+
+This document details the modular, extensible architecture of the `cz` CLI package.
+
+---
+
+## 1. Architectural Philosophy
+
+`cz` is designed as an extensible, multi-framework static scanner for AI agentic applications. To ensure maintainability, testability, and zero cross-contamination, the codebase is partitioned into isolated domain plugins:
+
+```
+┌────────────────────────────────────────────────────────┐
+│                        cz CLI                          │
+└───────────────────────────┬────────────────────────────┘
+                            │
+┌───────────────────────────▼────────────────────────────┐
+│                    Master Engine                       │
+│  - Directory walker (respects .git, venv, node_modules)│
+│  - Orchestrates Registries                             │
+└─────────────┬─────────────┬─────────────┬──────────────┘
+              │             │             │
+              ▼             ▼             ▼
+┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
+│FrameworkRegistry │ │ LLMRegistry  │ │ObservabilityReg. │
+│- langgraph/      │ │- openai/     │ │- langsmith/      │
+│- (future crewai) │ │- anthropic/  │ │- langfuse/       │
+│- (future adk)    │ │- google/     │ │- opentelemetry/  │
+│                  │ │- groq/       │ │- arize_phoenix/  │
+│                  │ │- grok/       │ │- traceloop/      │
+│                  │ │- langchain/  │ │- agentops/       │
+│                  │ │- litellm/    │ │- wandb/          │
+└──────────────────┘ └──────────────┘ └──────────────────┘
+```
+
+---
+
+## 2. Domain Registries
+
+### A. Frameworks (`src/cz/frameworks/`)
+- Protocol: `BaseFrameworkScanner` (defines `visit_assign`, `visit_call`, `visit_return`, `get_graphs`).
+- Primary Implementation: `src/cz/frameworks/langgraph/`
+  - `scanner.py`: Extracts `StateGraph`, `Graph`, `MessageGraph`, nodes, direct edges, conditional edges, `ToolNode`, and `.compile()`.
+  - `models.py`: LangGraph-specific models and aliases.
+- Extensibility: Adding a new framework (e.g. CrewAI or Google ADK) requires only creating a folder in `src/cz/frameworks/` and implementing `BaseFrameworkScanner`.
+
+### B. LLM Provider Detectors (`src/cz/llms/`)
+- Protocol: `BaseLLMDetector` (defines `detect_call` and `detect_tools_bound`).
+- Each provider lives in its own folder:
+  - `openai/`: Detects `client.chat.completions.create`, models, and `tools=[...]`.
+  - `anthropic/`: Detects `client.messages.create`, models, and `tools=[...]`.
+  - `google/`: Detects `generate_content`, `generate_text`, models, and `tools=[...]`.
+  - `groq/`: Detects Groq client completions, models, and `tools=[...]`.
+  - `grok/`: Detects xAI Grok completions.
+  - `langchain/`: Detects `.invoke()`, `.ainvoke()`, `.stream()`, and `model.bind_tools(tools)`.
+  - `litellm/`: Detects `completion()`, `acompletion()`, models, and `tools=[...]`.
+
+### C. Observability Providers (`src/cz/observability/`)
+- Protocol: `BaseObservabilityDetector` (defines `check_manifest`, `get_known_env_vars`, `get_known_decorators`).
+- Each tool lives in its own folder:
+  - `langsmith/`
+  - `langfuse/`
+  - `opentelemetry/`
+  - `arize_phoenix/`
+  - `traceloop/`
+  - `agentops/`
+  - `wandb/`
+- The `ObservabilityRegistry` computes coverage metrics and generates gap analysis.
+
+---
+
+## 3. How to Extend
+
+### Adding a New LLM Provider
+1. Create `src/cz/llms/<provider_name>/detector.py`.
+2. Implement `detect_call(call, file_path, lineno)` returning `Optional[LLMCallSite]`.
+3. Register the detector in `src/cz/llms/registry.py`.
+
+### Adding a New Observability Tool
+1. Create `src/cz/observability/<tool_name>/detector.py`.
+2. Define `provider_id`, `display_name`, `check_manifest`, `get_known_env_vars`, and `get_known_decorators`.
+3. Register the detector in `src/cz/observability/registry.py`.
+
+### Adding a New Agentic Framework
+1. Create `src/cz/frameworks/<framework_name>/scanner.py`.
+2. Implement `BaseFrameworkScanner`.
+3. Register in `src/cz/frameworks/registry.py`.

cohzen-0.2.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to **Cohzen (`cz`)** will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.2.0] - 2026-10-02
+
+### Added
+- **Runtime Execution Tracking & Observability (`cz init`, `cz runs`, `cz run <id>`)**:
+  - Transparent LangChain / LangGraph execution tracing with zero code changes via `CohzenCallbackHandler`.
+  - SQLite persistent telemetry store `.cohzen/executions.db` recording run states, tokens, latency, and spans.
+  - Interactive terminal run viewers, detailed JSON payloads, and execution waterfall timeline graphs (`cz waterfall`).
+- **Isolated Node Debugger (`cz node run`, `cz node list`, `cz debug`)**:
+  - Test and run individual LangGraph nodes directly in isolation without compiling or running the entire graph.
+  - State replay from previous executions using `--from-run <id>`.
+  - Smart state hydration reconstructing Pydantic models, dual-access state dicts, and LangChain message objects.
+- **Interactive Browser Telemetry Viewer**:
+  - Visual Gantt waterfall and execution trace inspection in browser (`cz run <id> --view`).
+
+---
+
+## [0.1.0] - 2024-09-19
+
+### Added
+- **100% Static LangGraph Architecture Reconstruction**: Statically analyzes LangGraph workflows directly from Python AST without executing any runtime code.
+- **Immutable System Manifest (`CohzenManifest` v0.1.0)**:
+  - Canonical normalized schema representing graphs, nodes, edges, tools, and models.
+  - Granular source location tracking (`file`, `line_start`, `line_end`).
+  - Graceful degradation resolution states (`resolved`, `partially_resolved`, `unresolved`).
+  - Analysis limitations & completeness metadata (`unresolved_symbols`, `dynamic_constructions`, `warnings`).
+- **Comprehensive Detector Suite**:
+  - LangGraph: `StateGraph`, `MessageGraph`, `Graph`, `add_node`, `add_edge`, `add_conditional_edges`, `compile()`, checkpointer resolution, interrupt points.
+  - LLM Providers: OpenAI, Anthropic, Google Gemini, Groq, xAI Grok, LiteLLM, LangChain client calls & `bind_tools`.
+  - Tools: `@tool` function inspection, line spans, docstrings, `ToolNode` parameter extraction.
+  - Observability Telemetry: Tracing decorator inspection (`@traceable`, `@observe`), manifest detection (`pyproject.toml`, `requirements.txt`), `.env` configuration audits.
+- **First-Class Inline Lambda Support**: Automatically parses inline lambda handlers and routers into resolved nodes with body-level LLM inspection.
+- **External Dependency Highlighting**: Explicitly identifies node and tool handlers imported from external packages (`external_package`) without conflating them with errors.
+- **CLI Commands**:
+  - `cz scan [path]`: Interactive terminal dashboard, `--json` manifest, `--mermaid` diagram export.
+  - `cz audit [path]`: Observability and telemetry gap audit report with tool attribution.
+  - `cz view [path]`: Standalone interactive HTML browser visualizer.
+  - `cz version`: Version details.
+- **Production Test Suite**: 56 unit, integration, and real-world fixture tests covering diverse patterns (monolithic graphs, split modules, multiple graphs, subgraphs, factory builders, conditional routing, ToolNodes).

cohzen-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,177 @@
+# Contributing to Cohzen
+
+Thank you for your interest in contributing to **Cohzen**! We welcome contributions from the community to make static agentic architecture discovery fast, accurate, and developer-friendly.
+
+---
+
+## Code of Conduct
+
+Please be respectful, collaborative, and constructive when interacting with maintainers and other contributors.
+
+---
+
+## Development Setup
+
+Cohzen requires **Python 3.10+**.
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/cohzen-ai/cohzen.git
+   cd cohzen
+   ```
+
+2. **Create and activate a virtual environment**:
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+
+3. **Install in editable mode with development dependencies**:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+4. **Verify the installation**:
+   ```bash
+   cz version
+   pytest tests/ -v
+   ```
+
+---
+
+## Repository Structure
+
+```text
+cohzen/
+├── .github/                       # CI/CD workflows & community templates
+│   ├── workflows/
+│   │   ├── tests.yml              # Multi-Python (3.10, 3.11, 3.12) test matrix
+│   │   └── release.yml            # Automated PyPI release workflow
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── bug_report.md          # Bug report template
+│   │   └── feature_request.md     # Feature/detector request template
+│   └── pull_request_template.md   # PR checklist and guidelines
+│
+├── docs/                          # Comprehensive technical documentation
+│   ├── architecture.md            # Static AST engine & pipeline architecture
+│   ├── manifest.md                # CohzenManifest v0.1 JSON specification
+│   ├── supported-frameworks.md    # Framework & LLM detector matrix
+│   └── development.md             # Contributor development workflow
+│
+├── examples/                      # Runnable standalone LangGraph examples
+│   ├── langgraph-basic/           # ProcessState pipeline with MemorySaver
+│   ├── langgraph-tools/           # MessagesState agent with ToolNode & lambda routing
+│   └── langgraph-routing/         # Supervisor team with conditional routing & interrupts
+│
+├── src/cz/                        # Core codebase
+│   ├── cli/                       # Typer-based CLI application (`main.py`)
+│   │   ├── __init__.py
+│   │   └── main.py                # Commands: cz scan, cz audit, cz view, cz version
+│   │
+│   ├── scanner/                   # AST analysis engine, visitor, and data models
+│   │   ├── __init__.py
+│   │   ├── engine.py              # Repository scan orchestrator (scan_repository, scan_file)
+│   │   ├── visitor.py             # AST visitor & symbol resolver (scan_python_file)
+│   │   ├── utils.py               # AST string & expression extractors
+│   │   └── models.py              # ScanResult, GraphInfo, NodeInfo, ToolDef, etc.
+│   │
+│   ├── manifest/                  # Immutable Cohzen Manifest v0.1 Contract
+│   │   ├── __init__.py
+│   │   ├── schema.py              # CohzenManifest, GraphDef, NodeDef, ToolDef, ModelDef
+│   │   └── builder.py             # Deterministic Manifest compilation
+│   │
+│   ├── detectors/                 # Static pattern detectors
+│   │   ├── __init__.py
+│   │   ├── base.py                # BaseFrameworkScanner, BaseLLMDetector, BaseToolDetector
+│   │   ├── registry.py            # FrameworkRegistry
+│   │   ├── langgraph/             # LangGraph framework detector (StateGraph, nodes, edges)
+│   │   ├── llm/                   # Frozen v0.1 LLM provider detectors
+│   │   │   ├── base.py
+│   │   │   ├── registry.py        # LLMRegistry
+│   │   │   ├── openai/
+│   │   │   ├── anthropic/
+│   │   │   ├── google/
+│   │   │   ├── groq/
+│   │   │   ├── grok/
+│   │   │   ├── langchain/
+│   │   │   └── litellm/
+│   │   └── tools/                 # Tool detector (@tool decorators, line spans)
+│   │       ├── __init__.py
+│   │       └── detector.py
+│   │
+│   ├── audit/                     # Observability & telemetry governance engine
+│   │   ├── __init__.py
+│   │   ├── engine.py              # Audit orchestrator (audit_repository, scan_manifest_files)
+│   │   ├── registry.py            # Observability detector registry
+│   │   ├── base.py                # BaseObservabilityDetector protocol
+│   │   ├── langsmith/
+│   │   ├── langfuse/
+│   │   ├── opentelemetry/
+│   │   ├── arize_phoenix/
+│   │   ├── traceloop/
+│   │   ├── agentops/
+│   │   └── wandb/
+│   │
+│   └── formatters/                # Output presentation & visualization
+│       ├── __init__.py
+│       ├── console.py             # Rich terminal architecture & audit flow reports
+│       ├── mermaid.py             # LangGraph-compatible Mermaid flowchart
+│       ├── json_fmt.py            # Cohzen Manifest JSON serializer
+│       └── viewer.py              # Interactive dark-mode HTML browser visualizer
+│
+├── tests/                         # Test suites & fixtures
+│   ├── fixtures/                  # Real-world & sample test fixtures
+│   │   ├── real_world/            # 10 production-pattern test projects (01 to 10)
+│   │   └── sample_graphs/         # Specialized graph variations
+│   ├── test_scanner.py
+│   ├── test_cli_and_formatters.py
+│   ├── test_real_world_fixtures.py
+│   ├── test_graphs_and_compilation.py
+│   ├── test_routing_and_edges.py
+│   ├── test_tools_and_nodes.py
+│   ├── test_agents_and_llms.py
+│   ├── test_llm_providers.py
+│   ├── test_observability_audit.py
+│   ├── test_observability_providers.py
+│   ├── test_framework_registry.py
+│   └── test_engine_and_ignores.py
+│
+├── .gitignore                     # Git ignore rules
+├── pyproject.toml                 # Build configuration & entrypoint (cz = "cz.cli.main:app")
+├── LICENSE                        # MIT License
+├── README.md                      # Project documentation & overview
+├── CHANGELOG.md                   # Version release notes
+└── CONTRIBUTING.md                # Contributor guide
+```
+
+---
+
+## Core Guiding Principles
+
+When making changes to Cohzen:
+1. **Zero Runtime Execution**: Cohzen is strictly a **static AST analysis tool**. Never import or execute scanned target user code (`importlib`, `exec()`, `eval()`).
+2. **Immutable Contract**: The `CohzenManifest` (`v0.1.0`) is the single source of truth. Formats (`console`, `mermaid`, `json`, `view`) must consume discovered facts from this manifest.
+3. **Graceful Degradation**: Real-world Python can be dynamic or external. Degrade gracefully (`resolved` -> `partially_resolved` -> `unresolved`) with honest static limitations rather than crashing or guessing.
+
+---
+
+## Running Tests
+
+Run the complete test suite:
+```bash
+pytest tests/ -v
+```
+
+Generate a test coverage report:
+```bash
+pytest --cov=cz --cov-report=term-missing tests/
+```
+
+---
+
+## Pull Request Guidelines
+
+1. **Branch naming**: `feature/your-feature-name` or `fix/your-bug-fix`.
+2. **Include tests**: Add unit tests or real-world fixtures under `tests/` demonstrating your fix or new detection pattern.
+3. **Documentation**: Update relevant guides in `docs/` or `README.md` if CLI flags or manifest schemas change.
+4. **Clean Git history**: Ensure commits are logical and well-described.

cohzen-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cohzen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.