forge-lens-fl 0.2.0__tar.gz

forge_lens_fl-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgar Sócrates Caria
+
+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.

forge_lens_fl-0.2.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: forge-lens-fl
+Version: 0.2.0
+Summary: Local-first, open-source agentic observability: traces, tools, tokens, cost and evidence.
+Keywords: observability,opentelemetry,openinference,agents,llm,tracing
+Author: Edgar Sócrates Caria
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: fastapi>=0.115 ; extra == 'server'
+Requires-Dist: uvicorn>=0.30 ; extra == 'server'
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/EdgarSocrates98/forge-lens
+Project-URL: Issues, https://github.com/EdgarSocrates98/forge-lens/issues
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# Forge Lens
+
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Forge Lens logo" width="420" />
+</p>
+
+**Local-first, open-source agentic observability.** Understand every agent execution. Trace every tool. Measure every cost. Investigate every failure. Prove every improvement.
+
+Forge Lens receives, persists and explains agent executions — via OTLP/HTTP, OpenInference attributes, or its own SDKs — on your machine, with no mandatory external dependency.
+
+## Status
+
+Cycles 00–01 (foundation, verified): contracts v1, OTLP/HTTP JSON ingestion, sanitization, SQLite WAL store, Python + TypeScript SDKs, CLI.
+Cycles 03–06 backend: temporal execution graph (`/v1/graph/*`), token/cost intelligence (`/v1/traces/{id}/cost`), failure classification + recorded replay + incident bundles (`/v1/traces/{id}/failure|replay|incident`), deterministic evaluation (`/v1/eval/*`), versioned datasets + regression gates — reports in `docs/cycles/`.
+Cycle 02: Angular Studio (`apps/studio`) — Trace Explorer with sortable/filterable list, waterfall with span detail, an evidence pane (cost/failure/loops/graph-analysis payloads rendered as JSON, plus eval results and recorded replay in tables), ops summary view, host-capability table, dark/light themes, URL-state sync, lazy routes, typed API client.
+Cycle 07: loop/no-progress detection (`/v1/traces/{id}/loops`), bounded specialist runtime (`/v1/analyze/*`), threshold alerts (`/v1/alerts/evaluate`), ops summary (`/v1/ops/summary`), MCP security observer (`/v1/traces/{id}/security`).
+Cycle 08: auth modes (`none|key|keys`) with API keys + roles + per-project tenancy, audit trail (`/v1/admin/audit`), retention (`forge-lens prune|archive`, `/v1/admin/prune`), TLS passthrough on `serve`.
+Cycle 09: SSE replay (`/v1/traces/{id}/stream`), measured benchmarks at 1k/10k/100k spans (`scripts/benchmark.py` → `docs/benchmarks/`), archive-before-delete lifecycle.
+Cycle 10: honest host-capability matrix (`/v1/capabilities`), Claude Code JSONL importer (`import-claude`), MCP stdio observer (`mcp-serve`), install lifecycle receipts (`install-status`), 7 skills in `skills/`.
+Cycle 11: CycloneDX SBOM generator (`scripts/gen_sbom.py`), release workflow with OIDC trusted publishing + version gate, `CHANGELOG.md`, `docs/versioning.md`, Studio CI job.
+Cycle 12: efficiency intelligence (`/v1/intel/efficiency`, `/v1/traces/{id}/efficiency`), cohort regression (`/v1/intel/regress`), candidate recommendations (`/v1/traces/{id}/recommendations`), graph centrality/concentration analysis (`/v1/graph/traces/{id}/analysis`).
+
+## Quickstart
+
+Portable install (same model as the other Forge projects — venv under
+`~/.forge/installs/forge-lens`, launcher on PATH, no project-venv
+touch):
+
+```bash
+./install.sh              # POSIX; . .\install.ps1 on PowerShell
+forge-lens init .
+forge-lens serve          # API on http://127.0.0.1:7777
+forge-lens doctor
+```
+
+Dev checkout alternative: `uv sync --extra server && uv run forge-lens ...`.
+
+Instrument an agent:
+
+```python
+from forge_lens.sdk import LensTracer
+from forge_lens.sdk.exporter import HTTPExporter
+
+tracer = LensTracer(
+    service_name="my-agent",
+    exporter=HTTPExporter("http://127.0.0.1:7777"),
+)
+
+with tracer.agent("researcher"):
+    with tracer.llm_call("claude-sonnet-4", provider="anthropic") as s:
+        tracer.record_usage(s, input_tokens=200, output_tokens=80, total_tokens=280)
+    with tracer.tool_call("web_search"):
+        ...  # call the tool
+```
+
+Inspect:
+
+```bash
+forge-lens traces list
+forge-lens traces show <trace-id>
+```
+
+A runnable offline demo (SDK → pipeline → store → read-back, no server):
+`uv run python examples/quickstart.py`
+
+## Principles
+
+- **Local-first** — SQLite WAL by default; works fully offline.
+- **Evidence-first** — every claim carries provenance (`observed` / `imported` / `derived` / `inferred` / `unknown`). Inferred never silently becomes observed.
+- **Safe by default** — `capture=metadata` redacts secrets and drops prompt bodies unless you opt into `full`.
+- **OTel/OpenInference compatible** — OTLP/HTTP JSON ingest, `openinference.*` attribute mapping, W3C traceparent propagation.
+
+## Documentation
+
+See `docs/` — architecture, guides, API/CLI/contracts reference, ADRs and cycle reports (PT-BR first, EN planned).
+
+- `docs/guides/quickstart.md` — first trace in minutes
+- `docs/guides/operations-runbook.md` — serve, auth modes, retention, backups, monitoring, alert rules
+- `docs/guides/troubleshooting.md` — symptom → cause → fix
+- `docs/guides/failure-investigation.md` — failure taxonomy (§05.3), root-cause hypotheses (§05.4), eval suggestions (§12.7)

