Lens

A pure-Python RLM interpretation layer that reads Knitweb/Pulse exports, resolved OriginTrail snapshots, ActivityStreams objects, and human-agent logs, then returns provenance-cited answers without live service dependencies.

View Repository Open Issues Research Notes

Run It Offline

These commands work from a fresh checkout with no API keys, vector database, DKG node, or Knitweb runtime.

python -m pip install -e ".[dev]"
lens query "What does Lens preserve?" README.md --json
lens query "How do graph rows work?" examples/neo4j_rows.json --json
lens query "How are vector scores handled?" examples/vector_results.json --json
lens query "What should Lens preserve from social exports?" examples/activitystreams_collection.json --json
lens query "What did OriginTrail resolve?" examples/origintrail_resolved_asset.json --json
lens query "Does Lens become a MeTTa runtime?" examples/metta_atom_rows.json --json
lens inspect-pulse tests/fixtures/pulse_web_export.json
python -m pytest

Compatibility Inputs

Lens normalizes read models into cited chunks. It delegates storage, signing, transport, anchoring, discovery, and federation to the systems that own those responsibilities.

Pulse/Knitweb

Reads JSON-LD Web exports and Web-like objects while preserving CIDs, UALs, records, edges, and relation paths.

OriginTrail

Reads already-resolved Knowledge Asset snapshots and preserves UALs as citations without DKG querying or publishing.

ActivityStreams

Reads exported social objects and collections while preserving actors, objects, replies, targets, tags, audiences, and publication timestamps.

Interaction Logs

Reads human and agent logs with actors, timestamps, reply links, target CIDs, and tool-call references.

Graph Rows

Accepts Neo4j, LightRAG, Hyperon/MeTTa atom exports, vector-result, JSON, Markdown, and text rows through small dependency-free adapters and runnable examples.

Context Bundles

Exports ranked chunks as portable JSON, renders Markdown, and replays answers through the offline harness.

Current Surface

The repository is intentionally small, testable, and friendly to adapter and reliability contributions.

63

Offline tests covering adapters, CLI, reliability, evals, context bundles, and Pulse export inspection.

0

Required network services or live model credentials for the base package.

/interpret

Small stdlib HTTP route for read-only interpretation requests and context replay.

Boundaries

Compatibility does not mean feature duplication.

Lens Owns

  • Adapter normalization into chunks.
  • Deterministic integer retrieval and reliability scores.
  • Ephemeral sessions, context bundles, and cited answers.
  • Consumer-side Pulse export shape inspection.

Delegated

  • Knitweb/Pulse owns fabric storage, canonical CID generation, signing, mutation, transport, and ledger behavior.
  • OriginTrail owns UAL resolution, DKG querying, publishing, anchoring, and network discovery.
  • ActivityPub systems own inbox/outbox delivery, federation, moderation, and social graph storage.
  • Hyperon/MeTTa owns Atomspace storage, evaluation, grounded atoms, and runtime mutation.

Contribute

Good contributions add fixtures, adapters, citation quality, eval cases, or docs while keeping the base package pure Python and offline-testable.

Adapter Fixtures

Bring small real exports from Pulse, OriginTrail, ActivityStreams, Hyperon/MeTTa, LightRAG, Neo4j, vector stores, or local agent logs.

Reliability

Improve abstention, source trust, and citation-faithfulness evals with deterministic integer reports.

Live Adapters

Wrap external model calls around the prompt renderer while keeping the base package offline and dependency-free.

Review Norm

Small safe PRs are welcome; control surfaces need maintainer review. Every PR should get technical feedback.