jevgraph 0.2.0a1__tar.gz

jevgraph-0.2.0a1/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: tests
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e '.[dev,server]'
+      - run: python -m pytest
+      - run: ruff check .
+      - run: python -m build
+      - run: jevgraph demo
+  browser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: python -m venv .venv
+      - run: .venv/bin/pip install -e '.[dev,server]'
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:browser

jevgraph-0.2.0a1/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+*.sqlite*
+.env
+runs/
+.jevgraph/
+node_modules/
+test-results/

jevgraph-0.2.0a1/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+This is an early independent prototype. Start by running the offline demo and tests:
+
+```bash
+uv sync --extra dev --extra server
+uv run jevgraph demo
+uv run pytest
+uv run ruff check .
+uv build
+npm ci
+npx playwright install chromium
+npm run test:browser
+```
+
+Keep relationship evidence separate from query relevance. Any change to relation prompts must bump the rubric version; a custom judge must change its `cache_key` when its behavior changes. Preserve original edge direction, negative/uncertain judgments, and source revisions. Add behavior tests for source invalidation, traversal or provider changes.
+
+Use synthetic records in tests and examples. Tests must run without credentials. Label scripted judgments clearly. Live experiments should publish their dataset provenance, model version, budgets, unsuccessful requests, and cache conditions alongside any results. Never infer model quality from a scripted demo.
+
+Priorities are a retriever protocol, measured candidate recall, a small public multi-hop evaluation, source-span adapters, and larger-store adapters. See DESIGN.md for the proposed research direction.
+
+Before a public release, resolve the existing JevGraph name collision, choose the actual repository/distribution names, update metadata, and verify the source and wheel contents. Do not use another project's package name or imply affiliation.

jevgraph-0.2.0a1/DESIGN.md

