Cohzen (`cz`) Documentation

$ pip install cohzen

$ git clone https://github.com/cohzenai/cohzen.git
$ cd cohzen/cz
$ pip install -e .

Cohzen will:
  • create or modify .cohzen/config.toml
  • create or modify .cohzen/manifest.json
  • create or modify .cohzen/executions.db
  • create or modify .gitignore
  • create or modify .venv/lib/python3.11/site-packages/cohzen_startup.pth

Graph Topology & Routing Edges
┏━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Type        ┃ Source    ┃ Direction ┃ Target / Routing   ┃ Location          ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ DIRECT      │ START     │    ──>    │ assistant          │ agent_tools.py:35 │
│ CONDITIONAL │ assistant │   ─?─>    │ fn: lambda state:  │ agent_tools.py:36 │
│             │           │           │ 'tools' | 'finish' │                   │
│ DIRECT      │ tools     │    ──>    │ assistant          │ agent_tools.py:41 │
└─────────────┴───────────┴───────────┴────────────────────┴───────────────────┘

✔ Cohzen initialized at ./
  • Manifest: .cohzen/manifest.json (1 graphs, 2 nodes, 2 tools)
  • Telemetry DB: .cohzen/executions.db
  • Startup hook: .venv/lib/python3.11/site-packages/cohzen_startup.pth
  • Added .cohzen/ to .gitignore

Capture is enabled for eligible local LangGraph runs. One-off capture remains available:
  cz capture -- python app.py

Then inspect recorded executions:
  cz runs

╭─────────────── Cohzen Observability & Telemetry Audit (v0.3) ────────────────╮
│  Scanned Target:    ./examples/langgraph-tools                               │
│  Observability:     LangSmith detected in package manifests                  │
│  Tracing Coverage:  Nodes: 1/2 (50.0%)  •  Tools: 1/2 (50.0%)                │
│  CI Gate Check:     Required 80.0% coverage  -->  FAILED (50.0%)             │
╰──────────────────────────────────────────────────────────────────────────────╯

╭─────────────────────────── Node Instrumentation Status ───────────────────────────╮
│ Node Name            │ Location           │ Tracing Status   │ Observability Tool │
│ 🤖 assistant         │ agent_tools.py:20  │ ✖ Uninstrumented │ None               │
│ 🤖 tools             │ agent_tools.py:29  │ ✔ Instrumented   │ LangSmith          │
╰───────────────────────────────────────────────────────────────────────────────────╯

╭─────────────────────────── Audit Findings & Gaps ─────────────────────────────────╮
│                                                                                   │
│  ⚠ LangSmith tracing detected, but 'LANGCHAIN_TRACING_V2=true' missing in .env   │
│  ⚠ Agent(s) 'assistant' perform LLM calls without @traceable or @observe          │
│  ✖ CI Gate Failure: Codebase coverage 50.0% does not meet --min-coverage 80.0%   │
│                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────╯

{
  "version": "0.1.0",
  "metadata": {
    "target": ".",
    "files_scanned": 14,
    "files_skipped": 0,
    "parse_errors": 0,
    "unresolved_symbols": 0,
    "dynamic_constructions": 0,
    "scan_duration_ms": 1.82,
    "created_at": "2024-09-19T12:00:00Z",
    "warnings": []
  },
  "frameworks": ["langgraph"],
  "graphs": [
    {
      "id": "graph.workflow",
      "name": "workflow",
      "framework": "langgraph",
      "graph_class": "StateGraph",
      "state_schema": "AgentState",
      "source": { "file": "app.py", "line_start": 20, "line_end": 20 },
      "node_ids": ["planner", "tools"],
      "edges": [
        { "source": "START", "target": "planner", "edge_type": "direct" },
        { "source": "planner", "target": "tools", "edge_type": "conditional" }
      ],
      "compilation": {
        "compiled_var": "app",
        "checkpointer": "MemorySaver",
        "source": { "file": "app.py", "line_start": 35, "line_end": 35 }
      }
    }
  ],
  "nodes": [
    {
      "id": "planner",
      "name": "planner",
      "kind": "node",
      "handler": "planner_node",
      "source": { "file": "app.py", "line_start": 10, "line_end": 18 },
      "model_ids": ["model.openai.gpt-4o"],
      "tool_ids": ["tool.search_web"],
      "resolution": { "status": "resolved", "reason": null },
      "classification": { "role": "agent", "confidence": "high", "evidence": ["llm_invocation", "tool_binding"] }
    }
  ],
  "tools": [
    {
      "id": "tool.search_web",
      "name": "search_web",
      "source": { "file": "tools.py", "line_start": 5, "line_end": 8 },
      "docstring": "Searches the web",
      "resolution": { "status": "resolved", "reason": null }
    }
  ],
  "models": [
    {
      "id": "model.openai.gpt-4o",
      "provider": "openai",
      "name": "gpt-4o",
      "source": { "file": "app.py", "line_start": 12, "line_end": 12 }
    }
  ]
}

name: Cohzen Architecture & Telemetry Gate
on: [push, pull_request]

jobs:
  cohzen-audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Run Cohzen Governance Action
        uses: cohzenai/cohzen@v0.3.4
        with:
          min-coverage: '80'
          fail-on-empty: 'true'