execweave 0.6.0__py3-none-any.whl

execweave-0.6.0.dist-info/METADATA

@@ -0,0 +1,356 @@
+Metadata-Version: 2.5
+Name: execweave
+Version: 0.6.0
+Summary: Turn AI-agent runtime behavior into a local interactive execution graph.
+Project-URL: Homepage, https://github.com/Irish-kw/ExecWeave
+Project-URL: Repository, https://github.com/Irish-kw/ExecWeave
+Project-URL: Documentation, https://github.com/Irish-kw/ExecWeave#documentation
+Project-URL: Issues, https://github.com/Irish-kw/ExecWeave/issues
+Author: ExecWeave contributors
+License: MIT License
+        
+        Copyright (c) 2026 GWW
+        
+        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.
+License-File: LICENSE
+Keywords: ai-agents,execution-graph,observability,provenance,runtime,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: psutil>=5.9
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=6.0; extra == 'release'
+Description-Content-Type: text/markdown
+
+# ExecWeave
+
+<p align="center">
+  <strong>English</strong> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.ja.md">日本語</a> |
+  <a href="README.ko.md">한국어</a>
+</p>
+
+**See what AI agents actually do on your machine.**
+
+ExecWeave is an open-source, local-first observability project that turns AI-agent activity into an interactive execution graph while keeping observed evidence separate from inference.
+
+> **Event is ground truth. The graph is a materialized view.**
+
+## Install
+
+ExecWeave v0.6.0 is packaged as a standard Python wheel/sdist. The repository is PyPI-ready; until the first Trusted Publisher release is made, install the package directly from GitHub:
+
+```bash
+python -m pip install "execweave @ git+https://github.com/Irish-kw/ExecWeave.git@main"
+```
+
+For development:
+
+```bash
+git clone https://github.com/Irish-kw/ExecWeave.git
+cd ExecWeave
+python -m pip install -e ".[dev]"
+```
+
+Once the first PyPI release is published, installation becomes:
+
+```bash
+python -m pip install execweave
+```
+
+Watch any command live:
+
+```bash
+execweave live --open -- claude
+```
+
+Or build the full artifact pipeline:
+
+```bash
+execweave record --open -- python my_agent.py
+```
+
+## Performance and footprint
+
+ExecWeave includes a reproducible package-level overhead benchmark that is run from an installed wheel. The reference plot follows the same trade-off style commonly used for model quality/cost comparisons:
+
+- **X-axis:** additional peak process-tree RSS, low → high.
+- **Y-axis:** runtime overhead, low → high.
+- **Bubble area:** median artifact size per run.
+- **Preferred region:** lower-left.
+
+![ExecWeave overhead trade-off](docs/benchmarks/v0.6.0-github-actions.svg)
+
+Reference environment: GitHub Actions Ubuntu runner, Intel Xeon Platinum 8573C, 4 logical CPUs, Python 3.12.14, `n=7`.
+
+| Profile | Median wall time | Runtime overhead | Additional peak RSS | Median artifacts/run |
+| --- | ---: | ---: | ---: | ---: |
+| ExecWeave OFF | 236.221 ms | 0.0% | 0.0 MB | 0 KB |
+| Portable ON | 391.580 ms | 65.768% | 27.852 MB | 741.355 KB |
+| Strace ON | 1226.076 ms | 419.038% | 37.653 MB | 572.838 KB |
+
+The same build produced an approximately **113 KB wheel** and **198 KB sdist**. The installed ExecWeave distribution footprint was about **849 KB**, excluding Python and dependency footprints.
+
+This is a deliberately short, file/process-heavy **reference microbenchmark**, not a universal workload claim. Percentage overhead is amplified because the uninstrumented baseline is only a few hundred milliseconds. Re-run `execweave-overhead` on the target host and representative workload before making capacity decisions.
+
+```bash
+execweave-overhead \
+  --iterations 7 \
+  --strace auto \
+  --output-json benchmark-results.json \
+  --output-svg benchmark-overhead.svg
+```
+
+Raw reference data and methodology: [`docs/benchmarks/`](docs/benchmarks/).
+
+## Evidence layers
+
+ExecWeave intentionally models four different layers instead of flattening them into one trace:
+
+```text
+Agent / IDE semantic evidence
+          ↓
+Inference gateway / routing evidence
+          ↓
+Model runtime / inference-server evidence
+          ↓
+OS runtime evidence: process / file / network
+```
+
+A relationship is only causal when the underlying telemetry supports that claim.
+
+## Agent / IDE integrations
+
+### Claude Code
+
+```bash
+execweave-claude-hook --print-config
+execweave-claude-record --open -- claude
+```
+
+### OpenAI Codex
+
+```bash
+execweave-codex-hook --print-config
+execweave-codex-record --open -- codex
+```
+
+### Gemini CLI
+
+```bash
+execweave-gemini-hook --print-config
+execweave-gemini-record --open -- gemini
+```
+
+### Cursor
+
+```bash
+execweave-cursor-hook --print-config
+execweave-cursor-record --open -- cursor
+```
+
+Cursor provides a stable `tool_use_id`, allowing exact logical tool-call identity across its pre/post hooks.
+
+### OpenCode
+
+```bash
+execweave-opencode-plugin --install
+execweave-opencode-record --open -- opencode
+```
+
+The project-local OpenCode plugin uses exact `sessionID + callID` identity and deliberately does not forward tool output.
+
+Provider-integrated runs preserve runtime, semantic, and correlated artifacts separately. Tool → Process bridges remain conservative derived evidence:
+
+```text
+inferred: true
+causal: false
+```
+
+Ambiguity produces no edge.
+
+## Inference gateway integrations
+
+OpenRouter and LiteLLM Proxy are modeled as `inference_gateway`, not as local model runtimes.
+
+```bash
+execweave-inference-gateway event \
+  --gateway litellm \
+  --requested-model assistant \
+  --resolved-model azure/gpt-5 \
+  --provider-name Azure \
+  --deployment-id deployment-west \
+  --sidecar gateway.jsonl
+```
+
+ExecWeave keeps requested model, resolved model, routed provider, and deployment identity distinct. Provider/deployment edges are only emitted when authoritative metadata is supplied; they are never inferred from a model-name prefix.
+
+When the caller has an explicit shared identity across Gateway and Model Runtime observations, the two request nodes can be linked without collapsing layers:
+
+```bash
+execweave-inference-link \
+  --gateway litellm \
+  --gateway-request-id gw-123 \
+  --runtime vllm \
+  --runtime-request-id rt-456 \
+  --shared-request-id trace-789 \
+  --sidecar inference.jsonl
+```
+
+`SAME_INFERENCE_REQUEST` is exact identity evidence, not causal evidence:
+
+```text
+identity_exact: true
+inferred: false
+causal: false
+```
+
+The raw shared request ID is not persisted; only a SHA-256-derived identity hash is stored.
+
+## Model runtime integrations
+
+Current model-runtime integrations are **Ollama**, **llama.cpp**, **vLLM**, and **LM Studio**.
+
+```bash
+execweave-model-runtime event --runtime ollama --sidecar model-runtime.jsonl
+execweave-model-runtime event --runtime llamacpp --sidecar model-runtime.jsonl
+execweave-model-runtime event --runtime vllm --sidecar model-runtime.jsonl
+execweave-model-runtime event --runtime lmstudio --sidecar model-runtime.jsonl
+```
+
+OpenAI-compatible runtimes share response/usage and model-catalog parsing while retaining runtime-specific evidence semantics. Prompt, generated, and reasoning content are not stored. Sensitive local model paths are redacted; llama.cpp keeps stricter GGUF-path redaction.
+
+LM Studio model-catalog visibility is represented as `ADVERTISES_MODEL`, not as proof that model weights are loaded in memory.
+
+## Runtime evidence
+
+The portable collector runs on Linux, macOS, and Windows. Linux also has a syscall-backed `strace` reference backend.
+
+```bash
+execweave doctor
+execweave run --backend portable -- your-command
+execweave run --backend strace -- your-command
+```
+
+Portable filesystem watching is session-correlated rather than process-causal, and short-lived processes can be missed between polling intervals. The Linux `strace` path captures process-attributed syscall evidence after the command exits.
+
+Future native collectors remain planned for Linux eBPF, Windows ETW, and macOS Endpoint Security.
+
+## Layered artifacts
+
+A provider-integrated run can produce:
+
+```text
+.execweave/runs/<run-id>/
+├── events.jsonl
+├── graph.json
+├── viewer.html
+├── semantic.jsonl
+├── events.semantic.jsonl
+├── graph.semantic.json
+├── viewer.semantic.html
+├── events.correlated.jsonl
+├── graph.correlated.json
+└── viewer.correlated.html
+```
+
+Raw evidence is never rewritten by the derived correlation layer.
+
+## Interactive Viewer
+
+The standalone Viewer is local and self-contained. Current baseline includes pan/zoom, draggable nodes, node/edge inspection, node-type/relation/causal filters, **observed only**, search, evidence-sequence replay, progressive cluster expansion, focused neighborhoods, Saved Views, explicit edge semantics, and Correlation Summary.
+
+## Graph operations
+
+```bash
+execweave graph-summary run.graph.json
+execweave graph-filter run.graph.json --output causal.graph.json --causal-only
+execweave graph-focus run.graph.json NODE_ID --hops 2 --output focused.graph.json
+execweave path run.graph.json SOURCE TARGET --causal-only
+execweave graph-condense run.graph.json --output compact.graph.json --threshold 8 --keep-expansion
+```
+
+## Security analysis
+
+```bash
+execweave analyze run.graph.json --output analysis.json
+```
+
+Security findings remain explicit about evidence limits. A possible sensitive-file → network path does not imply byte-level exfiltration:
+
+```json
+{
+  "data_flow_proven": false,
+  "exfiltration_proven": false
+}
+```
+
+## Current status
+
+ExecWeave is currently **v0.6.0** and under active development.
+
+The baseline includes runtime collection, graph materialization/querying, standalone/live Viewer, Claude/Codex/Gemini/Cursor/OpenCode semantic integrations, conservative Tool → Process correlation, OpenRouter/LiteLLM gateway metadata, Ollama/llama.cpp/vLLM/LM Studio runtime metadata, exact Gateway ↔ Model Runtime request identity, PyPI-ready wheel/sdist packaging, reproducible overhead benchmarking, and cross-platform CI on Python 3.10/3.12.
+
+## Privacy
+
+ExecWeave is local-first. Runtime events, semantic sidecars, graphs, reports, and Viewers remain local by default. File contents and raw read/write byte buffers are not intentionally captured. Native adapters also avoid prompts/transcripts/tool output by default, but commands, paths, endpoint metadata, identifiers, and model metadata can still be sensitive.
+
+Review artifacts before sharing them.
+
+## Documentation
+
+- [`Phase 1 — Runtime Collection`](docs/phase-1-runtime-collection.md)
+- [`Phase 2 — Execution Graph`](docs/phase-2-execution-graph.md)
+- [`Live Graph`](docs/live-graph.md)
+- [`Semantic Telemetry`](docs/semantic-telemetry.md)
+- [`Claude Code Hooks`](docs/claude-code-hooks.md)
+- [`OpenAI Codex Hooks`](docs/codex-hooks.md)
+- [`Gemini CLI Hooks`](docs/gemini-hooks.md)
+- [`Cursor Hooks`](docs/cursor-hooks.md)
+- [`OpenCode Plugin`](docs/opencode-plugin.md)
+- [`Inference Gateway / OpenRouter / LiteLLM`](docs/inference-gateway.md)
+- [`Model Runtime / Ollama / llama.cpp / vLLM / LM Studio`](docs/model-runtime.md)
+- [`Performance Benchmarks`](docs/benchmarks/README.md)
+- [`Security Analysis`](docs/security-analysis.md)
+
+## Contributing
+
+Contributions are welcome, especially around native OS collectors, additional Agent/IDE adapters, inference gateways, model runtimes, entity/correlation methods, privacy/redaction, graph UX, and performance evaluation.
+
+## License
+
+See [`LICENSE`](LICENSE).