@@ -0,0 +1,87 @@
+# JEVGRAPH: search that builds reusable graph memory
+
+This document describes the underlying graph engine. The product has expanded into a general workplace search app with Chrome capture and dump ingestion; see [PRODUCT.md](PRODUCT.md) for the current product scope and roadmap.
+
+## Premise
+
+Give an agent a dataset and a question. Let it create the part of a relationship graph needed to investigate that question. Preserve the relationship judgments, including their evidence and uncertainty, so the next investigation can reuse them.
+
+The unit of memory is a **versioned relationship judgment**. It contains a directed claim, a relation definition, the source records evaluated, the judge version, and support/contradiction scores. A search is an ordered set of decisions over those judgments. Keeping those two objects separate prevents query relevance from gradually contaminating persistent memory.
+
+Product sentence: **“JEVGRAPH turns your searches into reusable evidence graphs.”**
+
+Developer promise: initialize a named graph, supply records and relation definitions, ask a bounded question, and inspect the path and evidence. No database service is required for the local alpha.
+
+## Why this might matter
+
+Consider an architecture investigation: “How could an identity outage affect checkout?” Text/vector retrieval can identify records mentioning identity or checkout. A relationship graph can connect records across service boundaries. Reusing previously judged edges may reduce repeated calls when later questions investigate payments, login, or the edge router.
+
+Building the graph only where queries explore could also reduce unnecessary indexing work. That benefit depends on query distribution and candidate quality. A corpus that is fully explored, frequently changing, or poorly retrieved may receive little benefit; cold searches add relationship-evaluation latency. Repeated retrieval can reinforce bad judgments unless evidence and revisions remain inspectable.
+
+The research question is whether this design improves supported answer recall per unit of evaluation work under realistic cold, warm, and source-update workloads.
+
+## Four responsibilities
+
+| Responsibility | Input | Output | Alpha implementation |
+| --- | --- | --- | --- |
+| Candidate retrieval | Query/current record, optional embedding | Bounded candidate records | Lexical + exact cosine, rank fusion |
+| Relationship evaluation | Directed pair, predicate, source text | Support and contradiction judgments | JEV Noul; independent predicates |
+| Graph memory | Versioned judgments | Reusable supported/uncertain/rejected edges | Named SQLite namespaces |
+| Search control | Query, evidence path, supported neighbors | Relevance decisions and stopping judgment | Bounded best-first traversal |
+
+The answering model can receive `SearchResult.to_dict()` and write a response with citations. Answer synthesis is intentionally an application responsibility in this version.
+
+## Relationship lifecycle
+
+1. The caller supplies a record with stable ID and exact source text.
+2. Retrieval proposes a pair. Type constraints determine applicable predicates.
+3. A matching cache entry reuses the original judgment. Otherwise, JEV evaluates the pair without seeing the user's query.
+4. Deterministic thresholds classify the result. Only supported edges enter traversal; all statuses remain inspectable.
+5. Query-specific routing determines which candidate path to explore next.
+6. Source edits or deletions remove affected cached judgments. Model/rubric/schema changes select a different cache identity. Policy changes reinterpret stored scores.
+
+Evidence currently means the supplied node records, not extracted sentence spans or independently verified truth. Cross-document entity resolution, aliases, temporal validity, and external verification are future work.
+
+## Search behavior
+
+Seed from explicit node IDs or local hybrid retrieval. On each expansion, judge whether the path is sufficient. If not, interleave known supported neighbors with nearby retrieved records. Evaluate missing candidate relationships in both directions, then independently score supported extensions for the query. Continue with the highest-priority queued path until the goal judgment passes or a budget/coverage limit is reached.
+
+Paths do not revisit the same node. Different paths to the same node remain eligible because their evidence can differ. Edge direction stays explicit even when traversing backward. The bottleneck priority makes no independence assumption about multiple model scores; it is only a heuristic.
+
+There is no completeness guarantee. Bounded candidates, greedy priorities, source omissions, ambiguous language, and judge errors can all cause misses. Call and question counts are recorded even on failed attempts. Reported token usage covers successful responses; failed requests may incur usage that is unavailable to this client.
+
+## What could make the next version distinctive
+
+These are proposed extensions, not current capabilities:
+
+1. **Search over missing knowledge.** Expose unresolved relationship questions to an agent. It can fetch a targeted source, add evidence, and resume the frontier. Tool execution remains with the host application.
+2. **Estimate the value of another hop.** Compare expected new evidence with latency/call cost. Measure whether this beats a fixed threshold before making it the default.
+3. **Keep contradictory paths visible.** Return competing evidence branches and dates rather than flattening disagreement into one answer.
+4. **Reuse work across related questions.** Distinguish relationship cache reuse from answer reuse; a previously useful path must still be evaluated for a new query.
+5. **Support larger corpora through adapters.** Add a retriever interface for existing vector indexes and a graph-store interface for existing graph databases, with identical evidence and invalidation contracts.
+6. **Give agents a small tool surface.** Proposed tools: `graph.search`, `graph.inspect_path`, `graph.add_evidence`, and `graph.unresolved`. Implement an MCP adapter after the Python contracts stabilize.
+
+## Evaluation before performance claims
+
+Use a held-out dataset of source records, dependency questions, answerable/unanswerable cases, and gold evidence paths. Include negation, reversed relations, distractors, conflicting versions, duplicate names, deleted records, cycles, and high-degree nodes. Ensure the question text never leaks into durable edge judgment prompts.
+
+Compare the same records and embedding model across:
+
+- text/vector retrieval alone;
+- vector retrieval with JEV reranking;
+- a fully precomputed relationship graph;
+- JEVGRAPH with cold memory;
+- JEVGRAPH with warm relationship memory;
+- JEVGRAPH after a controlled source update.
+
+Measure candidate recall separately from relationship precision/recall; then measure supported answer recall, incorrect-stop rate, abstention rate, citation correctness, p50/p95 latency, attempted calls/questions, reported tokens, and provider-reported cost where available. Run an ablation without JEV routing to determine whether navigation judgment adds value beyond graph traversal.
+
+Record source/model/schema versions, budgets, failures, and cache states. Fix thresholds on a development split and evaluate on held-out records. Fixture tests prove mechanics; they are not evidence that JEV finds the right relationships.
+
+## Scope of this first delivery
+
+Implemented: Python package, local graph namespaces, user-supplied records and embeddings, local hybrid retrieval, pair-level relation judgments, lazy graph growth, persistent cache/invalidation, evidence paths, bounded search, JSON export, offline demo, live JEV adapter, tests, and build metadata.
+
+The workspace layer now adds Chrome page capture, batch imports, authenticated local search, source previews, ingestion activity, and a browser-agent ingestion client. Still not implemented: automatic entity extraction, arbitrary graph-schema induction, an embedding provider, ANN indexing, native SaaS connectors, AST parsers, graph-store adapters, MCP serving, a graph visualization UI, answer synthesis, or production benchmarking.
+
+The original references “gantas” and “JEVbase” remain unidentified. No code from assumed repositories has been incorporated. Public references used to verify this design are linked in the README.

jevgraph-0.2.0a1/LICENSE

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

