Repository files navigation

A physics‑inspired, model‑free coherence layer that transforms candidate embeddings into an explainable working‑memory state via convex energy minimization. Deterministic receipts for audit. Conjugate‑gradient solve with SPD guarantees.

Build coherence into retrieval and generation. Deterministic receipts for every decision. Latency that scales gracefully with corpus size. This is the missing layer from your RAG stack.

Setup: synthetic “facts + traps” dataset — see the notebook for N, k, trials, seed. Reproducible vianotebooks/04_hallucination_reduction.ipynb. Traps flagged; gate=0.01, off‑topic damp=0.5.

• Latency scales smoothly: with fixed D, k, and CG tol, settle tends to remain stable with denser graphs. Reference E2E < 40 ms at N≈1200 on a laptop CPU.
• Hallucination control: in our controlled study[1], Oscillink reduced trap selections while maintaining competitive F1. See the notebook for setup and reproduction.
• Receipts: SHA‑256 state signature; optional HMAC‑SHA256.schema
• Universal: works with any embeddings, no retraining.adapters ·quickstart
• Self‑optimizing: learns parameters over time.adaptive suite
• Production: scales to millions. See scripts underscripts/ for reproducible benchmarks.

Get Started ·API Docs ·See Results ·Live Demos

CI ·PyPI ·API ·Math ·Receipts ·Benchmarks ·Notebooks

• Overview
• Quickstart
• Adapters & Compatibility
• Reproducibility
• Performance
• Method (Technical)
• Deployment Options
• Security, Privacy, Legal
• Troubleshooting
• Contributing & License
• Changelog

pip install oscillink

Abstract. Oscillink is a physics‑inspired, model‑free coherence layer that transforms a set of candidate embeddings into an explainable working‑memory state by minimizing a strictly convex energy on a mutual‑kNN lattice. The system solves a symmetric positive‑definite (SPD) linear system via preconditioned conjugate gradients (CG), returning (i) refined embeddings U*, (ii) a deterministic, signed “receipt” with energy improvement ΔH, and (iii) per‑edge/null‑point diagnostics. No training is required; your embeddings are the model.

Install:pip install oscillink · Docs:API · Math:Overview · Receipts:Schema

• Overview
• Quickstart
• Adapters & Compatibility
• Reproducibility
• Performance
• Method (Technical)
• Deployment Options
• Security, Privacy, Legal
• Troubleshooting
• Contributing & License
• Changelog

Oscillink builds a transient mutual‑kNN graph over N×D anchorsY and settles to a unique global optimum of a convex energy. The result is a coherent bundle of items for a querypsi, along with an auditable “receipt” that explains the decision.

Outputs per run:

• Refined state U* (coherent embeddings)
• Receipt with ΔH (energy drop), term breakdown, CG iterations/residuals, and a SHA‑256 state signature (optional HMAC)
• Diagnostics: null points (incoherent edges), chain/prior scores (optional)

The system is deterministic, explainable, and training‑free.

Minimal, 60 seconds:

pip install oscillinkpython -<<'PY'import numpy as npfrom oscillink import Oscillink# Anchors (N x D, float32) and a D-dim queryY = np.random.randn(80,128).astype('float32')psi = (Y[:10].mean(0) / (np.linalg.norm(Y[:10].mean(0))+1e-9)).astype('float32')lat = Oscillink(Y, kneighbors=6, lamG=1.0, lamC=0.5, lamQ=4.0)lat.set_query(psi)lat.settle()print("top-5:", [(b.get("id", i), round(b["score"],3)) for i,b in enumerate(lat.bundle(k=5))])print("ΔH:", lat.receipt()["deltaH_total"])PY

System requirements: Python 3.10–3.12, NumPy ≥ 1.22 (1.x/2.x supported). CPU only.

SDK at a glance:

fromoscillinkimportOscillink# Y: (N, D) embeddings; psi: (D,) query (float32 recommended)lattice=Oscillink(Y,kneighbors=6)lattice.set_query(psi)lattice.settle()bundle=lattice.bundle(k=5)# coherent top-kreceipt=lattice.receipt()# deterministic audit (energy breakdown)

• Embeddings: Bring your own (OpenAI, Cohere, Sentence‑Transformers, local). Shapes:Y: (N, D),psi: (D,), preferably near unit‑norm float32.
• Dependencies: NumPy + small helpers; no framework lock‑in.
• Adapters: seeoscillink.adapters.* for simple text embedding utilities.
• Tuning: Practical knobs arekneighbors,lamC,lamQ. CLI--tune and the adaptive suite offer data‑driven defaults.
• Preprocessing: optionalsmart_correct can reduce incidental traps in noisy inputs.
• Platforms: Windows, macOS, Linux.

Claim → how to reproduce (scripts write JSON or plots):

Notes: The “facts + traps” setup used in the notebook is a controlled study to demonstrate controllability and auditability. Evaluate on your corpus before drawing production conclusions.

Reference (laptop, Python 3.11, NumPy BLAS, N≈1200, light receipts):

• Graph build: ~18 ms
• Settle: ~10 ms
• Receipt: ~3 ms

Total: under ~40 ms.

As N grows (fixed D, k, tol), CG typically converges in 3–4 iterations with Jacobi preconditioning; end‑to‑end times scale smoothly.

Complexity: one matvec is O(Nk); overall solve ≈ O(D · cg_iters · N · k).

Oscillink minimizes a convex energy on a mutual‑kNN lattice:

