dagc 0.1.0__py3-none-any.whl

dagc/__init__.py

@@ -0,0 +1,47 @@
+"""
+dagc — Decision-Anchored Graph Compression.
+
+Compress long agent/chat message histories while guaranteeing that every
+artifact a decision depends on (tool-call arguments, confirmed IDs, cited
+metrics) survives compression. Zero required dependencies, zero LLM calls.
+
+    from dagc import compress
+    compressed = compress(messages, target_reduction=0.85)
+    response = client.chat.completions.create(model="gpt-4", messages=compressed)
+
+Bring your own tokenizer/embedder for production-grade quality:
+
+    import dagc
+    from dagc.adapters import TiktokenTokenizer, SentenceTransformerEmbedder
+    dagc.configure(
+        tokenizer=TiktokenTokenizer("cl100k_base"),
+        embedder=SentenceTransformerEmbedder("all-MiniLM-L6-v2"),
+    )
+
+"""
+from .compressor import compress, compress_any, compress_dagc, DAGCConfig, DAGC_CFG
+from .extraction import extract_decisions
+from .graph import (
+    build_dependency_graph, attach_dependencies, compute_rci, compute_chain_rci,
+    CausalMessageGraph, CausalGraphConfig, SpectralCompressor,
+)
+from .config import configure, Runtime, Tokenizer, Embedder, runtime
+from .formats import (
+    normalize_message, normalize_trace,
+    denormalize_message, denormalize_trace,
+    register_adapter as register_format_adapter,
+)
+from .schema import register_adapter, to_dagc_format
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "compress", "compress_any", "compress_dagc", "DAGCConfig", "DAGC_CFG",
+    "extract_decisions",
+    "build_dependency_graph", "attach_dependencies", "compute_rci", "compute_chain_rci",
+    "CausalMessageGraph", "CausalGraphConfig", "SpectralCompressor",
+    "configure", "Runtime", "Tokenizer", "Embedder", "runtime",
+    "normalize_message", "normalize_trace",
+    "denormalize_message", "denormalize_trace",
+    "register_adapter", "register_format_adapter", "to_dagc_format",
+]

dagc/adapters.py

@@ -0,0 +1,93 @@
+"""
+Optional, real-quality Tokenizer/Embedder adapters. Each is lazily
+imported so that importing `dagc.adapters` never requires having every
+vendor SDK installed -- only the one you actually instantiate.
+
+Install what you need:
+    pip install dagc[tiktoken]
+    pip install dagc[sentence-transformers]
+    pip install dagc[openai]
+
+Or write your own -- any object with .encode()/.decode() (Tokenizer) or
+.encode() -> np.ndarray (Embedder) works, see dagc.config.Tokenizer /
+dagc.config.Embedder for the exact protocol.
+"""
+from __future__ import annotations
+from typing import List
+import numpy as np
+
+
+class TiktokenTokenizer:
+    """Real BPE token counts via OpenAI's tiktoken. pip install tiktoken."""
+    def __init__(self, encoding_name: str = "cl100k_base"):
+        try:
+            import tiktoken
+        except ImportError as e:
+            raise ImportError(
+                "TiktokenTokenizer needs tiktoken. Install it with "
+                "pip install -e '.[tiktoken]'"
+            ) from e
+        self._enc = tiktoken.get_encoding(encoding_name)
+
+    def encode(self, text: str) -> List[int]:
+        return self._enc.encode(str(text))
+
+    def decode(self, tokens: List[int]) -> str:
+        return self._enc.decode(tokens)
+
+
+class SentenceTransformerEmbedder:
+    """Local, free, good-quality embeddings. pip install sentence-transformers."""
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as e:
+            raise ImportError(
+                "SentenceTransformerEmbedder needs sentence-transformers. "
+                "Install it with pip install -e '.[sentence-transformers]'"
+            ) from e
+        self._model = SentenceTransformer(model_name)
+
+    def encode(self, texts: List[str], normalize_embeddings: bool = False) -> np.ndarray:
+        return np.asarray(
+            self._model.encode(list(texts), normalize_embeddings=normalize_embeddings)
+        )
+
+
+class OpenAIEmbedder:
+    """
+    BYOK wrapper around any OpenAI-compatible embeddings endpoint.
+    Pass your own already-configured client (openai.OpenAI(...)) --
+    dagc never sees or stores your API key.
+    """
+    def __init__(self, client, model: str = "text-embedding-3-small"):
+        self._client = client
+        self._model = model
+
+    def encode(self, texts: List[str], normalize_embeddings: bool = False) -> np.ndarray:
+        resp = self._client.embeddings.create(model=self._model, input=list(texts))
+        vecs = np.array([d.embedding for d in resp.data], dtype=np.float32)
+        if normalize_embeddings:
+            norms = np.linalg.norm(vecs, axis=1, keepdims=True)
+            norms[norms == 0] = 1.0
+            vecs = vecs / norms
+        return vecs
+
+
+class CohereEmbedder:
+    """BYOK wrapper around a Cohere client (cohere.Client(...))."""
+    def __init__(self, client, model: str = "embed-english-v3.0",
+                 input_type: str = "search_document"):
+        self._client = client
+        self._model = model
+        self._input_type = input_type
+
+    def encode(self, texts: List[str], normalize_embeddings: bool = False) -> np.ndarray:
+        resp = self._client.embed(texts=list(texts), model=self._model,
+                                   input_type=self._input_type)
+        vecs = np.array(resp.embeddings, dtype=np.float32)
+        if normalize_embeddings:
+            norms = np.linalg.norm(vecs, axis=1, keepdims=True)
+            norms[norms == 0] = 1.0
+            vecs = vecs / norms
+        return vecs