jevgraph-0.2.0a1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: jevgraph
+Version: 0.2.0a1
+Summary: Browser capture, workspace search, and reusable evidence graphs.
+Author: JEVGRAPH contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == 'dev'
+Requires-Dist: httpx<1,>=0.28; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.115; extra == 'server'
+Requires-Dist: uvicorn<1,>=0.34; extra == 'server'
+Description-Content-Type: text/markdown
+
+# JEVGRAPH
+
+**Capture in the browser. Search in one workspace. Follow the evidence.**
+
+JEVGRAPH is an MIT-licensed Python graph engine with an optional local workplace search app and a bundled Chrome extension. It connects browser capture and agent ingestion to a searchable source library, with optional JEV relationship evaluation and bounded graph traversal.
+
+Version **0.2.0a1 is an alpha release** for local evaluation. Python 3.11 or newer is required. This is an independent project; other projects also use the JevGraph name.
+
+## Install and run
+
+```bash
+python -m pip install 'jevgraph[server]==0.2.0a1'
+jevgraph serve
+```
+
+Open `http://127.0.0.1:8765`. The server creates an owner-readable `.jevgraph/access.json` file in your current directory. Copy its token into the workspace connection dialog. The server listens on loopback; it is not a production hosted service.
+
+Choose **Get Chrome capture**, download and unzip the extension, and load that folder using **Load unpacked** at `chrome://extensions`. Open the extension's toolbar icon and connect it to the same workspace URL and token. Capture the current page or select up to 20 open tabs. Captures are private by default.
+
+For just the dependency-free graph engine:
+
+```bash
+python -m pip install 'jevgraph==0.2.0a1'
+jevgraph demo
+```
+
+The demo uses scripted fixture judgments and makes no network requests. It demonstrates traversal and caching, not live model accuracy.
+
+## Ingest browser-agent records or JSON dumps
+
+Use the workspace import dialog, `jevgraph ingest records.json`, or the Python client:
+
+```python
+import os
+from jevgraph import IngestionClient
+
+client = IngestionClient(
+    "http://127.0.0.1:8765",
+    os.environ["JEVGRAPH_ACCESS_TOKEN"],
+)
+receipt = client.ingest([{
+    "external_id": "project-42/handoff",
+    "title": "Project handoff",
+    "url": "https://example.com/projects/42",
+    "text": "The payment service depends on the identity service.",
+    "source_type": "agent",
+    "visibility": "private",
+}])
+print(receipt)
+```
+
+Stable external IDs update existing records instead of creating duplicates. Each batch accepts up to 50 records and 2 MB. The HTTP endpoint is `POST /api/ingest`, with a bearer token and a JSON object containing `records`.
+
+## What it provides
+
+- Local SQLite storage, scoped private/shared records, source previews, and import activity.
+- Chrome page capture, selected-tab collection, persistent upload queues, explicit retries, JSON export, and workspace search.
+- Keyword retrieval in the workspace; the engine also accepts caller-provided vectors.
+- Optional JEV evaluation of explicit relationships, cached judgments tied to source revisions, bounded traversal, and inspectable evidence traces.
+
+The central idea is to retain useful relationship judgments across searches instead of evaluating the same unchanged evidence repeatedly. Accuracy and cost improvements must be measured on your own workload; this release claims no benchmark advantage.
+
+## Optional JEV exploration
+
+Set `TYPESAFE_API_KEY` in the server environment and run `jevgraph serve --live`. Relationship exploration sends selected authorized evidence to TypeSafe. JEV is a separate API service; its model and service usage are not included in this package. Ordinary local ingestion and keyword search do not require that key.
+
+## Current boundaries
+
+Browser capture reads text loaded in the main frame. It is not a full export of paginated applications, PDFs, or canvas editors. It excludes form controls and editable/hidden regions and does not read browser cookies or browsing history.
+
+Stored copies have local workspace permissions. They do not automatically inherit upstream permission changes or deletions. Managed hosting, native connectors, automatic source synchronization, workspace embedding jobs, generated answers, SSO, and billing are not included yet. Live JEV quality has not been validated for this release.
+
+The source distribution includes `README.md`, `PRODUCT.md`, `DESIGN.md`, examples, and tests for further development. Licensed under MIT.

jevgraph-0.2.0a1/PRODUCT.md