$$H(U)=\lambda_G|U-Y|_F^2+\lambda_C,\mathrm{tr}(U^\top L_{\mathrm{sym}}U)+\lambda_Q,\mathrm{tr}\big((U-\mathbf{1}\psi^\top)^\top,B,(U-\mathbf{1}\psi^\top)\big)$$

with optional path prior term$\lambda_P L_{\text{path}}$. Normal equations yield an SPD system$MU^*=F$ with

$$M=\lambda_G I+\lambda_C L_{\mathrm{sym}}+\lambda_Q B+\lambda_P L_{\text{path}},\quad F=\lambda_G Y+\lambda_Q B,\mathbf{1}\psi^\top.$$

Properties. If$\lambda_G&gt;0$ and$L_{\mathrm{sym}}, B, L_{\text{path}}$ are symmetric PSD, then$M$ is SPD ⇒ unique minimizer$U^*$. We solve with Jacobi‑preconditioned CG. Each run emits a receipt with$\Delta H$, per‑term energy, CG stats, and a SHA‑256 state signature (optional HMAC).

More detail:Foundations / Math Overview

Keep everything in‑process. See Install and examples underexamples/.

Run the API entirely inside your VPC/cluster. No embeddings or content leave your network; only license/usage heartbeats if enabled.

docker compose -f deploy/docker-compose.yml up -d

# set OSCILLINK_ADMIN_SECRET before running the containercurl -H"X-Admin-Secret:$OSCILLINK_ADMIN_SECRET" http://localhost:8000/admin/introspect

Opt‑in hosted API for convenience. Obtain an API key and call:

importos,httpxAPI_BASE=os.environ.get("OSCILLINK_API_BASE","https://api2.odinprotocol.dev")API_KEY=os.environ["OSCILLINK_API_KEY"]r=httpx.post(f"{API_BASE}/v1/settle",json={"Y": [[0.1,0.2]],"psi": [0.1,0.2],"options": {"bundle_k":1,"include_receipt":True}},headers={"X-API-Key":API_KEY},)print(r.json())

Cloud feature flags, quotas, and Stripe onboarding are documented underdocs/:

• Cloud architecture & ops:docs/cloud/CLOUD_ARCH_GCP.md,docs/ops/REDIS_BACKEND.md
• Billing:docs/billing/STRIPE_INTEGRATION.md,docs/billing/PRICING.md

• Local SDK: does not transmit embeddings/content anywhere.
• Cloud API: processes only request payloads; no training/retention beyond request lifecycle unless explicit caching is enabled.
• Receipts: contain derived numeric metrics and a state checksum; not raw content.
• Webhooks: keepOSCILLINK_ALLOW_UNVERIFIED_STRIPE=0 in production and setSTRIPE_WEBHOOK_SECRET.

Policies:Security ·Privacy ·Terms ·License ·Patent notice

Patent & OSS usage (FAQ). Oscillink is open‑source (Apache‑2.0). Apache‑2.0 includes an explicit patent license to practice the contributed Work. Our filing is primarily defensive.

• 422 Unprocessable Entity: ensureY: (N,D) andpsi: (D,) with finite float32 values.
• 403 Unauthorized: missing/invalidX-API-Key or suspended key.
• 429 Too Many Requests: rate/quota exceeded; seeX-Quota-*,X-RateLimit-*,X-IPLimit-* headers (andX-Monthly-* if enabled).
• Webhook signature error: verifySTRIPE_WEBHOOK_SECRET, server clock, andOSCILLINK_STRIPE_MAX_AGE.
• Redis not used: setOSCILLINK_STATE_BACKEND=redis andOSCILLINK_REDIS_URL (orREDIS_URL).

• License: Apache‑2.0 (seeLICENSE)
• Contributions welcome (seeCONTRIBUTING.md)
• Code of Conduct:CODE_OF_CONDUCT.md

Support & contacts. General:contact@oscillink.com · Security:security@oscillink.com · Founder:travisjohnson@oscillink.com. Brand: Oscillink is a brand of Odin Protocol Inc.

SeeCHANGELOG.md for release notes. Status: API v1 (stable) · Cloud: beta.

Controlled “facts + traps” dataset and notebook are provided to demonstrate controllability/auditability:

• Notebook:notebooks/04_hallucination_reduction.ipynb
• Dataset card (N, k, trials, seed) and CLI plot script:assets/benchmarks/ andscripts/plot_benchmarks.py

Simple, per‑container licensing with an enterprise cluster option (see details indocs/billing/PRICING.md):

• Starter: $49/container
• Team: $199/container
• Scale Pack: $699 (5 containers)
• Enterprise: $2k–$6k/cluster

Dev (free) for labs/evaluation with caps; annual discount available.

Notes on evaluation design: the hallucination/trap studies are synthetic/controlled and intended to validate auditability and controls, not to claim universal guarantees. For production, validate on your own corpus using the provided harness and receipts.

• Math & foundations:docs/foundations/MATH_OVERVIEW.md,docs/foundations/PHYSICS_FOUNDATIONS.md
• Receipts:docs/reference/RECEIPTS.md,docs/reference/RECEIPT_SCHEMA.md
• API reference and OpenAPI baseline:docs/reference/API.md,openapi_baseline.json
• Benchmarks & scripts:benchmarks/,scripts/,examples/,notebooks/

Acknowledgments: This repository uses standard sparse linear algebra techniques (mutual‑kNN graphs, Laplacians, SPD solvers) adapted for explainable coherence in embedding workflows.

Contact: For design‑partner inquiries (on‑prem container, regulated deployments):contact@oscillink.com.