dagc/baselines.py

@@ -0,0 +1,82 @@
+"""
+Optional baseline compressors for comparison against compress_dagc().
+Not imported by dagc/__init__.py automatically -- pull in what you need:
+
+    from dagc.baselines import compress_tail_truncation, compress_random_drop
+"""
+from __future__ import annotations
+import random
+from typing import Dict, List
+
+from .utils import _get_text, _split_sents, _tok
+from .compressor import DAGCConfig, DAGC_CFG
+
+
+def compress_tail_truncation(messages: List[Dict], cfg: DAGCConfig = DAGC_CFG, **kw) -> List[Dict]:
+    """Naive baseline: keep system prompt + as many trailing messages as fit."""
+    orig_toks = sum(_tok(_get_text(m)) for m in messages)
+    budget = max(1, int(orig_toks * (1 - cfg.TARGET_REDUCTION)))
+    sys_msgs = [(i, m) for i, m in enumerate(messages) if m.get('role') == 'system']
+    rest = [(i, m) for i, m in enumerate(messages) if m.get('role') != 'system']
+    kept, used = {}, 0
+    for i, m in sys_msgs:
+        mc = dict(m)
+        toks = _tok(m.get('content', ''))
+        if toks > cfg.SYSTEM_MAX_TOKENS:
+            mc['content'] = m.get('content', '')[: cfg.SYSTEM_MAX_TOKENS * 4] + '[…]'
+        mc['_orig_idx'] = i
+        kept[i] = mc
+        used += _tok(mc.get('content', ''))
+    for i, m in reversed(rest):
+        t = _tok(_get_text(m))
+        if used + t > budget and kept:
+            continue
+        kept[i] = dict(m, _orig_idx=i)
+        used += t
+    return [kept[i] for i in sorted(kept)]
+
+
+def compress_random_drop(messages: List[Dict], cfg: DAGCConfig = DAGC_CFG, seed: int = 0, **kw) -> List[Dict]:
+    """Naive baseline: randomly keep sentences until the budget is spent."""
+    rng = random.Random(seed)
+    orig_toks = sum(_tok(_get_text(m)) for m in messages)
+    budget = max(1, int(orig_toks * (1 - cfg.TARGET_REDUCTION)))
+    n = len(messages)
+    protected = {i for i, m in enumerate(messages)
+                 if m.get('role') == 'system' or i >= n - cfg.KEEP_LAST_K}
+    protected_toks = sum(_tok(_get_text(messages[i])) for i in protected)
+    remaining = max(0, budget - protected_toks)
+    pool = [(s, i) for i, m in enumerate(messages) if i not in protected
+            for s in _split_sents(_get_text(m), cfg.MIN_SENT_TOKENS)]
+    rng.shuffle(pool)
+    chosen, used = [], 0
+    for s, i in pool:
+        t = _tok(s)
+        if used + t <= remaining:
+            chosen.append((s, i))
+            used += t
+    msg_sents: Dict[int, List[str]] = {}
+    for s, i in chosen:
+        msg_sents.setdefault(i, []).append(s)
+    out = []
+    for i, m in enumerate(messages):
+        if i in protected:
+            out.append(dict(m, _orig_idx=i))
+        elif i in msg_sents:
+            mc = dict(m)
+            mc['content'] = ' '.join(msg_sents[i])
+            mc['_orig_idx'] = i
+            out.append(mc)
+    return out
+
+
+def compress_identity(messages: List[Dict], **kw) -> List[Dict]:
+    """No-op baseline: returns the trace unchanged (for measuring the ceiling)."""
+    return [dict(m, _orig_idx=i) for i, m in enumerate(messages)]
+
+
+BASELINES = {
+    'tail_truncation': compress_tail_truncation,
+    'random_drop': compress_random_drop,
+    'identity': compress_identity,
+}

dagc/cli.py