forge_lens_fl-0.2.0/README.md

@@ -0,0 +1,80 @@
+# Forge Lens
+
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Forge Lens logo" width="420" />
+</p>
+
+**Local-first, open-source agentic observability.** Understand every agent execution. Trace every tool. Measure every cost. Investigate every failure. Prove every improvement.
+
+Forge Lens receives, persists and explains agent executions — via OTLP/HTTP, OpenInference attributes, or its own SDKs — on your machine, with no mandatory external dependency.
+
+## Status
+
+Cycles 00–01 (foundation, verified): contracts v1, OTLP/HTTP JSON ingestion, sanitization, SQLite WAL store, Python + TypeScript SDKs, CLI.
+Cycles 03–06 backend: temporal execution graph (`/v1/graph/*`), token/cost intelligence (`/v1/traces/{id}/cost`), failure classification + recorded replay + incident bundles (`/v1/traces/{id}/failure|replay|incident`), deterministic evaluation (`/v1/eval/*`), versioned datasets + regression gates — reports in `docs/cycles/`.
+Cycle 02: Angular Studio (`apps/studio`) — Trace Explorer with sortable/filterable list, waterfall with span detail, an evidence pane (cost/failure/loops/graph-analysis payloads rendered as JSON, plus eval results and recorded replay in tables), ops summary view, host-capability table, dark/light themes, URL-state sync, lazy routes, typed API client.
+Cycle 07: loop/no-progress detection (`/v1/traces/{id}/loops`), bounded specialist runtime (`/v1/analyze/*`), threshold alerts (`/v1/alerts/evaluate`), ops summary (`/v1/ops/summary`), MCP security observer (`/v1/traces/{id}/security`).
+Cycle 08: auth modes (`none|key|keys`) with API keys + roles + per-project tenancy, audit trail (`/v1/admin/audit`), retention (`forge-lens prune|archive`, `/v1/admin/prune`), TLS passthrough on `serve`.
+Cycle 09: SSE replay (`/v1/traces/{id}/stream`), measured benchmarks at 1k/10k/100k spans (`scripts/benchmark.py` → `docs/benchmarks/`), archive-before-delete lifecycle.
+Cycle 10: honest host-capability matrix (`/v1/capabilities`), Claude Code JSONL importer (`import-claude`), MCP stdio observer (`mcp-serve`), install lifecycle receipts (`install-status`), 7 skills in `skills/`.
+Cycle 11: CycloneDX SBOM generator (`scripts/gen_sbom.py`), release workflow with OIDC trusted publishing + version gate, `CHANGELOG.md`, `docs/versioning.md`, Studio CI job.
+Cycle 12: efficiency intelligence (`/v1/intel/efficiency`, `/v1/traces/{id}/efficiency`), cohort regression (`/v1/intel/regress`), candidate recommendations (`/v1/traces/{id}/recommendations`), graph centrality/concentration analysis (`/v1/graph/traces/{id}/analysis`).
+
+## Quickstart
+
+Portable install (same model as the other Forge projects — venv under
+`~/.forge/installs/forge-lens`, launcher on PATH, no project-venv
+touch):
+
+```bash
+./install.sh              # POSIX; . .\install.ps1 on PowerShell
+forge-lens init .
+forge-lens serve          # API on http://127.0.0.1:7777
+forge-lens doctor
+```
+
+Dev checkout alternative: `uv sync --extra server && uv run forge-lens ...`.
+
+Instrument an agent:
+
+```python
+from forge_lens.sdk import LensTracer
+from forge_lens.sdk.exporter import HTTPExporter
+
+tracer = LensTracer(
+    service_name="my-agent",
+    exporter=HTTPExporter("http://127.0.0.1:7777"),
+)
+
+with tracer.agent("researcher"):
+    with tracer.llm_call("claude-sonnet-4", provider="anthropic") as s:
+        tracer.record_usage(s, input_tokens=200, output_tokens=80, total_tokens=280)
+    with tracer.tool_call("web_search"):
+        ...  # call the tool
+```
+
+Inspect:
+
+```bash
+forge-lens traces list
+forge-lens traces show <trace-id>
+```
+
+A runnable offline demo (SDK → pipeline → store → read-back, no server):
+`uv run python examples/quickstart.py`
+
+## Principles
+
+- **Local-first** — SQLite WAL by default; works fully offline.
+- **Evidence-first** — every claim carries provenance (`observed` / `imported` / `derived` / `inferred` / `unknown`). Inferred never silently becomes observed.
+- **Safe by default** — `capture=metadata` redacts secrets and drops prompt bodies unless you opt into `full`.
+- **OTel/OpenInference compatible** — OTLP/HTTP JSON ingest, `openinference.*` attribute mapping, W3C traceparent propagation.
+
+## Documentation
+
+See `docs/` — architecture, guides, API/CLI/contracts reference, ADRs and cycle reports (PT-BR first, EN planned).
+
+- `docs/guides/quickstart.md` — first trace in minutes
+- `docs/guides/operations-runbook.md` — serve, auth modes, retention, backups, monitoring, alert rules
+- `docs/guides/troubleshooting.md` — symptom → cause → fix
+- `docs/guides/failure-investigation.md` — failure taxonomy (§05.3), root-cause hypotheses (§05.4), eval suggestions (§12.7)

