agentledger-inspector 1.3.0__tar.gz

agentledger_inspector-1.3.0/.gitignore

@@ -0,0 +1,64 @@
+.agentledger/
+go/.agentledger-go/
+rust/.agentledger-rust/
+*.db
+*.sqlite
+*.sqlite3
+
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env
+.DS_Store
+**/.DS_Store
+node_modules/
+**/node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Local notes, research dumps, and generated reports that should not ship.
+.claude/
+AI_Agent_Runtime_开源项目构想.md
+*.pdf
+*.docx
+*.pptx
+*.pages
+*.key
+evidence/
+evidence*.html
+time-travel*.html
+
+# Local external installer/download artifacts.
+rce
+
+# Rust build outputs.
+target/
+**/target/
+rust/crates/*/Cargo.lock
+# Local transient files
+*.tmp
+*.log
+*.bak
+*.swp
+*.swo
+*.orig
+
+# Python/pytest leftovers not always covered by tool output
+.coverage.*
+htmlcov/
+.ipynb_checkpoints/

agentledger_inspector-1.3.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: agentledger-inspector
+Version: 1.3.0
+Summary: Read-only Inspector and evidence viewer package for AgentLedger
+Project-URL: Homepage, https://github.com/yaogdu/AgentLedger
+Project-URL: Repository, https://github.com/yaogdu/AgentLedger
+Project-URL: Documentation, https://github.com/yaogdu/AgentLedger/tree/main/docs
+Project-URL: Issues, https://github.com/yaogdu/AgentLedger/issues
+Author: AgentLedger Contributors
+License: Apache-2.0
+Keywords: agents,debug,evidence,inspector,runtime
+Requires-Python: >=3.11
+Requires-Dist: agentledger-runtime<2,>=1.3
+Description-Content-Type: text/markdown
+
+# agentledger-inspector
+
+Read-only Inspector and evidence viewer package for AgentLedger.
+
+This package is language-neutral. It is implemented once as a companion evidence consumer and can inspect evidence/runtime metadata produced by Python, Go, TypeScript, or Rust implementations when they follow the AgentLedger contract.
+
+```bash
+pip install agentledger-inspector
+pip install "agentledger-runtime[inspector]"
+```
+
+Inspect a local runtime database:
+
+```bash
+agentledger inspector run <run_id> --root .agentledger --html ./inspector.html
+```
+
+Inspect an exported evidence bundle:
+
+```bash
+agentledger inspector evidence ./evidence/<run_id> --html ./inspector.html
+```
+
+For Postgres or MySQL, use a read-only database credential and pass the local blob root that contains the referenced payload blobs. Inspector uses read-only store wrappers and does not run migrations or create tables:
+
+```bash
+agentledger inspector run <run_id> --backend postgres --dsn "$AGENTLEDGER_POSTGRES_DSN" --blob-root .agentledger/blobs --html ./inspector.html
+agentledger inspector run <run_id> --backend mysql --dsn "$AGENTLEDGER_MYSQL_DSN" --blob-root .agentledger/blobs --html ./inspector.html
+```
+
+The Inspector does not start a server, mutate runtime state, call tools, approve requests, or contact model providers. It builds a language-neutral read model from AgentLedger runtime metadata or exported evidence bundles. AgentLedger does not add a separate permission layer for Inspector; use database grants, filesystem ACLs, and deployment policy.
+
+Extension API:
+
+```python
+from agentledger_inspector import EvidenceBlobStoreProtocol, EvidenceStateStoreProtocol, InspectorDataSource, InspectorReportBuilder
+
+report = InspectorDataSource().from_evidence_path("./evidence/run-1")
+data = report.to_dict()
+html = report.to_html()
+
+builder = InspectorReportBuilder()
+custom_report = builder.from_evidence_path("./evidence/run-1")
+
+custom_source_report = InspectorDataSource().from_runtime_store(
+    store=my_read_only_state_store,
+    blobs=my_read_only_blob_store,
+    run_id="run_123",
+)
+```
+
+The default HTML renderer is a reference renderer. Users can build their own UI by consuming `InspectorReport.to_dict()` and preserving `schema_version == agentledger.inspector.v1`.
+
+`EvidenceStateStoreProtocol` and `EvidenceBlobStoreProtocol` describe the minimal read API for custom database/blob backends.
+
+Custom viewers should depend on the read model and protocols instead of undocumented SQL tables. Keep write/control actions outside Inspector surfaces; use runtime APIs for approve, deny, cancel, or recover operations.
+
+Runnable custom-viewer example:
+
+```bash
+git clone https://github.com/yaogdu/AgentLedger.git
+cd AgentLedger
+PYTHONPATH=src python3 examples/inspector/custom_viewer.py
+```
+
+That example creates a temporary runtime, reads SQLite metadata, exports an evidence bundle, writes JSON/HTML reports, and builds a compact custom UI/API payload from `InspectorReport.to_dict()`.
+
+Security note: Inspector output may include tool arguments, model metadata, artifact references, approval reasons, and failure details. Treat exported JSON/HTML as sensitive operational evidence.

agentledger_inspector-1.3.0/README.md

@@ -0,0 +1,68 @@
+# agentledger-inspector
+
+Read-only Inspector and evidence viewer package for AgentLedger.
+
+This package is language-neutral. It is implemented once as a companion evidence consumer and can inspect evidence/runtime metadata produced by Python, Go, TypeScript, or Rust implementations when they follow the AgentLedger contract.
+
+```bash
+pip install agentledger-inspector
+pip install "agentledger-runtime[inspector]"
+```
+
+Inspect a local runtime database:
+
+```bash
+agentledger inspector run <run_id> --root .agentledger --html ./inspector.html
+```
+
+Inspect an exported evidence bundle:
+
+```bash
+agentledger inspector evidence ./evidence/<run_id> --html ./inspector.html
+```
+
+For Postgres or MySQL, use a read-only database credential and pass the local blob root that contains the referenced payload blobs. Inspector uses read-only store wrappers and does not run migrations or create tables:
+
+```bash
+agentledger inspector run <run_id> --backend postgres --dsn "$AGENTLEDGER_POSTGRES_DSN" --blob-root .agentledger/blobs --html ./inspector.html
+agentledger inspector run <run_id> --backend mysql --dsn "$AGENTLEDGER_MYSQL_DSN" --blob-root .agentledger/blobs --html ./inspector.html
+```
+
+The Inspector does not start a server, mutate runtime state, call tools, approve requests, or contact model providers. It builds a language-neutral read model from AgentLedger runtime metadata or exported evidence bundles. AgentLedger does not add a separate permission layer for Inspector; use database grants, filesystem ACLs, and deployment policy.
+
+Extension API:
+
+```python
+from agentledger_inspector import EvidenceBlobStoreProtocol, EvidenceStateStoreProtocol, InspectorDataSource, InspectorReportBuilder
+
+report = InspectorDataSource().from_evidence_path("./evidence/run-1")
+data = report.to_dict()
+html = report.to_html()
+
+builder = InspectorReportBuilder()
+custom_report = builder.from_evidence_path("./evidence/run-1")
+
+custom_source_report = InspectorDataSource().from_runtime_store(
+    store=my_read_only_state_store,
+    blobs=my_read_only_blob_store,
+    run_id="run_123",
+)
+```
+
+The default HTML renderer is a reference renderer. Users can build their own UI by consuming `InspectorReport.to_dict()` and preserving `schema_version == agentledger.inspector.v1`.
+
+`EvidenceStateStoreProtocol` and `EvidenceBlobStoreProtocol` describe the minimal read API for custom database/blob backends.
+
+Custom viewers should depend on the read model and protocols instead of undocumented SQL tables. Keep write/control actions outside Inspector surfaces; use runtime APIs for approve, deny, cancel, or recover operations.
+
+Runnable custom-viewer example:
+
+```bash
+git clone https://github.com/yaogdu/AgentLedger.git
+cd AgentLedger
+PYTHONPATH=src python3 examples/inspector/custom_viewer.py
+```
+
+That example creates a temporary runtime, reads SQLite metadata, exports an evidence bundle, writes JSON/HTML reports, and builds a compact custom UI/API payload from `InspectorReport.to_dict()`.
+
+Security note: Inspector output may include tool arguments, model metadata, artifact references, approval reasons, and failure details. Treat exported JSON/HTML as sensitive operational evidence.

agentledger_inspector-1.3.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentledger-inspector"
+version = "1.3.0"
+description = "Read-only Inspector and evidence viewer package for AgentLedger"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+authors = [{name = "AgentLedger Contributors"}]
+keywords = ["agents", "runtime", "inspector", "debug", "evidence"]
+dependencies = ["agentledger-runtime>=1.3,<2"]
+
+[project.urls]
+Homepage = "https://github.com/yaogdu/AgentLedger"
+Repository = "https://github.com/yaogdu/AgentLedger"
+Documentation = "https://github.com/yaogdu/AgentLedger/tree/main/docs"
+Issues = "https://github.com/yaogdu/AgentLedger/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentledger_inspector"]

agentledger_inspector-1.3.0/src/agentledger_inspector/__init__.py

@@ -0,0 +1,20 @@
+"""Read-only Inspector package for AgentLedger."""
+
+__version__ = "1.3.0"
+
+from agentledger.inspector import INSPECTOR_SCHEMA_VERSION, InspectorDataSource, InspectorReport, InspectorReportBuilder, ReadOnlyLocalBlobStore, ReadOnlyMySQLStore, ReadOnlyPostgresStore, ReadOnlySQLiteStore
+from agentledger.protocol import EvidenceBlobStoreProtocol, EvidenceStateStoreProtocol
+
+__all__ = [
+    "INSPECTOR_SCHEMA_VERSION",
+    "EvidenceBlobStoreProtocol",
+    "EvidenceStateStoreProtocol",
+    "InspectorDataSource",
+    "InspectorReport",
+    "InspectorReportBuilder",
+    "ReadOnlyLocalBlobStore",
+    "ReadOnlyMySQLStore",
+    "ReadOnlyPostgresStore",
+    "ReadOnlySQLiteStore",
+    "__version__",
+]

agentledger_inspector-1.3.0/tests/test_import.py

@@ -0,0 +1,8 @@
+def test_imports() -> None:
+    from agentledger_inspector import INSPECTOR_SCHEMA_VERSION, EvidenceStateStoreProtocol, InspectorDataSource, InspectorReportBuilder, ReadOnlyPostgresStore
+
+    assert INSPECTOR_SCHEMA_VERSION == "agentledger.inspector.v1"
+    assert EvidenceStateStoreProtocol.__name__ == "EvidenceStateStoreProtocol"
+    assert InspectorDataSource.__name__ == "InspectorDataSource"
+    assert InspectorReportBuilder.__name__ == "InspectorReportBuilder"
+    assert ReadOnlyPostgresStore.__name__ == "ReadOnlyPostgresStore"