@@ -0,0 +1,120 @@
+# JEVGRAPH Workspace
+
+**Your work, connected.**
+
+Build a horizontal workplace search product: one place to find knowledge across the tools a person uses, inspect its sources, and explore useful connections. Chrome capture is an ingestion surface and an everyday search surface. Industry-specific workflows come after the general workspace experience.
+
+Glean is the product reference for cross-application search and browser access. Its [enterprise search](https://www.glean.com/enterprise-search) and [browser extension](https://docs.glean.com/user-guide/apps/installing-the-browser-extension) show the category. This is an independent implementation; Glean feature parity is not claimed.
+
+## The three layers
+
+| Layer | Product | Commercial direction | Delivered locally |
+| --- | --- | --- | --- |
+| Open-source engine | Records, graph judgments, evidence, retrieval, ingestion contracts | MIT engine for developers and self-hosting | Python engine, SQLite, optional workspace API, browser/agent ingestion |
+| Hosted workspace | Search, capture, source library, managed indexing and administration | Workspace subscription plus metered ingestion/model usage | Local workspace UI/API; hosting, subscription billing and production administration remain planned |
+| Industry products | Curated connectors, templates, permissions and workflow experiences | Packaged workspace editions and integrations | Reusable record contracts; no industry package is shipped yet |
+
+The initial target is a small team whose useful knowledge is scattered across browser-accessible tools. The first useful moment is saving two relevant pages and finding them together in a single search. The second is following a source-supported relationship between them.
+
+## First complete workflow
+
+1. Start a workspace and connect the browser companion using a workspace-scoped token.
+2. Capture the current page or explicitly select up to 20 open tabs. Chrome requests access to the selected sites when necessary.
+3. The extension reads loaded DOM text, attaches a title and source locator, and queues each record.
+4. The server validates and atomically upserts the batch, recording added/updated/unchanged counts. Stable external IDs prevent duplicate records on retry.
+5. Search in the workspace app or directly in the extension. Inspect the captured source text and open the original page.
+6. Optionally request JEV connection exploration. Only the caller's currently accessible records enter the graph or model request.
+7. Export captured JSON or send records from a browser agent through the same ingestion API.
+
+This version does not crawl links, click through arbitrary business applications, read browser cookies/history, or run continuously over all browsing. A page capture includes text currently loaded in the main frame; it is not a complete export of a paginated application, embedded PDF, canvas-based editor, or unopened record.
+
+## Permission model
+
+An access token resolves to a server-controlled `subject` and `workspace`. The ingestion payload cannot select an owner or workspace. Captures default to private; the extension always writes private records. JSON/API callers can explicitly mark a record `workspace` to share its copy within their workspace. Search, source previews, counts, and activity are scoped to the authenticated identity; only owners can delete their records.
+
+Browser visibility is not proof of team-wide access. The local permissions model controls access to the stored copy, not the upstream application's permissions. Browser snapshots do not automatically disappear when upstream access is revoked. Production connected sources need source ACL ingestion, membership sync, revocation propagation, retention policy, and deletion processing before promising permissions parity with the original systems.
+
+## What is implemented
+
+- Responsive workspace UI: search, source filtering, library, previews, deletion, source inventory, and import activity.
+- Chrome MV3 side panel: current-page capture, selected-tab collection, persistent queue, explicit failure retry, JSON export, and workspace search.
+- Browser capture excludes form controls, editable regions, hidden DOM text, navigation and footer elements. URL cleanup drops most query parameters; explicit external IDs support records identified by route fragments.
+- Batch ingestion API and Python client/CLI for browser agents and data dumps; up to 50 records / 2 MB per batch.
+- Idempotent source updates, private/shared record access, per-user graph synchronization, removal of stale chunks before search.
+- Keyword retrieval in the workspace, with optional JEV graph exploration. The underlying engine supports caller-provided vectors; the workspace does not yet provision embeddings.
+- Attempt/usage traces for graph evaluation, ingestion receipts and local activity. These are not a subscription billing system.
+
+## Next releases, in order
+
+1. **Reliable connected ingestion.** Add native Drive/Slack/Notion-style connectors with durable checkpoints, source IDs, revisions, deletions, and verified ACLs. Prefer native export APIs for large collections; use browser collection where a suitable API is unavailable.
+2. **Hybrid enterprise search.** Add embedding jobs, a vector index, incremental indexing, title/body/source ranking, and evaluations on permission-scoped queries. Preserve deterministic source relationships without paying a model to rediscover them.
+3. **Answers with citations.** Add a separate answer-generation model over retrieved evidence, inspectable citations, unresolved questions and contradiction handling. JEV continues to evaluate relationships and retrieval choices.
+4. **Hosted operations.** Organization accounts, SSO, team/group membership, scoped credentials, background jobs, retries, quotas, ingestion dashboards, retention, backups, monitoring and usage metering. Add paid plans after pilot workloads establish unit costs.
+5. **Browser agent collections.** User-defined collections with a bounded URL/record worklist, approved origins, page limits, source-specific pagination, resume checkpoints and a receipt per record. Agents submit normalized records through the existing API; website credentials need not be sent to JEVGRAPH.
+6. **Industry editions.** Package source mappings, vocabularies and workflow interfaces for legal operations, support and engineering on the same workspace foundation.
+
+## Product validation
+
+For the first pilot, measure capture success, time from capture to search, duplicate/update behavior, permission leakage, source freshness, search success on known questions, and weekly repeat use. For JEV exploration, measure supported-path recall, incorrect stopping, latency, attempted calls, and provider usage separately from basic search.
+
+The initial advantage to test is quick browser-to-workspace ingestion plus reusable relationship judgments. The long-term product depends on connector quality, access correctness, retrieval quality, and a useful everyday interface.
+
+## Running the local product
+
+```bash
+uv sync --extra server --extra dev
+uv run jevgraph serve
+```
+
+Open `http://127.0.0.1:8765`. The command writes a token mapping to `.jevgraph/access.json` with owner-only file permissions. Copy your token into the workspace connection dialog. The server binds to loopback and is intended for local evaluation, not public deployment.
+
+For Chrome, download the extension from **Get Chrome capture**, unzip it, and use **Load unpacked** on `chrome://extensions`. You can also load `src/jevgraph/extension` directly. In the side panel, set the workspace URL and token. Click the toolbar icon on the page before using **Capture this page**; selected-tab capture requests the required site access separately.
+
+To enable optional model-backed exploration:
+
+```bash
+export TYPESAFE_API_KEY="your-server-side-key"
+uv run jevgraph serve --live
+```
+
+Ordinary ingestion/search stays local. Requesting an exploration sends selected authorized evidence to TypeSafe. The live key stays on the server, never in the extension.
+
+## Browser agents and JSON dumps
+
+```json
+{
+  "records": [
+    {
+      "external_id": "docs/project-42/record-7",
+      "title": "Project handoff",
+      "url": "https://example.com/project/42",
+      "text": "The source text collected by the browser agent…",
+      "source_type": "agent",
+      "visibility": "private"
+    }
+  ]
+}
+```
+
+`external_id` should remain stable across updates. If omitted, the cleaned URL is used. Supply it explicitly for single-page apps whose records share a URL. Each record may contain up to 100,000 characters; the server chunks its text for retrieval.
+
+Use the import dialog, `POST /api/ingest` with `Authorization: Bearer ...`, or:
+
+```bash
+# Uses the single local token in .jevgraph/access.json, or JEVGRAPH_ACCESS_TOKEN.
+uv run jevgraph ingest captured-records.json --server http://127.0.0.1:8765
+```
+
+```python
+import os
+from jevgraph import IngestionClient
+
+client = IngestionClient("http://127.0.0.1:8765", os.environ["JEVGRAPH_ACCESS_TOKEN"])
+receipt = client.ingest(records)  # dictionaries in the format above
+```
+
+The extension retains its latest 20 capture jobs locally for retry/export. **Clear finished** removes completed/failed queue records. Failed HTTP requests are explicitly retried by the user; repeated batches update the same records. Site permissions remain in Chrome until revoked through extension settings.
+
+## Delivery boundaries
+
+The current product runs locally. It has not been deployed as a hosted service or submitted to the Chrome Web Store. This independent project shares the JevGraph name with other projects. Real MV3 capture-to-ingestion-to-search is tested with synthetic local pages; live JEV quality and production connector behavior need separate evaluation. A Python package release distributes the engine, local app, and extension files; it does not deploy a cloud workspace.

jevgraph-0.2.0a1/README.md

@@ -0,0 +1,167 @@
+# JEVGRAPH
+
+**Your work, connected. Capture in the browser. Search in one workspace.**
+
+JEVGRAPH includes a workspace search app, a Chrome capture extension, and a Python graph engine. Collect browser pages or import data dumps, search your private workspace, and optionally use JEV to explore relationships between source records.
+
+Start the product with `uv sync --extra server --extra dev`, then `uv run jevgraph serve`. Open the local URL printed by the server and connect using the token in `.jevgraph/access.json`. Download Chrome capture from the workspace, or load `src/jevgraph/extension` as an unpacked extension. [PRODUCT.md](PRODUCT.md) covers setup, browser-agent ingestion, access controls, and the open-source/hosted/industry product plan.
+
+The core premise: **every search can leave behind a small, reusable graph of evidence.** Vectors and text retrieval find candidate records. JEV judges explicit relationships. A bounded search follows useful connections and returns the path, source records, uncertainty, and decision trace to an answering agent.
+
+Status: local alpha, version `0.2.0a1`. The code is MIT licensed. Other projects already use the JevGraph name, including [chenmingtang830/jevgraph](https://github.com/chenmingtang830/jevgraph); this project is independent. `README_PYPI.md` contains the distribution's installation instructions and current boundaries. The source-checkout instructions below also work without a registry release.
+
+```mermaid
+flowchart LR
+    Q[Question] --> R[Text and vector candidates]
+    R --> J[JEV relationship judgments]
+    J --> G[Reusable graph memory]
+    G --> N[JEV guides traversal]
+    N --> R
+    N --> P[Evidence paths and search trace]
+    P --> A[Your answering agent]
+```
+
+## The product idea
+
+An agent investigating a failing identity service should be able to start at a checkout endpoint, find the payment service it calls, follow that service's identity dependency, and hand back the complete evidence trail. A second question should reuse the relationship work already done. If the architecture changes, affected judgments must be invalidated.
+
+Two distinct kinds of information make this possible:
+
+- **Relationship memory:** source A supports the directed claim that service X depends on service Y. This judgment is reusable across questions, within the same source revisions, schema, and judge version.
+- **Search decisions:** this particular relationship looks useful for the current question. These scores stay in the query trace and never become durable relationship facts.
+
+The intended benefit is less repeated relationship evaluation and better inspection of multi-hop retrieval. These are hypotheses to measure; this alpha makes no comparative accuracy, cost, speed, or novelty claims. See [DESIGN.md](DESIGN.md) for the premise, boundaries, and evaluation plan.
+
+## Run it in a minute
+
+Requires Python 3.11 or later. From this directory:
+
+```bash
+python3.11 -m pip install -e .
+jevgraph demo
+python3.11 examples/quickstart.py
+```
+
+Or with uv:
+
+```bash
+uv sync --extra dev --extra server
+uv run jevgraph demo
+uv run python examples/quickstart.py
+```
+
+The default demo uses **hard-coded fixture judgments**, no API key and no network. It exercises a three-hop path:
+
+```text
+edgerouter -> checkout -> payments -> identity
+```
+
+It also includes a rejected dependency on LegacyAuth. The cold/warm example demonstrates cache behavior, not model quality or an end-to-end performance benchmark.
+
+Persist the graph and inspect a full trace:
+
+```bash
+jevgraph demo --db demo.sqlite --out runs/first.json
+jevgraph demo --db demo.sqlite --out runs/second.json
+```
+
+Run those same synthetic records through real JEV:
+
+```bash
+export TYPESAFE_API_KEY="your-key"
+jevgraph demo --live --db live-demo.sqlite --out runs/live.json
+```
+
+`--live` sends the synthetic node text, query, and selected paths to TypeSafe. It uses at most 32 attempted evaluations and 100 typed questions for the demo. Live results can differ from the scripted path. The prototype has no automatic retries, and failures return a partial trace with `provider_error`.
+
+## Python API
+
+```python
+from jevgraph import Budget, Graph, JevJudge, Node, Relation
+
+with Graph(
+    "knowledge.sqlite",
+    name="architecture",
+    judge=JevJudge(),  # reads TYPESAFE_API_KEY; pinned model by default
+    relations=[Relation(
+        "depends_on",
+        "The source service requires the target service to perform its function.",
+        source_kind="service",
+        target_kind="service",
+    )],
+) as graph:
+    graph.add(Node(
+        "checkout", "Checkout sends card charges to Payments and depends on it.",
+        kind="service", source="architecture.md#checkout",
+    ))
+    graph.add(Node(
+        "payments", "Payments authenticates through Identity and depends on it.",
+        kind="service", source="architecture.md#payments",
+    ))
+    graph.add(Node(
+        "identity", "Identity issues tokens for signed-in sessions.",
+        kind="service", source="architecture.md#identity",
+    ))
+
+    result = graph.search(
+        "Find the service dependency path from Checkout to Identity.",
+        start=["checkout"],
+        budget=Budget(max_calls=12, max_questions=40, max_hops=3),
+    )
+    print(result.stop_reason)
+    print(result.to_dict())  # evidence, paths, judgments, usage, and stop reason
+```
+
+Each `Node` is a supplied record, passage, or entity with supporting text. You choose stable IDs and relation definitions. Node text is capped at 6000 characters; chunk larger sources before adding them. Entity extraction, source-code parsing, document conversion, and answer writing belong in upstream/downstream adapters.
+
+`graph.relate(source_id, target_id)` judges a specific pair for every applicable predicate in one call; it is useful when an existing parser already produces candidate pairs. Predicates are judged independently, so a pair can have more than one relationship. Multiple named graphs can share a SQLite file.
+
+## Vectors
+
+Supply embeddings in `Node(..., vector=...)`, declare their model/version as `Graph(..., embedding_space="your-model-version")`, and pass a query embedding to `search(..., vector=...)` or `retrieve(..., vector=...)`.
+
+The prototype fuses lexical and cosine rankings using reciprocal-rank fusion. It performs exact, exhaustive local retrieval; it does not ship an embedding model, approximate-nearest-neighbor index, or hosted database. All vectors in a graph must use one declared embedding space and dimension. You are responsible for using the same embedding model for records and queries. Updating a node without its vector explicitly removes that vector.
+
+## Relationship and search contracts
+
+- Each directed predicate receives independent JEV Noul questions for **support** and **contradiction**, with only its two source records as evidence. The query is excluded.
+- Judgments are `supported`, `contradicted`, `unsupported`, or `uncertain`. Only `supported` judgments are traversed. A high score for both support and contradiction remains uncertain.
+- Every judgment stores the exact supplied record text, source reference, content revision, relation, scores, and model. Source references are caller supplied; no byte offsets into an original file are invented.
+- Cache keys include source revisions, relationship definition, judge identity, graph namespace, and rubric revision. Updating/deleting a node invalidates its incident judgments. Changed thresholds reclassify cached scores.
+- JEV scores proposed path extensions and checks whether the current path answers the query. Search can follow edges in either direction while retaining the original directed claim.
+- Calls, typed questions, candidates per node, hops, and expanded paths are bounded. `goal_reached` is a model judgment; `no_seeds`, `frontier_exhausted`, `budget_exhausted`, `max_hops`, `max_expansions`, and `provider_error` describe other outcomes.
+- Path priority uses the minimum of edge-support and route scores along the path. It is a ranking heuristic, not a calibrated probability for the whole answer.
+
+JEV exposes typed decisions through its [System One API](https://docs.typesafe.ai/api). Noul returns a yes-probability; it does not have the separate confidence field used by Choice/Score. Defaults here are starting policies, not measured calibration. See TypeSafe's [confidence guidance](https://docs.typesafe.ai/confidence).
+
+## Current limits
+
+This is a small-corpus, synchronous reference implementation. It scans local records, considers a bounded candidate pool, and may miss relationships that retrieval never proposes. It cannot discover unnamed entities, guarantee exhaustive dependency impact, infer arbitrary new predicates, or prove source claims are true. Text is retained locally in SQLite and included in exported traces. Live JEV evaluates the selected text externally.
+
+The low-level graph namespaces are not an authentication boundary. The optional workspace server adds authenticated owner/workspace access checks before retrieval; it is a local prototype, not production enterprise identity management. There is no autonomous browser crawler, MCP server, distributed ingestion, temporal conflict resolver, or answer-generation model yet. Existing sources with conflicting claims remain evidence to inspect. A JEV request may be rejected by the 32 KB payload cap rather than truncated. Treat `Graph` as a single-threaded object.
+
+## Development
+
+```bash
+uv sync --extra dev --extra server
+uv run pytest
+uv run ruff check .
+uv build
+npm ci
+npx playwright install chromium
+npm run test:browser
+```
+
+Python tests cover the engine, access scopes, batch ingestion, updates/deletions, source filtering, and the JEV HTTP contract. JEV responses are simulated. Browser QA runs the actual MV3 extension against synthetic local pages and the real ingestion server, including a failed-upload retry, export/reimport, and desktop/mobile UI checks. [CONTRIBUTING.md](CONTRIBUTING.md) describes contribution expectations.
+
+## Related work
+
+- [neo4jev](https://github.com/jexp/neo4jev) explores JEV-guided traversal over existing Neo4j graphs.
+- [chenmingtang830/jevgraph](https://github.com/chenmingtang830/jevgraph) builds candidate knowledge graphs from documents using schema-guided relation decisions.
+- [neo4j-field/jev-graphrag](https://github.com/neo4j-field/jev-graphrag) explores JEV decisions in GraphRAG workflows.
+
+These are research references, not bundled dependencies. This package's experiment combines lazy relationship discovery, reusable judgments, and query-scoped traversal in a local Python API. It is an independent community prototype, with no claimed affiliation with TypeSafe or the projects above.
+
+## License
+
+[MIT](LICENSE). The package's license does not cover the external JEV service, embedding providers, or user-supplied source data.

jevgraph-0.2.0a1/README_PYPI.md

@@ -0,0 +1,73 @@
+# JEVGRAPH
+
+**Capture in the browser. Search in one workspace. Follow the evidence.**
+
+JEVGRAPH is an MIT-licensed Python graph engine with an optional local workplace search app and a bundled Chrome extension. It connects browser capture and agent ingestion to a searchable source library, with optional JEV relationship evaluation and bounded graph traversal.
+
+Version **0.2.0a1 is an alpha release** for local evaluation. Python 3.11 or newer is required. This is an independent project; other projects also use the JevGraph name.
+
+## Install and run
+
+```bash
+python -m pip install 'jevgraph[server]==0.2.0a1'
+jevgraph serve
+```
+
+Open `http://127.0.0.1:8765`. The server creates an owner-readable `.jevgraph/access.json` file in your current directory. Copy its token into the workspace connection dialog. The server listens on loopback; it is not a production hosted service.
+
+Choose **Get Chrome capture**, download and unzip the extension, and load that folder using **Load unpacked** at `chrome://extensions`. Open the extension's toolbar icon and connect it to the same workspace URL and token. Capture the current page or select up to 20 open tabs. Captures are private by default.
+
+For just the dependency-free graph engine:
+
+```bash
+python -m pip install 'jevgraph==0.2.0a1'
+jevgraph demo
+```
+
+The demo uses scripted fixture judgments and makes no network requests. It demonstrates traversal and caching, not live model accuracy.
+
+## Ingest browser-agent records or JSON dumps
+
+Use the workspace import dialog, `jevgraph ingest records.json`, or the Python client:
+
+```python
+import os
+from jevgraph import IngestionClient
+
+client = IngestionClient(
+    "http://127.0.0.1:8765",
+    os.environ["JEVGRAPH_ACCESS_TOKEN"],
+)
+receipt = client.ingest([{
+    "external_id": "project-42/handoff",
+    "title": "Project handoff",
+    "url": "https://example.com/projects/42",
+    "text": "The payment service depends on the identity service.",
+    "source_type": "agent",
+    "visibility": "private",
+}])
+print(receipt)
+```
+
+Stable external IDs update existing records instead of creating duplicates. Each batch accepts up to 50 records and 2 MB. The HTTP endpoint is `POST /api/ingest`, with a bearer token and a JSON object containing `records`.
+
+## What it provides
+
+- Local SQLite storage, scoped private/shared records, source previews, and import activity.
+- Chrome page capture, selected-tab collection, persistent upload queues, explicit retries, JSON export, and workspace search.
+- Keyword retrieval in the workspace; the engine also accepts caller-provided vectors.
+- Optional JEV evaluation of explicit relationships, cached judgments tied to source revisions, bounded traversal, and inspectable evidence traces.
+
+The central idea is to retain useful relationship judgments across searches instead of evaluating the same unchanged evidence repeatedly. Accuracy and cost improvements must be measured on your own workload; this release claims no benchmark advantage.
+
+## Optional JEV exploration
+
+Set `TYPESAFE_API_KEY` in the server environment and run `jevgraph serve --live`. Relationship exploration sends selected authorized evidence to TypeSafe. JEV is a separate API service; its model and service usage are not included in this package. Ordinary local ingestion and keyword search do not require that key.
+
+## Current boundaries
+
+Browser capture reads text loaded in the main frame. It is not a full export of paginated applications, PDFs, or canvas editors. It excludes form controls and editable/hidden regions and does not read browser cookies or browsing history.
+
+Stored copies have local workspace permissions. They do not automatically inherit upstream permission changes or deletions. Managed hosting, native connectors, automatic source synchronization, workspace embedding jobs, generated answers, SSO, and billing are not included yet. Live JEV quality has not been validated for this release.
+
+The source distribution includes `README.md`, `PRODUCT.md`, `DESIGN.md`, examples, and tests for further development. Licensed under MIT.