forge_lens_fl-0.2.0/pyproject.toml

@@ -0,0 +1,156 @@
+[project]
+name = "forge-lens-fl"
+version = "0.2.0"
+description = "Local-first, open-source agentic observability: traces, tools, tokens, cost and evidence."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+keywords = [
+    "observability",
+    "opentelemetry",
+    "openinference",
+    "agents",
+    "llm",
+    "tracing",
+]
+dependencies = [
+    "pydantic>=2.7",
+    "typer>=0.12",
+    "rich>=13.7",
+]
+
+[[project.authors]]
+name = "Edgar Sócrates Caria"
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+]
+
+[project.urls]
+Repository = "https://github.com/EdgarSocrates98/forge-lens"
+Issues = "https://github.com/EdgarSocrates98/forge-lens/issues"
+
+[project.scripts]
+forge-lens = "forge_lens.cli.main:main"
+
+[dependency-groups]
+lint = ["ruff>=0.8"]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "httpx>=0.27",
+]
+types = ["mypy>=1.13"]
+audit = ["pip-audit>=2.7"]
+
+[[dependency-groups.dev]]
+include-group = "lint"
+
+[[dependency-groups.dev]]
+include-group = "test"
+
+[[dependency-groups.dev]]
+include-group = "types"
+
+[[dependency-groups.dev]]
+include-group = "audit"
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "forge_lens"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "C4",
+    "RUF",
+    "S",
+    "DTZ",
+    "PT",
+    "PTH",
+    "TID",
+]
+ignore = ["S608"]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/forge_bootstrap.py" = ["ALL"]
+"scripts/lab/forge_lens_lab.py" = ["S314"]
+"tests/**" = [
+    "S101",
+    "PT011",
+    "PTH",
+    "S105",
+    "S106",
+]
+"examples/**" = [
+    "S101",
+    "T201",
+]
+"homolog/**" = [
+    "S101",
+    "S105",
+    "S310",
+    "S603",
+    "PTH",
+]
+"src/forge_lens/cli/**" = ["T201"]
+"src/forge_lens/ui/**/*.py" = ["ALL"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+markers = [
+    "e2e: end-to-end scenarios",
+    "contract: contract and schema tests",
+    "benchmark: benchmark smoke tests (tests/bench)",
+    "network: legitimately opens sockets (exempt from the offline gate)",
+]
+
+[tool.coverage.run]
+source = ["src/forge_lens"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@overload",
+]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+packages = ["forge_lens"]
+strict = true
+warn_unreachable = true
+exclude = ["forge_lens.ui"]

forge_lens_fl-0.2.0/pyproject.toml.orig

@@ -0,0 +1,117 @@
+[project]
+name = "forge-lens-fl"
+version = "0.2.0"
+description = "Local-first, open-source agentic observability: traces, tools, tokens, cost and evidence."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Edgar Sócrates Caria" }]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+keywords = ["observability", "opentelemetry", "openinference", "agents", "llm", "tracing"]
+dependencies = [
+    "pydantic>=2.7",
+    "typer>=0.12",
+    "rich>=13.7",
+]
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+]
+
+[project.urls]
+Repository = "https://github.com/EdgarSocrates98/forge-lens"
+Issues = "https://github.com/EdgarSocrates98/forge-lens/issues"
+
+[project.scripts]
+# Route the installed command through the small dispatcher so a bare
+# `forge-lens install` gets the guided wizard on a real TTY.  Pointing the
+# entry point directly at the Typer object bypasses that contract in wheels.
+forge-lens = "forge_lens.cli.main:main"
+
+[dependency-groups]
+dev = [
+    { include-group = "lint" },
+    { include-group = "test" },
+    { include-group = "types" },
+    { include-group = "audit" },
+]
+lint = ["ruff>=0.8"]
+test = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "httpx>=0.27",
+]
+types = ["mypy>=1.13"]
+audit = ["pip-audit>=2.7"]
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.13"]
+build-backend = "uv_build"
+
+# The PyPI distribution is `forge-lens-fl` but the import package stays
+# `forge_lens` — without this, uv_build expects src/forge_lens_fl/.
+[tool.uv.build-backend]
+module-name = "forge_lens"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "C4", "RUF", "S", "DTZ", "PT", "PTH", "TID"]
+ignore = [
+    "S608", # SQL is built from fixed fragments + parameters only
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Vendored shared bootstrap — canonical copy in forge-doctor-api is the lint target.
+"scripts/forge_bootstrap.py" = ["ALL"]
+# Lab emitter parses its own just-written junit artifact — not untrusted input.
+"scripts/lab/forge_lens_lab.py" = ["S314"]
+"tests/**" = ["S101", "PT011", "PTH", "S105", "S106"]
+"examples/**" = ["S101", "T201"]
+# Homologation runner — subprocess/urllib against the local install is the point.
+"homolog/**" = ["S101", "S105", "S310", "S603", "PTH"]
+"src/forge_lens/cli/**" = ["T201"]
+# Vendored Forge UI kit (canonical: the-forge/src/theforge/ui) —
+# byte-identical to the shared source; linted in the canonical repo.
+"src/forge_lens/ui/**/*.py" = ["ALL"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+markers = [
+    "e2e: end-to-end scenarios",
+    "contract: contract and schema tests",
+    "benchmark: benchmark smoke tests (tests/bench)",
+    "network: legitimately opens sockets (exempt from the offline gate)",
+]
+
+[tool.coverage.run]
+source = ["src/forge_lens"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError", "@overload"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+packages = ["forge_lens"]
+strict = true
+warn_unreachable = true
+# Vendored Forge UI kit — mesma razão da exclusão de lint.
+exclude = ["forge_lens.ui"]

forge_lens_fl-0.2.0/src/forge_lens/__init__.py

@@ -0,0 +1,3 @@
+"""Forge Lens — local-first agentic observability and intelligence."""
+
+__version__ = "0.2.0"

forge_lens_fl-0.2.0/src/forge_lens/__main__.py

@@ -0,0 +1,3 @@
+from forge_lens.cli.main import main
+
+main()

forge_lens_fl-0.2.0/src/forge_lens/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Host/runtime adapters — Cycle 10. Optional, evidence-first."""
+
+from forge_lens.adapters.capabilities import HOST_CAPABILITIES, capability_matrix
+
+__all__ = ["HOST_CAPABILITIES", "capability_matrix"]

forge_lens_fl-0.2.0/src/forge_lens/adapters/capabilities.py

@@ -0,0 +1,70 @@
+"""Honest host capability matrix — Cycle 10.
+
+Every host entry states WHAT is actually instrumentable, through which
+mechanism. 'unsupported' is a valid answer — the matrix exists so
+nobody claims coverage that doesn't exist.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+HOST_CAPABILITIES: dict[str, dict[str, Any]] = {
+    "claude_code": {
+        "native_tracing": False,
+        "mechanism": "hooks + session JSONL logs",
+        "adapter": "adapters.claude_code (JSONL import → Trace)",
+        "coverage": "tool calls, model usage, session boundaries",
+        "limits": "no in-process span capture; log-derived only",
+    },
+    "codex": {
+        "native_tracing": False,
+        "mechanism": "session logs / rollout files",
+        "adapter": "not implemented — log format unstable",
+        "coverage": "none claimed",
+        "limits": "unsupported today",
+    },
+    "devin": {
+        "native_tracing": False,
+        "mechanism": "unsupported — no public instrumentation surface",
+        "adapter": None,
+        "coverage": "none",
+        "limits": "unsupported",
+    },
+    "copilot": {
+        "native_tracing": False,
+        "mechanism": "unsupported — closed surface",
+        "adapter": None,
+        "coverage": "none",
+        "limits": "unsupported",
+    },
+    "cursor": {
+        "native_tracing": False,
+        "mechanism": "MCP instrumentation point exists (client-side)",
+        "adapter": "forge_lens.mcp_server used as gateway observer",
+        "coverage": "MCP tool list/call/result only — NOT agent internals",
+        "limits": "MCP traffic only; no claim of full tracing",
+    },
+    "forge": {
+        "native_tracing": True,
+        "mechanism": "in-process SDK instrumentation",
+        "adapter": "forge_lens.sdk (native)",
+        "coverage": "full spans, tools, tokens",
+        "limits": "requires opt-in tracing init",
+    },
+    "generic_otlp": {
+        "native_tracing": True,
+        "mechanism": "OTLP/HTTP JSON endpoint",
+        "adapter": "built-in",
+        "coverage": "whatever the runtime emits",
+        "limits": "span quality depends on emitter",
+    },
+}
+
+
+def capability_matrix() -> dict[str, Any]:
+    return {
+        "hosts": {k: dict(v) for k, v in sorted(HOST_CAPABILITIES.items())},
+        "note": "coverage claims are per-mechanism; 'unsupported' means"
+                " no verified path exists today",
+    }