execweave-0.6.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+execweave/__init__.py,sha256=bkl2BlZu8r7JHTOKfKIIkmHRUiD7MWVFXpaTWilKysI,62
+execweave/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+execweave/analysis.py,sha256=9Poq69HmNQ_gsvdTyKpjUkDol4tYYdKZKV9_-JGl6os,16729
+execweave/backends.py,sha256=Z_FxFczEc3pMis-COBO906LNdEGTnmbcWOfDZKNWfM4,1778
+execweave/benchmark.py,sha256=1q7F3c483qU_tXPgUsWeMbpaBwRDuBRp9ABMJF0Kbec,2634
+execweave/claude_adapter.py,sha256=zuWoN-N05Y_jxe4HMMSgrNlVQt3lxFhxpNlLij2kxN8,14860
+execweave/claude_hook_cli.py,sha256=bTjNYz_WEy6bAzA8hg-xg9YgF_KLEZHVLtVR3gVOrOs,3444
+execweave/claude_record.py,sha256=dGRCrzX6x3-MNs2SLEWKmCSbyYK_0-7a1Gnmp1gcpZA,3587
+execweave/cli.py,sha256=Et0ILR2Eq5bBaDLVsG1uuYkoBDRRy0T0wYo_b9YBNQI,21309
+execweave/codex_adapter.py,sha256=nKfJnqlfX3VPJL4ASk0zHOH25ELQLb46mzdIQT7jRoU,10183
+execweave/codex_hook_cli.py,sha256=oW5trzijBzP9t0cMusg2banyA2okaO8zvip0aGn9t6E,3311
+execweave/codex_record.py,sha256=08hL-sqBZm9Cl4slroFObglPSfy8dn7eSmhvt-kQKOQ,3803
+execweave/collector.py,sha256=LHhgRwvuyan4_HGb4dtOM5L3dzlG-eGP61lepGU9EkE,10493
+execweave/correlation.py,sha256=ov4Pw0uO1o2Dm3ox0R49xGC0Xyr18kcI2XdsX7TLjx8,20739
+execweave/cursor_adapter.py,sha256=ssxECLnZNhSGBhVVuO7RgjKRpUCTfI_W3SCE92Utzms,11290
+execweave/cursor_hook_cli.py,sha256=cE4VXhBQjOAtZ9AQYYLRSeHdmTp4EuGKw1r-S62wOFA,2862
+execweave/cursor_record.py,sha256=WKK4Nfod2Q1ENF4ZnA5fCyXYGuCDng1zNWyfhxFWwTM,3354
+execweave/filesystem.py,sha256=RiymQyGeJL0jyzV0KKaQ3d6AxTQlEKvnabgyK2xuxEI,3350
+execweave/focus.py,sha256=lpKfn820oJ9r77vbSUuLMMuci88A1yTrB5-UOGCkNOI,4428
+execweave/gemini_adapter.py,sha256=JxTpsUZXuD0AGXiaRjpNBXs4SMUD7eVcdZZd-7J1xSU,12433
+execweave/gemini_hook_cli.py,sha256=tjAd18wRe8d7iQuSUfO0KNy-QCMCFgAygTlZXT6jxYk,2864
+execweave/gemini_record.py,sha256=PaN4uqYVCKgVaDAeYBc0UkC-z4BnJ3qGWNDi2Jo0Tvg,3406
+execweave/graph.py,sha256=JrlsPOyB6mfir_2Kc_R0lG5L21J-jluI7jHFTSo8zXU,11704
+execweave/graph_ops.py,sha256=6nGGLDKM_U3L3K8DfMh36BxMe6rUgKmvBaO_8k-FWRI,16786
+execweave/inference_gateway.py,sha256=l7dRP1r7TYeRLkKUuxH-6v1arB3zIz3wRveZj8dH08c,13978
+execweave/inference_gateway_cli.py,sha256=fLQQQNewV7GKvosRtJAJcnkw22LeBoE3KYq9p-CMbgM,3678
+execweave/inference_identity.py,sha256=-QdHgLJ0XiMrWbOT2E49EwQ2vMSHsWxJ7WFOrCprfu8,2418
+execweave/inference_identity_cli.py,sha256=kG74ZJuu-74533xaNxGILc349VuieKTQ9Z1ubPUjDCE,2026
+execweave/live.py,sha256=66nwOSnXI1BfMrHmmf-oLLX9hAvPs760gxINv2fbxw0,17912
+execweave/model_runtime.py,sha256=lmEzXytiBTLFvjecRa9gDNkTqIkPVhhmV-thEfn5kko,17052
+execweave/model_runtime_cli.py,sha256=QBfVYBz_4N5FHPBEgI3DNWTX7A1TsOeT79zTa-E_-l8,5413
+execweave/opencode_adapter.py,sha256=ctkzx5unpogFp65GrbbAJHTTfX5cfsUKKbCVbJRFXoQ,10120
+execweave/opencode_hook_cli.py,sha256=tQ7rhtxOceSjUHwQkYgl-KvgJZC3FOGR-eYq2aHj5NU,1850
+execweave/opencode_plugin_cli.py,sha256=77TEH6izZtkjSD0LjSGeg1FC50BHC4XbDwRFga_40aI,3249
+execweave/opencode_record.py,sha256=L7JKQ1acV1y7mfFiZkC7SsPrLenfoG7dpfd0DnUXPOs,3377
+execweave/overhead_benchmark.py,sha256=Udamkj8xB02NMoE8Z3ygDWtrMlBIvothN5ImduC6Hpo,17029
+execweave/provider_record.py,sha256=Z4n2GsQRmCZTz7gVR2yvS6jBLn2OKgSTy1z7zkys3iU,8150
+execweave/schema.py,sha256=GnTWju3TbHkW820lIxIHqih985jUJafE3D7YEo9vIM0,1605
+execweave/semantic.py,sha256=xcrB4oGom514xbfrxJOXTOMyVgJF7PhjP2gOKPas_WE,13214
+execweave/sink.py,sha256=BLU1GT5LQgBU8q8SYG5ZpGFAST6qT98d4GA0OiEiDz8,1177
+execweave/strace_backend.py,sha256=CPOYNyZKcoJWV2S_H63F5tm2u4dQEWT8cE04JMIcYT4,24831
+execweave/validate.py,sha256=OJXxyKVBW_jifuWN6WRuhkzO8-S9iY5aoYH86k6KZUc,6676
+execweave/viewer.py,sha256=u6qN-qz38Jz94CuOsp1NUjmgWJrWlGWXOUZNEE7POtY,31404
+execweave/workflow.py,sha256=o65wCQsqUJLfll5EULh83h0XFSRwkhmHsR1iPBc_07o,3608
+execweave-0.6.0.dist-info/METADATA,sha256=3OcDzJ4HLHpf7Vm1TGz1xn9fdiN9pVMG8XdSvuTN-rs,13219
+execweave-0.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+execweave-0.6.0.dist-info/entry_points.txt,sha256=ZwT21nZH-byNJ399kQ10HLKUaipaJiMIQMpenxdACng,912
+execweave-0.6.0.dist-info/licenses/LICENSE,sha256=fSwH9gjMzp7_hc_2crwT-bf8PUhIHDoUvzueU5zAIJ0,1060
+execweave-0.6.0.dist-info/RECORD,,

execweave-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

execweave-0.6.0.dist-info/entry_points.txt

@@ -0,0 +1,17 @@
+[console_scripts]
+execweave = execweave.cli:main
+execweave-claude-hook = execweave.claude_hook_cli:main
+execweave-claude-record = execweave.claude_record:main
+execweave-codex-hook = execweave.codex_hook_cli:main
+execweave-codex-record = execweave.codex_record:main
+execweave-cursor-hook = execweave.cursor_hook_cli:main
+execweave-cursor-record = execweave.cursor_record:main
+execweave-gemini-hook = execweave.gemini_hook_cli:main
+execweave-gemini-record = execweave.gemini_record:main
+execweave-inference-gateway = execweave.inference_gateway_cli:main
+execweave-inference-link = execweave.inference_identity_cli:main
+execweave-model-runtime = execweave.model_runtime_cli:main
+execweave-opencode-hook = execweave.opencode_hook_cli:main
+execweave-opencode-plugin = execweave.opencode_plugin_cli:main
+execweave-opencode-record = execweave.opencode_record:main
+execweave-overhead = execweave.overhead_benchmark:main

execweave-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GWW
+
+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.