@@ -0,0 +1,112 @@
+"""
+dagc CLI: dagc compress | benchmark | compare | evaluate | stats
+
+Wraps the existing Python API -- no logic duplicated here, just argument
+parsing and dispatch, so behavior always matches the library functions.
+"""
+from __future__ import annotations
+import argparse
+import json
+import sys
+
+
+def _load_trace(path: str):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except FileNotFoundError as exc:
+        raise SystemExit(f"Trace file not found: {path}\nProvide a JSON trace file, for example: dagc evaluate your_trace.json") from exc
+
+
+def cmd_compress(args):
+    import dagc
+    messages = _load_trace(args.input)
+    result = dagc.compress(messages, target_reduction=args.target_reduction)
+    out = json.dumps(result, indent=2, default=str)
+    if args.output:
+        with open(args.output, 'w') as f:
+            f.write(out)
+        print(f"Wrote compressed trace to {args.output}")
+    else:
+        print(out)
+
+
+def cmd_evaluate(args):
+    from dagc_eval import compute_drr
+    messages = _load_trace(args.input)
+    result = compute_drr(messages, verbose=not args.quiet,
+                          decision_roles=tuple(args.decision_roles.split(',')))
+    print(f"\nDRR_soft={result['DRR_soft']}  DRR_binary={result['DRR_binary']}  "
+          f"RCI={result['RCI']}  reduction={result.get('reduction', 0):.1f}%")
+    if args.output:
+        from dagc_eval.export import to_json, to_csv, to_markdown, to_html
+        ext = args.output.rsplit('.', 1)[-1].lower()
+        {'json': to_json, 'csv': to_csv, 'md': to_markdown, 'html': to_html}.get(
+            ext, to_json)(result, args.output)
+        print(f"Wrote report to {args.output}")
+
+
+def cmd_benchmark(args):
+    from dagc_eval import run_benchmark
+    results = run_benchmark(n_traces_per_task=args.n_traces,
+                             noise_levels=[int(x) for x in args.noise_levels.split(',')])
+    if args.output:
+        from dagc_eval.export import to_json, to_csv, to_markdown, to_html
+        ext = args.output.rsplit('.', 1)[-1].lower()
+        {'json': to_json, 'csv': to_csv, 'md': to_markdown, 'html': to_html}.get(
+            ext, to_json)(results, args.output)
+        print(f"Wrote report to {args.output}")
+
+
+def cmd_compare(args):
+    from dagc_eval import run_method_comparison
+    run_method_comparison(n_traces_per_task=args.n_traces,
+                           noise_levels=[int(x) for x in args.noise_levels.split(',')])
+
+
+def cmd_stats(args):
+    from dagc_eval import bootstrap_drr
+    with open(args.input) as f:
+        scores = json.load(f)
+    ci = bootstrap_drr([{'DRR_soft': s} for s in scores])
+    print(f"mean={ci['mean']:.4f}  95% CI=[{ci['ci_lo']:.4f}, {ci['ci_hi']:.4f}]  n={ci['n']}")
+
+
+def main():
+    parser = argparse.ArgumentParser(prog='dagc', description='DAGC — Decision-Anchored Graph Compression CLI')
+    sub = parser.add_subparsers(dest='command', required=True)
+
+    p_compress = sub.add_parser('compress', help='Compress a trace (JSON list of messages)')
+    p_compress.add_argument('input', help='Path to input trace JSON')
+    p_compress.add_argument('-o', '--output', help='Path to write compressed trace JSON')
+    p_compress.add_argument('--target-reduction', type=float, default=0.87)
+    p_compress.set_defaults(func=cmd_compress)
+
+    p_eval = sub.add_parser('evaluate', help='Score a trace with compute_drr')
+    p_eval.add_argument('input', help='Path to input trace JSON')
+    p_eval.add_argument('-o', '--output', help='Path to write report (.json/.csv/.md/.html)')
+    p_eval.add_argument('--decision-roles', default='assistant')
+    p_eval.add_argument('--quiet', action='store_true')
+    p_eval.set_defaults(func=cmd_evaluate)
+
+    p_bench = sub.add_parser('benchmark', help='Run the synthetic-task DRR benchmark sweep')
+    p_bench.add_argument('-o', '--output', help='Path to write report (.json/.csv/.md/.html)')
+    p_bench.add_argument('--n-traces', type=int, default=3)
+    p_bench.add_argument('--noise-levels', default='1,2,3,4,5')
+    p_bench.set_defaults(func=cmd_benchmark)
+
+    p_compare = sub.add_parser('compare', help='Compare DAGC vs BASELINES')
+    p_compare.add_argument('--n-traces', type=int, default=2)
+    p_compare.add_argument('--noise-levels', default='3')
+    p_compare.set_defaults(func=cmd_compare)
+
+    p_stats = sub.add_parser('stats', help='Bootstrap CI over a JSON list of DRR_soft scores')
+    p_stats.add_argument('input', help='Path to JSON list of floats')
+    p_stats.set_defaults(func=cmd_stats)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == '__main__':
+    sys.exit(main())