conservation-guardian 0.1.0__tar.gz

conservation_guardian-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: conservation-guardian
+Version: 0.1.0
+Summary: Generic Workflow Conservation Engine — analyze any workflow for cost efficiency and detect waste
+Author: SuperInstance
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SuperInstance/conservation-guardian
+Keywords: workflow,cost,optimization,conservation,guardian,efficiency,waste-detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Conservation Guardian
+
+A **generic** Workflow Conservation Engine — analyze any workflow for cost efficiency and detect waste.
+
+> Your workflow costs $12/day. Two nodes account for 78% of tokens. They both call GPT-4 for tasks GPT-4o-mini handles.
+
+Conservation Guardian is a framework-agnostic Python library that analyzes workflow execution for cost efficiency and detects waste. It doesn't change your workflows — it tells you what to change and why. Works with any workflow engine (Dify, n8n, LangGraph, Temporal, custom DAGs, etc.).
+
+## What It Does
+
+**Budget tracking** — Set hard limits on tokens per run, cost per day, and node count. Know immediately when a workflow crosses a threshold.
+
+**DAG analysis** — Parse any workflow JSON and surface:
+- Redundant LLM calls (same model, same upstream, same job)
+- Dead branches (conditional paths that never execute)
+
+**Per-node profiling** — Track tokens in/out, latency, and cost for every node across runs. Spot degradation before it hurts.
+
+**Waste detection** — Find the expensive stuff nobody notices:
+- **Overprompted nodes** — 4,200 tokens in, 180 out. You're paying for context the model ignores.
+- **Idle nodes** — Running every time, contributing 0.1% of value.
+- **Model mismatch** — Using GPT-4 for classification that GPT-4o-mini handles in 12ms.
+
+**Reports** — Markdown summaries you can paste into Slack, Notion, or a PR comment.
+
+## Install
+
+```bash
+pip install conservation-guardian
+```
+
+## Quick Start
+
+```python
+from conservation_guardian.budget import WorkflowBudget
+from conservation_guardian.analyzer import WorkflowDAG
+from conservation_guardian.profiler import Profiler, NodeSample
+from conservation_guardian.detector import WasteDetector
+from conservation_guardian.report import render_report
+
+# 1. Load a workflow (generic — works with any engine's JSON)
+dag = WorkflowDAG.from_dict(workflow_json)
+print(f"{len(dag.llm_nodes())} LLM nodes, {len(dag.redundant_llm_calls())} redundant")
+
+# 2. Profile some runs
+profiler = Profiler()
+profiler.record(NodeSample(
+    node_id="summarizer",
+    input_tokens=4200,
+    output_tokens=180,
+    latency_ms=820.0,
+    cost_usd=0.015,
+))
+
+# 3. Detect waste
+detector = WasteDetector(profiler)
+findings = detector.detect()
+for f in findings:
+    print(f"[{f.severity}] {f.message}")
+    print(f"  → {f.suggestion}")
+
+# 4. Generate report
+budget = WorkflowBudget()
+report = render_report(budget=budget, dag=dag, profiler=profiler, findings=findings)
+print(report)
+```
+
+## Differences from dify-workflow-guardian
+
+- **Framework-agnostic**: No Dify-specific assumptions in the analyzer
+- **Extended node types**: Recognizes `llm`, `llm-chain`, `chat-model`, `switch`, `conditional`, and more
+- **Same API**: Drop-in replacement — just change the import package name
+
+## Module Structure
+
+| File | Purpose |
+|------|---------|
+| `budget.py` | `WorkflowBudget` — token/cost/node limits and daily tracking |
+| `analyzer.py` | `WorkflowDAG` — parse workflow JSON, find redundancies and dead branches |
+| `profiler.py` | `Profiler`, `NodeProfile`, `NodeSample` — per-node stats and trends |
+| `detector.py` | `WasteDetector`, `WasteFinding` — surface actionable waste |
+| `report.py` | `render_report()` — Markdown conservation reports |
+
+## Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Philosophy
+
+Conservation Guardian doesn't optimize your workflows. It tells you where the money goes and what to do about it. The fixes are yours to make — but at least you'll know where to look.
+
+Built for [SuperInstance](https://github.com/SuperInstance).
+
+## License
+
+MIT

conservation_guardian-0.1.0/README.md

@@ -0,0 +1,98 @@
+# Conservation Guardian
+
+A **generic** Workflow Conservation Engine — analyze any workflow for cost efficiency and detect waste.
+
+> Your workflow costs $12/day. Two nodes account for 78% of tokens. They both call GPT-4 for tasks GPT-4o-mini handles.
+
+Conservation Guardian is a framework-agnostic Python library that analyzes workflow execution for cost efficiency and detects waste. It doesn't change your workflows — it tells you what to change and why. Works with any workflow engine (Dify, n8n, LangGraph, Temporal, custom DAGs, etc.).
+
+## What It Does
+
+**Budget tracking** — Set hard limits on tokens per run, cost per day, and node count. Know immediately when a workflow crosses a threshold.
+
+**DAG analysis** — Parse any workflow JSON and surface:
+- Redundant LLM calls (same model, same upstream, same job)
+- Dead branches (conditional paths that never execute)
+
+**Per-node profiling** — Track tokens in/out, latency, and cost for every node across runs. Spot degradation before it hurts.
+
+**Waste detection** — Find the expensive stuff nobody notices:
+- **Overprompted nodes** — 4,200 tokens in, 180 out. You're paying for context the model ignores.
+- **Idle nodes** — Running every time, contributing 0.1% of value.
+- **Model mismatch** — Using GPT-4 for classification that GPT-4o-mini handles in 12ms.
+
+**Reports** — Markdown summaries you can paste into Slack, Notion, or a PR comment.
+
+## Install
+
+```bash
+pip install conservation-guardian
+```
+
+## Quick Start
+
+```python
+from conservation_guardian.budget import WorkflowBudget
+from conservation_guardian.analyzer import WorkflowDAG
+from conservation_guardian.profiler import Profiler, NodeSample
+from conservation_guardian.detector import WasteDetector
+from conservation_guardian.report import render_report
+
+# 1. Load a workflow (generic — works with any engine's JSON)
+dag = WorkflowDAG.from_dict(workflow_json)
+print(f"{len(dag.llm_nodes())} LLM nodes, {len(dag.redundant_llm_calls())} redundant")
+
+# 2. Profile some runs
+profiler = Profiler()
+profiler.record(NodeSample(
+    node_id="summarizer",
+    input_tokens=4200,
+    output_tokens=180,
+    latency_ms=820.0,
+    cost_usd=0.015,
+))
+
+# 3. Detect waste
+detector = WasteDetector(profiler)
+findings = detector.detect()
+for f in findings:
+    print(f"[{f.severity}] {f.message}")
+    print(f"  → {f.suggestion}")
+
+# 4. Generate report
+budget = WorkflowBudget()
+report = render_report(budget=budget, dag=dag, profiler=profiler, findings=findings)
+print(report)
+```
+
+## Differences from dify-workflow-guardian
+
+- **Framework-agnostic**: No Dify-specific assumptions in the analyzer
+- **Extended node types**: Recognizes `llm`, `llm-chain`, `chat-model`, `switch`, `conditional`, and more
+- **Same API**: Drop-in replacement — just change the import package name
+
+## Module Structure
+
+| File | Purpose |
+|------|---------|
+| `budget.py` | `WorkflowBudget` — token/cost/node limits and daily tracking |
+| `analyzer.py` | `WorkflowDAG` — parse workflow JSON, find redundancies and dead branches |
+| `profiler.py` | `Profiler`, `NodeProfile`, `NodeSample` — per-node stats and trends |
+| `detector.py` | `WasteDetector`, `WasteFinding` — surface actionable waste |
+| `report.py` | `render_report()` — Markdown conservation reports |
+
+## Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Philosophy
+
+Conservation Guardian doesn't optimize your workflows. It tells you where the money goes and what to do about it. The fixes are yours to make — but at least you'll know where to look.
+
+Built for [SuperInstance](https://github.com/SuperInstance).
+
+## License
+
+MIT

conservation_guardian-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "conservation-guardian"
+version = "0.1.0"
+description = "Generic Workflow Conservation Engine — analyze any workflow for cost efficiency and detect waste"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{name = "SuperInstance"}]
+keywords = ["workflow", "cost", "optimization", "conservation", "guardian", "efficiency", "waste-detection"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/SuperInstance/conservation-guardian"
+
+[tool.setuptools.packages.find]
+where = ["src"]

conservation_guardian-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

conservation_guardian-0.1.0/src/conservation_guardian/__init__.py

@@ -0,0 +1,3 @@
+"""Conservation Guardian — Generic Workflow Conservation Engine."""
+
+__version__ = "0.1.0"

conservation_guardian-0.1.0/src/conservation_guardian/analyzer.py

@@ -0,0 +1,117 @@
+"""Analyze workflow DAG for inefficiencies.
+
+Generic version — works with any workflow engine that exposes nodes and edges.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class WorkflowNode:
+    id: str
+    type: str  # e.g. "llm", "tool", "if-else", "code", "http", "transform"
+    title: str = ""
+    upstream: list[str] = field(default_factory=list)
+    downstream: list[str] = field(default_factory=list)
+    data: dict = field(default_factory=dict)
+
+
+@dataclass
+class WorkflowDAG:
+    """Directed acyclic graph representing a workflow.
+
+    Can be constructed from any engine's JSON via ``from_dict`` by adapting
+    the node/edge field mappings, or built programmatically.
+    """
+
+    nodes: dict[str, WorkflowNode] = field(default_factory=dict)
+    entry_node: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "WorkflowDAG":
+        """Build a DAG from a generic workflow JSON.
+
+        Expects ``graph.nodes`` and ``graph.edges``, or a flat structure
+        with ``nodes`` / ``edges`` at the top level.  Each node should have
+        ``id`` and ``data.type`` (or just ``type``).  Each edge should have
+        ``sourceId``/``targetId`` or ``source``/``target``.
+        """
+        dag = cls()
+        graph = raw.get("graph", raw)
+        nodes_list = graph.get("nodes", [])
+        edges = graph.get("edges", [])
+
+        node_map: dict[str, WorkflowNode] = {}
+        for n in nodes_list:
+            node = WorkflowNode(
+                id=n["id"],
+                type=n.get("data", {}).get("type", n.get("type", "unknown")),
+                title=n.get("data", {}).get("title", n.get("title", "")),
+                data=n.get("data", {}),
+            )
+            node_map[node.id] = node
+
+        for edge in edges:
+            src = edge.get("sourceId") or edge.get("source")
+            tgt = edge.get("targetId") or edge.get("target")
+            if src in node_map and tgt in node_map:
+                node_map[src].downstream.append(tgt)
+                node_map[tgt].upstream.append(src)
+
+        dag.nodes = node_map
+        entries = [nid for nid, n in node_map.items() if not n.upstream]
+        dag.entry_node = entries[0] if entries else None
+        return dag
+
+    def llm_nodes(self) -> list[WorkflowNode]:
+        """Return all nodes whose type indicates LLM usage."""
+        return [n for n in self.nodes.values() if n.type in ("llm", "llm-chain", "chat-model")]
+
+    def redundant_llm_calls(self) -> list[tuple[WorkflowNode, WorkflowNode]]:
+        """Detect LLM nodes that appear to do the same work.
+
+        Heuristic: same model provider/name and same upstream source.
+        """
+        llms = self.llm_nodes()
+        redundant: list[tuple[WorkflowNode, WorkflowNode]] = []
+        for i, a in enumerate(llms):
+            for b in llms[i + 1:]:
+                if (
+                    a.data.get("model", {}).get("provider") == b.data.get("model", {}).get("provider")
+                    and a.data.get("model", {}).get("name") == b.data.get("model", {}).get("name")
+                    and set(a.upstream) == set(b.upstream)
+                ):
+                    redundant.append((a, b))
+        return redundant
+
+    def dead_branches(self) -> list[list[str]]:
+        """Return paths that can never execute.
+
+        Simplified heuristic: branches from if-else nodes that lead only to
+        leaf (sink) nodes with no further processing.
+        """
+        dead: list[list[str]] = []
+        for node in self.nodes.values():
+            if node.type not in ("if-else", "switch", "conditional"):
+                continue
+            for child_id in node.downstream:
+                path = self._walk_to_end(child_id)
+                if not path:
+                    continue
+                if all(len(self.nodes[nid].downstream) == 0 for nid in path if nid in self.nodes):
+                    dead.append([node.id] + path)
+        return dead
+
+    def _walk_to_end(self, start_id: str) -> list[str]:
+        visited: list[str] = []
+        current = start_id
+        while current and current not in visited:
+            visited.append(current)
+            node = self.nodes.get(current)
+            if not node or not node.downstream:
+                break
+            current = node.downstream[0]
+        return visited

conservation_guardian-0.1.0/src/conservation_guardian/budget.py

@@ -0,0 +1,54 @@
+"""Budget enforcement for workflow runs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Optional
+
+
+@dataclass
+class WorkflowBudget:
+    """Token, cost, and node-count limits for workflow execution."""
+
+    max_tokens_per_run: int = 500_000
+    max_cost_per_day: float = 50.0
+    max_nodes_per_workflow: int = 100
+
+    _daily_spend: dict[date, float] = field(default_factory=dict, repr=False)
+    _run_token_counts: list[int] = field(default_factory=list, repr=False)
+
+    price_input_per_1k: float = 0.03
+    price_output_per_1k: float = 0.06
+
+    def record_run(self, input_tokens: int, output_tokens: int) -> float:
+        total = input_tokens + output_tokens
+        self._run_token_counts.append(total)
+        cost = self._cost(input_tokens, output_tokens)
+        today = date.today()
+        self._daily_spend[today] = self._daily_spend.get(today, 0.0) + cost
+        return cost
+
+    def _cost(self, input_tokens: int, output_tokens: int) -> float:
+        return (input_tokens * self.price_input_per_1k + output_tokens * self.price_output_per_1k) / 1_000
+
+    def is_within_budget(self, input_tokens: int, output_tokens: int) -> bool:
+        total = input_tokens + output_tokens
+        if total > self.max_tokens_per_run:
+            return False
+        cost = self._cost(input_tokens, output_tokens)
+        today = date.today()
+        if self._daily_spend.get(today, 0.0) + cost > self.max_cost_per_day:
+            return False
+        return True
+
+    def check_node_count(self, node_count: int) -> bool:
+        return node_count <= self.max_nodes_per_workflow
+
+    def daily_spend(self, day: Optional[date] = None) -> float:
+        return self._daily_spend.get(day or date.today(), 0.0)
+
+    def avg_tokens_per_run(self) -> float:
+        if not self._run_token_counts:
+            return 0.0
+        return sum(self._run_token_counts) / len(self._run_token_counts)

conservation_guardian-0.1.0/src/conservation_guardian/detector.py

@@ -0,0 +1,113 @@
+"""Waste detection: find nodes that burn tokens without proportional value."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .profiler import NodeProfile, Profiler
+
+
+@dataclass
+class WasteFinding:
+    node_id: str
+    node_title: str
+    category: str  # "overprompted", "idle", "expensive_model", "redundant"
+    severity: str  # "low", "medium", "high"
+    message: str
+    suggestion: str
+
+
+DEFAULT_MAX_IO_RATIO = 15.0
+DEFAULT_IDLE_THRESHOLD = 0.1
+DEFAULT_EXPENSIVE_MODEL_RATIO = 0.6
+
+
+class WasteDetector:
+    """Analyze profiler data to surface actionable waste findings."""
+
+    def __init__(
+        self,
+        profiler: Profiler,
+        *,
+        max_io_ratio: float = DEFAULT_MAX_IO_RATIO,
+        idle_threshold: float = DEFAULT_IDLE_THRESHOLD,
+    ) -> None:
+        self.profiler = profiler
+        self.max_io_ratio = max_io_ratio
+        self.idle_threshold = idle_threshold
+
+    def detect(self) -> list[WasteFinding]:
+        findings: list[WasteFinding] = []
+        profiles = self.profiler.all_profiles()
+        if not profiles:
+            return findings
+
+        total_cost = sum(p.total_cost for p in profiles)
+
+        for p in profiles:
+            findings.extend(self._check_overprompted(p))
+            findings.extend(self._check_idle(p, total_cost))
+
+        findings.extend(self._check_expensive_model_concentration(profiles, total_cost))
+        return findings
+
+    def _check_overprompted(self, p: NodeProfile) -> list[WasteFinding]:
+        ratio = p.input_output_ratio
+        if ratio > self.max_io_ratio and p.avg_input_tokens > 200:
+            return [WasteFinding(
+                node_id=p.node_id,
+                node_title=p.node_title,
+                category="overprompted",
+                severity="high" if ratio > 30 else "medium",
+                message=(
+                    f"Node '{p.node_title or p.node_id}' receives {p.avg_input_tokens:,.0f} tokens avg "
+                    f"but outputs {p.avg_output_tokens:,.0f} (ratio {ratio:.1f}×)."
+                ),
+                suggestion="Consider extractive pre-filtering, summarization, or reducing the prompt template size.",
+            )]
+        return []
+
+    def _check_idle(self, p: NodeProfile, total_cost: float) -> list[WasteFinding]:
+        if total_cost == 0:
+            return []
+        fraction = p.total_cost / total_cost
+        if fraction < self.idle_threshold and p.run_count > 5:
+            return [WasteFinding(
+                node_id=p.node_id,
+                node_title=p.node_title,
+                category="idle",
+                severity="low",
+                message=f"Node '{p.node_title or p.node_id}' accounts for only {fraction:.1%} of cost over {p.run_count} runs.",
+                suggestion="Consider removing or conditionally bypassing this node.",
+            )]
+        return []
+
+    def _check_expensive_model_concentration(
+        self, profiles: list[NodeProfile], total_cost: float
+    ) -> list[WasteFinding]:
+        findings: list[WasteFinding] = []
+        if not profiles or total_cost == 0:
+            return findings
+
+        top = self.profiler.top_by_cost(3)
+        top_cost = sum(p.total_cost for p in top)
+        fraction = top_cost / total_cost
+
+        if fraction > DEFAULT_EXPENSIVE_MODEL_RATIO and len(top) <= 2:
+            names = ", ".join(f"'{p.node_title or p.node_id}'" for p in top)
+            findings.append(WasteFinding(
+                node_id=",".join(p.node_id for p in top),
+                node_title=names,
+                category="expensive_model",
+                severity="high",
+                message=(
+                    f"Two nodes ({names}) account for {fraction:.0%} of tokens. "
+                    f"If they use an expensive model, consider downgrading for simple tasks."
+                ),
+                suggestion=(
+                    "Tasks like classification, extraction, or short summarization "
+                    "often run fine on cheaper models."
+                ),
+            ))
+        return findings

conservation_guardian-0.1.0/src/conservation_guardian/profiler.py

@@ -0,0 +1,108 @@
+"""Per-node profiling: tokens, latency, cost, and historical trends."""
+
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional
+
+
+@dataclass
+class NodeSample:
+    """A single profiling observation for a node execution."""
+
+    node_id: str
+    input_tokens: int
+    output_tokens: int
+    latency_ms: float
+    cost_usd: float
+    node_title: str = ""
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+@dataclass
+class NodeProfile:
+    """Aggregate stats for a single workflow node across runs."""
+
+    node_id: str
+    node_title: str = ""
+    samples: list[NodeSample] = field(default_factory=list, repr=False)
+
+    def record(self, sample: NodeSample) -> None:
+        self.samples.append(sample)
+        if sample.node_title and not self.node_title:
+            self.node_title = sample.node_title
+
+    @property
+    def run_count(self) -> int:
+        return len(self.samples)
+
+    @property
+    def avg_input_tokens(self) -> float:
+        return statistics.mean(s.input_tokens for s in self.samples) if self.samples else 0.0
+
+    @property
+    def avg_output_tokens(self) -> float:
+        return statistics.mean(s.output_tokens for s in self.samples) if self.samples else 0.0
+
+    @property
+    def avg_latency_ms(self) -> float:
+        return statistics.mean(s.latency_ms for s in self.samples) if self.samples else 0.0
+
+    @property
+    def avg_cost(self) -> float:
+        return statistics.mean(s.cost_usd for s in self.samples) if self.samples else 0.0
+
+    @property
+    def total_cost(self) -> float:
+        return sum(s.cost_usd for s in self.samples)
+
+    @property
+    def total_tokens(self) -> int:
+        return sum(s.input_tokens + s.output_tokens for s in self.samples)
+
+    @property
+    def input_output_ratio(self) -> float:
+        avg_out = self.avg_output_tokens
+        return self.avg_input_tokens / avg_out if avg_out > 0 else float("inf")
+
+    def cost_trend(self, last_n: int = 10) -> list[float]:
+        return [s.cost_usd for s in self.samples[-last_n:]]
+
+    def latency_trend(self, last_n: int = 10) -> list[float]:
+        return [s.latency_ms for s in self.samples[-last_n:]]
+
+    def is_degrading(self, window: int = 5) -> bool:
+        """Return *True* if latency is trending upward over the last *window* runs."""
+        if len(self.samples) < window * 2:
+            return False
+        recent = [s.latency_ms for s in self.samples[-window:]]
+        earlier = [s.latency_ms for s in self.samples[-window * 2:-window]]
+        return statistics.mean(recent) > statistics.mean(earlier) * 1.2
+
+
+class Profiler:
+    """Collects and queries per-node profiles."""
+
+    def __init__(self) -> None:
+        self._profiles: dict[str, NodeProfile] = {}
+
+    def record(self, sample: NodeSample) -> None:
+        profile = self._profiles.get(sample.node_id)
+        if profile is None:
+            profile = NodeProfile(node_id=sample.node_id, node_title=sample.node_title)
+            self._profiles[sample.node_id] = profile
+        profile.record(sample)
+
+    def get(self, node_id: str) -> Optional[NodeProfile]:
+        return self._profiles.get(node_id)
+
+    def all_profiles(self) -> list[NodeProfile]:
+        return list(self._profiles.values())
+
+    def top_by_cost(self, n: int = 5) -> list[NodeProfile]:
+        return sorted(self._profiles.values(), key=lambda p: p.total_cost, reverse=True)[:n]
+
+    def top_by_tokens(self, n: int = 5) -> list[NodeProfile]:
+        return sorted(self._profiles.values(), key=lambda p: p.total_tokens, reverse=True)[:n]

conservation_guardian-0.1.0/src/conservation_guardian/report.py

@@ -0,0 +1,81 @@
+"""Markdown conservation reports."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .analyzer import WorkflowDAG
+from .budget import WorkflowBudget
+from .detector import WasteFinding
+from .profiler import Profiler
+
+
+def render_report(
+    *,
+    budget: Optional[WorkflowBudget] = None,
+    dag: Optional[WorkflowDAG] = None,
+    profiler: Optional[Profiler] = None,
+    findings: Optional[list[WasteFinding]] = None,
+    workflow_name: str = "Workflow",
+) -> str:
+    """Render a full Markdown conservation report."""
+    parts: list[str] = []
+    parts.append(f"# Conservation Report — {workflow_name}\n")
+
+    if budget is not None:
+        parts.append("\n## Budget Summary\n")
+        parts.append(f"- **Max tokens / run:** {budget.max_tokens_per_run:,}")
+        parts.append(f"- **Max cost / day:** ${budget.max_cost_per_day:.2f}")
+        parts.append(f"- **Max nodes / workflow:** {budget.max_nodes_per_workflow}")
+        parts.append(f"- **Today's spend:** ${budget.daily_spend():.4f}")
+        parts.append(f"- **Avg tokens / run:** {budget.avg_tokens_per_run():,.0f}")
+
+    if dag is not None:
+        parts.append("\n## DAG Analysis\n")
+        parts.append(f"- **Total nodes:** {len(dag.nodes)}")
+        parts.append(f"- **LLM nodes:** {len(dag.llm_nodes())}")
+
+        redundant = dag.redundant_llm_calls()
+        if redundant:
+            parts.append(f"- **Redundant LLM calls:** {len(redundant)}")
+            for a, b in redundant:
+                parts.append(f"  - `{a.title or a.id}` ↔ `{b.title or b.id}` (same model & upstream)")
+        else:
+            parts.append("- **Redundant LLM calls:** None detected ✅")
+
+        dead = dag.dead_branches()
+        if dead:
+            parts.append(f"- **Dead branches:** {len(dead)}")
+            for path in dead:
+                labels = [dag.nodes[nid].title or nid for nid in path if nid in dag.nodes]
+                parts.append(f"  - `{' → '.join(labels)}`")
+        else:
+            parts.append("- **Dead branches:** None detected ✅")
+
+    if profiler is not None:
+        parts.append("\n## Top Nodes by Cost\n")
+        top = profiler.top_by_cost(5)
+        if top:
+            parts.append("| Node | Runs | Avg In | Avg Out | Avg Cost | Total Cost |")
+            parts.append("|------|------|--------|---------|----------|------------|")
+            for p in top:
+                parts.append(
+                    f"| {p.node_title or p.node_id} | {p.run_count} | "
+                    f"{p.avg_input_tokens:,.0f} | {p.avg_output_tokens:,.0f} | "
+                    f"${p.avg_cost:.4f} | ${p.total_cost:.4f} |"
+                )
+        else:
+            parts.append("_No profiling data yet._")
+
+    if findings:
+        parts.append("\n## Waste Findings\n")
+        for f in findings:
+            icon = {"high": "🔴", "medium": "🟡", "low": "🟢"}.get(f.severity, "⚪")
+            parts.append(f"\n### {icon} {f.category.replace('_', ' ').title()} — {f.node_title or f.node_id}\n")
+            parts.append(f"\n{f.message}")
+            parts.append(f"\n> **Suggestion:** {f.suggestion}\n")
+    elif profiler is not None:
+        parts.append("\n## Waste Findings\n")
+        parts.append("_No waste detected._ ✅")
+
+    return "\n".join(parts) + "\n"

conservation_guardian-0.1.0/src/conservation_guardian.egg-info/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: conservation-guardian
+Version: 0.1.0
+Summary: Generic Workflow Conservation Engine — analyze any workflow for cost efficiency and detect waste
+Author: SuperInstance
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SuperInstance/conservation-guardian
+Keywords: workflow,cost,optimization,conservation,guardian,efficiency,waste-detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Conservation Guardian
+
+A **generic** Workflow Conservation Engine — analyze any workflow for cost efficiency and detect waste.
+
+> Your workflow costs $12/day. Two nodes account for 78% of tokens. They both call GPT-4 for tasks GPT-4o-mini handles.
+
+Conservation Guardian is a framework-agnostic Python library that analyzes workflow execution for cost efficiency and detects waste. It doesn't change your workflows — it tells you what to change and why. Works with any workflow engine (Dify, n8n, LangGraph, Temporal, custom DAGs, etc.).
+
+## What It Does
+
+**Budget tracking** — Set hard limits on tokens per run, cost per day, and node count. Know immediately when a workflow crosses a threshold.
+
+**DAG analysis** — Parse any workflow JSON and surface:
+- Redundant LLM calls (same model, same upstream, same job)
+- Dead branches (conditional paths that never execute)
+
+**Per-node profiling** — Track tokens in/out, latency, and cost for every node across runs. Spot degradation before it hurts.
+
+**Waste detection** — Find the expensive stuff nobody notices:
+- **Overprompted nodes** — 4,200 tokens in, 180 out. You're paying for context the model ignores.
+- **Idle nodes** — Running every time, contributing 0.1% of value.
+- **Model mismatch** — Using GPT-4 for classification that GPT-4o-mini handles in 12ms.
+
+**Reports** — Markdown summaries you can paste into Slack, Notion, or a PR comment.
+
+## Install
+
+```bash
+pip install conservation-guardian
+```
+
+## Quick Start
+
+```python
+from conservation_guardian.budget import WorkflowBudget
+from conservation_guardian.analyzer import WorkflowDAG
+from conservation_guardian.profiler import Profiler, NodeSample
+from conservation_guardian.detector import WasteDetector
+from conservation_guardian.report import render_report
+
+# 1. Load a workflow (generic — works with any engine's JSON)
+dag = WorkflowDAG.from_dict(workflow_json)
+print(f"{len(dag.llm_nodes())} LLM nodes, {len(dag.redundant_llm_calls())} redundant")
+
+# 2. Profile some runs
+profiler = Profiler()
+profiler.record(NodeSample(
+    node_id="summarizer",
+    input_tokens=4200,
+    output_tokens=180,
+    latency_ms=820.0,
+    cost_usd=0.015,
+))
+
+# 3. Detect waste
+detector = WasteDetector(profiler)
+findings = detector.detect()
+for f in findings:
+    print(f"[{f.severity}] {f.message}")
+    print(f"  → {f.suggestion}")
+
+# 4. Generate report
+budget = WorkflowBudget()
+report = render_report(budget=budget, dag=dag, profiler=profiler, findings=findings)
+print(report)
+```
+
+## Differences from dify-workflow-guardian
+
+- **Framework-agnostic**: No Dify-specific assumptions in the analyzer
+- **Extended node types**: Recognizes `llm`, `llm-chain`, `chat-model`, `switch`, `conditional`, and more
+- **Same API**: Drop-in replacement — just change the import package name
+
+## Module Structure
+
+| File | Purpose |
+|------|---------|
+| `budget.py` | `WorkflowBudget` — token/cost/node limits and daily tracking |
+| `analyzer.py` | `WorkflowDAG` — parse workflow JSON, find redundancies and dead branches |
+| `profiler.py` | `Profiler`, `NodeProfile`, `NodeSample` — per-node stats and trends |
+| `detector.py` | `WasteDetector`, `WasteFinding` — surface actionable waste |
+| `report.py` | `render_report()` — Markdown conservation reports |
+
+## Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Philosophy
+
+Conservation Guardian doesn't optimize your workflows. It tells you where the money goes and what to do about it. The fixes are yours to make — but at least you'll know where to look.
+
+Built for [SuperInstance](https://github.com/SuperInstance).
+
+## License
+
+MIT

conservation_guardian-0.1.0/src/conservation_guardian.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/conservation_guardian/__init__.py
+src/conservation_guardian/analyzer.py
+src/conservation_guardian/budget.py
+src/conservation_guardian/detector.py
+src/conservation_guardian/profiler.py
+src/conservation_guardian/report.py
+src/conservation_guardian.egg-info/PKG-INFO
+src/conservation_guardian.egg-info/SOURCES.txt
+src/conservation_guardian.egg-info/dependency_links.txt
+src/conservation_guardian.egg-info/top_level.txt
+tests/test_guardian.py

conservation_guardian-0.1.0/src/conservation_guardian.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

conservation_guardian-0.1.0/src/conservation_guardian.egg-info/top_level.txt

@@ -0,0 +1 @@
+conservation_guardian

conservation_guardian-0.1.0/tests/test_guardian.py

@@ -0,0 +1,258 @@
+"""Tests for the guardian module."""
+
+from __future__ import annotations
+
+import pytest
+
+from conservation_guardian.budget import WorkflowBudget
+from conservation_guardian.analyzer import WorkflowDAG
+from conservation_guardian.profiler import Profiler, NodeSample
+from conservation_guardian.detector import WasteDetector, WasteFinding
+from conservation_guardian.report import render_report
+
+
+# ---------------------------------------------------------------------------
+# Budget
+# ---------------------------------------------------------------------------
+
+class TestWorkflowBudget:
+    def test_default_limits(self):
+        b = WorkflowBudget()
+        assert b.max_tokens_per_run == 500_000
+        assert b.max_cost_per_day == 50.0
+        assert b.max_nodes_per_workflow == 100
+
+    def test_is_within_budget_ok(self):
+        b = WorkflowBudget()
+        assert b.is_within_budget(100_000, 50_000) is True
+
+    def test_is_within_budget_exceeds_tokens(self):
+        b = WorkflowBudget(max_tokens_per_run=1_000)
+        assert b.is_within_budget(800, 300) is False
+
+    def test_is_within_budget_exceeds_daily_cost(self):
+        b = WorkflowBudget(max_cost_per_day=0.01)
+        b.record_run(100_000, 50_000)
+        assert b.is_within_budget(100_000, 50_000) is False
+
+    def test_record_run_returns_cost(self):
+        b = WorkflowBudget()
+        cost = b.record_run(1_000, 1_000)
+        assert cost > 0
+        assert b.daily_spend() == cost
+
+    def test_check_node_count(self):
+        b = WorkflowBudget(max_nodes_per_workflow=5)
+        assert b.check_node_count(5) is True
+        assert b.check_node_count(6) is False
+
+    def test_avg_tokens_per_run(self):
+        b = WorkflowBudget()
+        b.record_run(1_000, 500)
+        b.record_run(2_000, 500)
+        assert b.avg_tokens_per_run() == 2_000.0
+
+    def test_avg_tokens_no_runs(self):
+        b = WorkflowBudget()
+        assert b.avg_tokens_per_run() == 0.0
+
+
+# ---------------------------------------------------------------------------
+# Analyzer
+# ---------------------------------------------------------------------------
+
+class TestWorkflowDAG:
+    @pytest.fixture()
+    def sample_dag(self) -> WorkflowDAG:
+        raw = {
+            "graph": {
+                "nodes": [
+                    {"id": "start", "data": {"type": "start", "title": "Start"}},
+                    {"id": "llm1", "data": {"type": "llm", "title": "Draft Email", "model": {"provider": "openai", "name": "gpt-4"}}},
+                    {"id": "llm2", "data": {"type": "llm", "title": "Draft Email 2", "model": {"provider": "openai", "name": "gpt-4"}}},
+                    {"id": "if1", "data": {"type": "if-else", "title": "Check Urgency"}},
+                    {"id": "tool1", "data": {"type": "tool", "title": "Send Slack"}},
+                    {"id": "end", "data": {"type": "end", "title": "End"}},
+                ],
+                "edges": [
+                    {"sourceId": "start", "targetId": "llm1"},
+                    {"sourceId": "start", "targetId": "llm2"},
+                    {"sourceId": "llm1", "targetId": "if1"},
+                    {"sourceId": "if1", "targetId": "tool1"},
+                    {"sourceId": "if1", "targetId": "end"},
+                ],
+            }
+        }
+        return WorkflowDAG.from_dict(raw)
+
+    def test_parse_nodes(self, sample_dag: WorkflowDAG):
+        assert len(sample_dag.nodes) == 6
+        assert sample_dag.entry_node == "start"
+
+    def test_llm_nodes(self, sample_dag: WorkflowDAG):
+        llms = sample_dag.llm_nodes()
+        assert len(llms) == 2
+
+    def test_redundant_llm_calls(self, sample_dag: WorkflowDAG):
+        redundant = sample_dag.redundant_llm_calls()
+        assert len(redundant) == 1
+        a, b = redundant[0]
+        assert "llm" in a.id and "llm" in b.id
+
+    def test_from_empty_dict(self):
+        dag = WorkflowDAG.from_dict({})
+        assert len(dag.nodes) == 0
+
+
+# ---------------------------------------------------------------------------
+# Profiler
+# ---------------------------------------------------------------------------
+
+class TestProfiler:
+    @pytest.fixture()
+    def profiler_with_data(self) -> Profiler:
+        p = Profiler()
+        for i in range(20):
+            p.record(NodeSample(
+                node_id="summarizer",
+                input_tokens=4_200,
+                output_tokens=180,
+                latency_ms=800.0 + i * 10,
+                cost_usd=0.015,
+                node_title="Summarizer",
+            ))
+        p.record(NodeSample(
+            node_id="classifier",
+            input_tokens=500,
+            output_tokens=10,
+            latency_ms=200.0,
+            cost_usd=0.002,
+            node_title="Classifier",
+        ))
+        return p
+
+    def test_run_count(self, profiler_with_data: Profiler):
+        p = profiler_with_data.get("summarizer")
+        assert p is not None
+        assert p.run_count == 20
+
+    def test_avg_tokens(self, profiler_with_data: Profiler):
+        p = profiler_with_data.get("summarizer")
+        assert p.avg_input_tokens == 4_200.0
+        assert p.avg_output_tokens == 180.0
+
+    def test_input_output_ratio(self, profiler_with_data: Profiler):
+        p = profiler_with_data.get("summarizer")
+        assert p.input_output_ratio == pytest.approx(4200 / 180, rel=0.01)
+
+    def test_top_by_cost(self, profiler_with_data: Profiler):
+        top = profiler_with_data.top_by_cost(1)
+        assert top[0].node_id == "summarizer"
+
+    def test_is_degrading(self, profiler_with_data: Profiler):
+        p = profiler_with_data.get("summarizer")
+        # Record more with much higher latency to trigger degradation
+        for i in range(10):
+            profiler_with_data.record(NodeSample(
+                node_id="summarizer",
+                input_tokens=4_200,
+                output_tokens=180,
+                latency_ms=2000.0 + i * 100,
+                cost_usd=0.015,
+            ))
+        assert p.is_degrading() is True
+
+    def test_not_degrading(self):
+        p = Profiler()
+        for i in range(20):
+            p.record(NodeSample(
+                node_id="stable",
+                input_tokens=100,
+                output_tokens=100,
+                latency_ms=500.0,
+                cost_usd=0.01,
+            ))
+        profile = p.get("stable")
+        assert profile is not None
+        assert profile.is_degrading() is False
+
+
+# ---------------------------------------------------------------------------
+# Detector
+# ---------------------------------------------------------------------------
+
+class TestWasteDetector:
+    @pytest.fixture()
+    def detector(self) -> WasteDetector:
+        p = Profiler()
+        for _ in range(10):
+            p.record(NodeSample(
+                node_id="summarizer",
+                input_tokens=4_200,
+                output_tokens=180,
+                latency_ms=800.0,
+                cost_usd=0.015,
+                node_title="Summarizer",
+            ))
+        for _ in range(10):
+            p.record(NodeSample(
+                node_id="rephraser",
+                input_tokens=500,
+                output_tokens=500,
+                latency_ms=300.0,
+                cost_usd=0.005,
+                node_title="Rephraser",
+            ))
+        return WasteDetector(p)
+
+    def test_detect_finds_overprompted(self, detector: WasteDetector):
+        findings = detector.detect()
+        categories = [f.category for f in findings]
+        assert "overprompted" in categories
+
+    def test_overprompted_message(self, detector: WasteDetector):
+        findings = [f for f in detector.detect() if f.category == "overprompted"]
+        assert len(findings) == 1
+        assert "4,200" in findings[0].message
+        assert "180" in findings[0].message
+
+    def test_no_findings_on_empty(self):
+        p = Profiler()
+        d = WasteDetector(p)
+        assert d.detect() == []
+
+
+# ---------------------------------------------------------------------------
+# Report
+# ---------------------------------------------------------------------------
+
+class TestReport:
+    def test_renders_markdown(self):
+        b = WorkflowBudget()
+        p = Profiler()
+        p.record(NodeSample(
+            node_id="test",
+            input_tokens=1000,
+            output_tokens=100,
+            latency_ms=500.0,
+            cost_usd=0.01,
+            node_title="Test Node",
+        ))
+        findings = [WasteFinding(
+            node_id="test",
+            node_title="Test Node",
+            category="overprompted",
+            severity="high",
+            message="Test message",
+            suggestion="Test suggestion",
+        )]
+        report = render_report(budget=b, profiler=p, findings=findings, workflow_name="TestFlow")
+        assert "# Conservation Report — TestFlow" in report
+        assert "Budget Summary" in report
+        assert "Top Nodes by Cost" in report
+        assert "Waste Findings" in report
+        assert "Test Node" in report
+
+    def test_empty_report(self):
+        report = render_report(workflow_name="Empty")
+        assert "Conservation Report" in report