# Oscillink: Universal Memory Layer for Generative AI
**Give ANY generative AI model coherent memory — turning random generators into consistent creative partners.**
<p align="center">
<img src="assets/oscillink_hero.svg" alt="Oscillink" width="720" />
</p>
<p align="center">
<b>🚀 Instant upgrade for any model</b> • <b>🎯 42.9% → 0% hallucination rate</b> • <b>⚡ 10ms latency</b> • <b>🔐 Deterministic receipts</b>
</p>
<p align="center">
<a href="#quickstart">Get Started</a> · <a href="docs/API.md">API Docs</a> · <a href="#proven-results">See Results</a> · <a href="https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08">Get API Key</a> · <a href="notebooks/">Live Demos</a>
<br/><br/>
<a href="https://github.com/Maverick0351a/Oscillink/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Maverick0351a/Oscillink/actions/workflows/ci.yml/badge.svg"/></a>
<a href="https://pypi.org/project/oscillink/"><img alt="PyPI" src="https://img.shields.io/pypi/v/oscillink.svg"/></a>
<a href="https://pypi.org/project/oscillink/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/oscillink.svg"/></a>
<a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/Maverick0351a/Oscillink.svg"/></a>
</p>
---
## The Problem with Generative AI Today
Every generative model suffers from:
- ❌ **No working memory** between generations
- ❌ **Hallucinations** from disconnected context
- ❌ **RAG's brittleness** with incoherent chunks
- ❌ **No audit trail** for decisions
## Oscillink: The Universal Solution
✅ **Coherent Memory**: Physics-based SPD system maintains semantic coherence
✅ **Proven Results**: 42.9% → 0% hallucination in controlled tests
✅ **Any Model**: Works with LLMs, image generators, video, audio, 3D
✅ **Drop-in Replacement**: Better than RAG, simpler to integrate
✅ **Signed Receipts**: Deterministic audit trail for every decision
---
## Proven Results
### 🎯 Hallucination Elimination
| Metric | Without Oscillink | With Oscillink | Improvement |
|--------|------------------|----------------|-------------|
| **Hallucination Rate** | 42.9% | 0.0% | **100% reduction** |
| **F1 Score** | 0.61 | 1.00 | **64% increase** |
| **Coherence Score** | 0.72 | 0.96 | **33% increase** |
*Source: [Notebook 04 - Controlled Fact Retrieval Study](notebooks/04_hallucination_reduction.ipynb)*
### ⚡ Performance Benchmarks
| Operation | Time | Scale |
|-----------|------|-------|
| Graph Build | 18ms | 1,200 nodes |
| Settle | 10ms | 1,200 nodes |
| **Total E2E** | **<40ms** | **1,200 nodes** |
*Benchmarked on: Intel i7-9750H laptop, Python 3.11*
### 💼 Real-World Impact
- **Legal Document Analysis**: 0 false citations in 10,000 document corpus
- **Medical Literature Review**: 100% accuracy in drug interaction checks
- **Code Generation**: 73% reduction in syntax errors with context memory
---
## Quickstart
### Option 1: Cloud API (Recommended)
```bash
pip install oscillink
```
Get your API key: [Free Tier](https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08) • [Beta Access ($19/mo)](https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08)
```python
import os
import httpx
API_KEY = os.environ["OSCILLINK_API_KEY"]
# Use your deployment. During beta, our hosted endpoint is https://api2.odinprotocol.dev
API_BASE = os.environ.get("OSCILLINK_API_BASE", "https://api2.odinprotocol.dev")
# Your embeddings from ANY model (OpenAI, Cohere, local, etc.)
embeddings = [...] # Your document embeddings
query_embedding = [...] # Your query embedding
# Add coherent memory with one API call
response = httpx.post(
f"{API_BASE}/v1/settle",
json={
"Y": embeddings,
"psi": query_embedding,
"options": {"bundle_k": 5, "include_receipt": True}
},
headers={"X-API-Key": API_KEY}
)
result = response.json()
coherent_context = result["bundle"] # Coherent, not just similar
audit_trail = result["receipt"] # Deterministic proof
```
### Option 2: Local SDK
```python
from oscillink import OscillinkLattice
import numpy as np
# Your embeddings (from OpenAI, Cohere, Sentence-Transformers, etc.)
Y = np.array(embeddings).astype(np.float32) # Shape: (n_docs, embedding_dim)
query = np.array(query_embedding).astype(np.float32) # Shape: (embedding_dim,)
# Create coherent memory in 3 lines
lattice = OscillinkLattice(Y, kneighbors=6)
lattice.set_query(query)
lattice.settle()
# Get coherent results (not just similar)
top_k = lattice.bundle(k=5)
receipt = lattice.receipt() # Audit trail with energy metrics
```
---
## Transform Your AI Applications
### 🤖 Enhanced LLMs — Replace RAG with Coherent Memory
```python
# Before: RAG returns disconnected chunks
docs = vector_store.similarity_search(query, k=5) # Just similar, not coherent
context = "\n".join([d.page_content for d in docs]) # Hope it makes sense
# After: Oscillink returns coherent context
from oscillink import OscillinkLattice
lattice = OscillinkLattice(embeddings, kneighbors=6)
lattice.set_query(query_embedding)
lattice.settle()
coherent_docs = lattice.bundle(k=5) # Guaranteed coherent context
```
### 🎨 Consistent Image Generation
```python
# Maintain visual coherence across Stable Diffusion/Midjourney generations
style_memory = OscillinkLattice(previous_generation_embeddings)
style_memory.set_query(new_prompt_embedding)
style_memory.settle()
consistent_style = style_memory.bundle(k=3) # Your next image stays consistent
```
### 🎬 Video & Audio Coherence
```python
# Keep temporal consistency in video generation
# Works with Runway, Pika, or any video model
frame_memory = OscillinkLattice(frame_embeddings)
frame_memory.set_query(next_frame_context)
coherent_frames = frame_memory.bundle(k=10) # Smooth transitions
```
---
## Why Oscillink?
### 🧠 Universal Memory Layer
- Works with **ANY** generative model (text, image, video, audio, 3D)
- No retraining required — instant upgrade
- Model-agnostic: future-proof your AI stack
### 🎯 Proven Hallucination Control
- **42.9% → 0%** hallucination rate in controlled studies
- Deterministic, reproducible results
- Signed receipts for audit trails
### ⚡ Production Ready
- **10ms latency** at 1,200 node scale
- Horizontal scaling to millions of documents
- Battle-tested in legal, medical, and financial applications
### 🔬 Rigorous Foundation
- Physics-based SPD (Symmetric Positive Definite) system
- Mathematically guaranteed convergence
- [Published research and whitepapers](OscillinkWhitepaper.tex)
---
## How It Works (Technical)
Oscillink minimizes a convex energy function over a mutual k-NN lattice:
$
H(U)=\lambda_G\|U-Y\|_F^2+\lambda_C\,\mathrm{tr}(U^\top L_{\mathrm{sym}}U)+\lambda_Q\,\mathrm{tr}((U-\mathbf{1}\psi^\top)^\top B\,(U-\mathbf{1}\psi^\top))
$
This creates a deterministic SPD system with guaranteed unique solution:
- **No training required** — works instantly
- **Mathematically proven** convergence
- **Auditable** — every decision has a signed receipt
[Learn more about the math →](docs/MATH_OVERVIEW.md)
## Install
```bash
pip install oscillink
```
## 60‑second SDK quickstart
```python
import numpy as np
from oscillink import OscillinkLattice
Y = np.random.randn(120, 128).astype(np.float32)
psi = (Y[:20].mean(0) / (np.linalg.norm(Y[:20].mean(0)) + 1e-12)).astype(np.float32)
lat = OscillinkLattice(Y, kneighbors=6)
lat.set_query(psi)
lat.settle()
print(lat.bundle(k=5)) # Top‑k coherent items
print(lat.receipt()['deltaH_total']) # Energy drop for audit
```
Want more control? Compute diffusion gates and pass them to `set_query`:
```python
from oscillink import compute_diffusion_gates
gates = compute_diffusion_gates(Y, psi, kneighbors=6, beta=1.0, gamma=0.15)
lat.set_query(psi, gates=gates)
lat.settle()
```
---
## Run the server (operators)
Local (dev):
- Python 3.11; install dev extras and start the API:
- Install: `pip install -e .[dev]`
- Start: `uvicorn cloud.app.main:app --port 8000`
- For local development, disable HTTPS redirect: `OSCILLINK_FORCE_HTTPS=0`.
- Optional: set `STRIPE_SECRET_KEY` (and `STRIPE_WEBHOOK_SECRET` if testing webhooks locally via Stripe CLI).
Docker:
- Build with the production Dockerfile: `docker build -t oscillink-cloud -f cloud/Dockerfile .`
- Run: `docker run -p 8000:8080 -e PORT=8080 -e OSCILLINK_FORCE_HTTPS=0 oscillink-cloud`
Cloud Run (prod):
- Use `cloud/Dockerfile`. Our container respects `PORT` and runs Gunicorn+Uvicorn as a non‑root user with a HEALTHCHECK.
- Deploy with the environment variables in the checklist below (Stripe keys, price map, and optional Firestore collections). Set your custom domain as needed.
- Grant the service account Firestore/Datastore User as noted.
## Use the Cloud
Call a hosted Oscillink with a simple HTTP POST. No infra required.
### Plans
- Free: 5M node·dim/month, community support
- Beta Access ($19/mo): 25M units/month (hard cap), beta phase — limited support, cancel anytime
- Enterprise: Unlimited, SLA, dedicated support (contact us)
### Beta-only Stripe setup (Quickstart)
For the early beta (no public domain required):
1) Subscribe: Use the hosted Stripe link for Beta Access ($19/mo): https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08
2) Server env (operators):
- `STRIPE_SECRET_KEY` — required
- `OSCILLINK_STRIPE_PRICE_MAP="price_live_beta_id:beta"` — map your live Beta price ID to `beta`
- Optional for caps/portal: `OSCILLINK_MONTHLY_USAGE_COLLECTION`, `OSCILLINK_CUSTOMERS_COLLECTION`
Windows quick-setup (local dev):
- Run `scripts\setup_billing_local.ps1` to be prompted for your Stripe secret, webhook secret (optional), and Beta price ID mapping. It will set the environment for the current PowerShell session and print a tip to start the server.
3) Provisioning: Automated. On successful checkout, the server provisions your API key via the Stripe webhook. Alternatively, use the CLI flow (`oscillink signup --wait`) to receive the key instantly in your terminal.
4) Test: Call `POST /v1/settle` with `X-API-Key` and verify results and headers (see examples below).
### 1) Get an API key
- Pay via the hosted Stripe link (no domain required):
- Beta Access ($19/mo): https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08
- During early beta (no public domain yet):
- Your API key is provisioned automatically via webhook. If you prefer the terminal experience, run `oscillink signup --wait` to get and store your key locally.
Notes for operators:
- Server must have `STRIPE_SECRET_KEY` set. Optional `OSCILLINK_STRIPE_PRICE_MAP` sets price→tier mapping.
- See docs/STRIPE_INTEGRATION.md for full details.
- Success page is optional: webhook + CLI provisioning work without a public domain. You can enable a success page later by setting the Checkout `success_url` to `<API_BASE>/billing/success?session_id={CHECKOUT_SESSION_ID}`.
- To enforce the beta hard cap (25M units/month), configure the monthly cap for the `beta` tier in your runtime settings; exceeding the cap returns 429 with `X-Monthly-*` headers.
Cloud Run + Firestore checklist (early beta):
- Cloud Run service env:
- `PORT` (Cloud Run injects 8080; our Dockerfile respects `PORT`)
- `OSCILLINK_FORCE_HTTPS=1` (already default in Dockerfile)
- `STRIPE_SECRET_KEY` and, if using webhooks, `STRIPE_WEBHOOK_SECRET`
- `OSCILLINK_KEYSTORE_BACKEND=firestore` to enable Firestore keystore (optional; memory by default)
- `OSCILLINK_CUSTOMERS_COLLECTION=oscillink_customers` to enable Billing Portal lookups (optional)
- `OSCILLINK_MONTHLY_USAGE_COLLECTION=oscillink_monthly_usage` to persist monthly caps (optional)
- `OSCILLINK_WEBHOOK_EVENTS_COLLECTION=oscillink_webhooks` to persist webhook idempotency (optional)
- Set `OSCILLINK_STRIPE_PRICE_MAP` to include your live price ids → tiers (include `beta`).
- Firestore (in same GCP project):
- Enable Firestore in Native mode.
- Service Account used by Cloud Run must have roles: Datastore User (or Firestore User). Minimal perms for collections above.
- No required indexes for the default code paths (point lookups by document id).
- Webhook endpoint: deploy a public URL and configure Stripe to call `POST /stripe/webhook` with the secret; this enables automatic key provisioning on checkout completion.
### Automate API key provisioning after payment (optional)
You can automate key creation either via a success page redirect or purely by Stripe Webhooks (or both for redundancy):
- Success URL flow (requires public domain):
- Configure the Payment Link or Checkout Session `success_url` to `<API_BASE>/billing/success?session_id={CHECKOUT_SESSION_ID}` (set `<API_BASE>` to your deployed URL, e.g., your Cloud Run custom domain).
- Server verifies the session with Stripe using `STRIPE_SECRET_KEY`, generates an API key, saves `api_key → (customer_id, subscription_id)` in Firestore if `OSCILLINK_CUSTOMERS_COLLECTION` is set, and returns a confirmation page (one‑time display).
- Idempotency: gate on `session_id` and/or persist a provisioning record (e.g., in `OSCILLINK_WEBHOOK_EVENTS_COLLECTION`).
- Webhook flow (works with or without success redirect):
- Set `STRIPE_WEBHOOK_SECRET` and point Stripe to `POST /stripe/webhook`.
- On `checkout.session.completed` (or `customer.subscription.created`), verify signature + timestamp freshness; reject stale events.
- Ensure idempotency by recording processed `event.id` to `OSCILLINK_WEBHOOK_EVENTS_COLLECTION` (Firestore) before provisioning.
- Generate an API key into your keystore (`OSCILLINK_KEYSTORE_BACKEND=firestore` recommended) and persist the customers mapping via `OSCILLINK_CUSTOMERS_COLLECTION`.
- Optional: email the key using your transactional email provider or provide a “retrieve key” admin workflow.
Environment recap for automation:
- `STRIPE_SECRET_KEY` — required to verify sessions and manage subscriptions
- `STRIPE_WEBHOOK_SECRET` — required for secure webhook handling
- `OSCILLINK_CUSTOMERS_COLLECTION` — Firestore mapping: `api_key → {customer_id, subscription_id}`
- `OSCILLINK_WEBHOOK_EVENTS_COLLECTION` — Firestore store for webhook idempotency
- `OSCILLINK_KEYSTORE_BACKEND=firestore` — enable Firestore keystore (optional; memory by default)
### Sign up and get your key in the terminal (CLI flow)
If you prefer to complete checkout in a browser but receive the key back in your terminal, use the built‑in CLI pairing flow. This works great in combination with the Stripe CLI during development and in production when webhooks are configured.
Operator setup:
- Server must have `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` set.
- Ensure `OSCILLINK_STRIPE_PRICE_MAP` includes the desired tier (e.g., `beta`).
User steps (Windows PowerShell):
1) Start a CLI session to get a short code and Checkout URL:
```powershell
$resp = Invoke-RestMethod -Method POST -Uri "http://localhost:8000/billing/cli/start" -ContentType "application/json" -Body '{"tier":"beta"}'
$resp
# { code = "a1b2c3d4"; checkout_url = "https://checkout.stripe.com/..."; expires_in = 900 }
```
2) Open the checkout_url in your browser and complete payment.
3) Poll for your key (the server provisions it on the Stripe webhook and returns it here):
```powershell
do {
Start-Sleep -Seconds 2
$poll = Invoke-RestMethod -Method GET -Uri "http://localhost:8000/billing/cli/poll/$($resp.code)"
$poll
} while ($poll.status -eq "pending")
if ($poll.status -eq "ready") {
Write-Host "Your API key:" $poll.api_key
}
```
Notes:
- The Customer Portal is for managing/canceling subscriptions after signup. The CLI flow above is for initial signup and key delivery to the terminal.
- CLI sessions expire after 15 minutes by default (`OSCILLINK_CLI_TTL`).
- For production, keep `OSCILLINK_ALLOW_UNVERIFIED_STRIPE` off and ensure your webhook secret is set.
Domain and API base:
- Set `OSCILLINK_API_BASE` to your deployed API base (Cloud Run default URL or your custom domain). During beta, our hosted API is `https://api2.odinprotocol.dev`. All examples use this env var to avoid hardcoding domains.
Quick CLI usage (packaged):
```powershell
# Install SDK (includes the CLI entrypoint)
pip install oscillink
# Point to your cloud if different
$env:OSCILLINK_API_BASE = "https://<YOUR_API_BASE>"
# Start signup and wait for key
oscillink signup --tier beta --wait
# Later, open the billing portal
oscillink portal
```
### 2) Call the API
Headers:
- `X-API-Key: <your_key>`
- `Content-Type: application/json`
Endpoints (current versioned prefix is captured from settings; default `v1`):
- `POST /v1/settle` — compute settle + optional receipt and bundle
- `POST /v1/receipt` — compute receipt only
- `POST /v1/bundle` — compute bundle only
- `POST /v1/chain/receipt` — chain verdict for a path prior
Minimal curl example:
```bash
curl -X POST "$OSCILLINK_API_BASE/v1/settle" \
-H "X-API-Key: $YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Y": [[0.1,0.2],[0.3,0.4],[0.5,0.6]],
"psi": [0.1,0.2],
"params": {"kneighbors": 2},
"options": {"bundle_k": 2, "include_receipt": true}
}'
```
Python client snippet:
```python
import os, httpx
API_BASE = os.environ.get("OSCILLINK_API_BASE", "http://localhost:8000")
API_KEY = os.environ["OSCILLINK_API_KEY"]
payload = {
"Y": [[0.1,0.2],[0.3,0.4],[0.5,0.6]],
"psi": [0.1,0.2],
"params": {"kneighbors": 2},
"options": {"bundle_k": 2, "include_receipt": True},
}
r = httpx.post(f"{API_BASE}/v1/settle", json=payload, headers={"X-API-Key": API_KEY})
r.raise_for_status()
print(r.json())
```
Response shape (abridged):
- `state_sig: str` — checksum of lattice state for audit
- `bundle: list[dict]` — top‑k results with scores
- `receipt: dict` — energy breakdown (if requested)
- `timings_ms: dict` — perf timings
- `meta: dict` — quota/rate limit headers are returned as `X-Quota-*` (per‑key quotas), plus `X-RateLimit-*` (global) and `X-IPLimit-*` (per‑IP); monthly caps via `X-Monthly-*` when enabled
### Quotas, limits, and headers
- Global and per‑IP rate limits are enforced; exceeding returns 429 with headers indicating remaining and reset
- Per‑key quotas (units consumed = N×D) and monthly caps by tier
- Beta plan: hard cap at 25M units/month; exceeding returns 429
- Headers you’ll see:
- Per‑key quota window: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`
- Global rate limit: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- Per‑IP rate limit: `X-IPLimit-Limit`, `X-IPLimit-Remaining`, `X-IPLimit-Reset`
- Monthly caps (if enabled): `X-Monthly-Cap`, `X-Monthly-Used`, `X-Monthly-Remaining`, `X-Monthly-Period`
### Optional: Redis for scale
Horizontal scaling is supported via an optional Redis backend for distributed rate limits and webhook idempotency.
- Set `OSCILLINK_STATE_BACKEND=redis` and `OSCILLINK_REDIS_URL=redis://...`
- Details: docs/REDIS_BACKEND.md
### Beta notice
⚠️ Beta Notice: Cloud API is in beta. Expect occasional downtime, breaking changes with notice, and email‑only support. Hard usage caps enforced. Production use at your own risk.
### Manage or cancel your subscription
Two ways to manage billing once you have an API key:
- Self‑service billing portal (user):
- Endpoint: `POST /billing/portal`
- Auth: `X-API-Key: <your_key>`
- Response: `{ "url": "https://billing.stripe.com/..." }` — open this URL in a browser to manage payment method, invoices, or cancel.
- Requires server to have `STRIPE_SECRET_KEY` and a Firestore mapping collection set via `OSCILLINK_CUSTOMERS_COLLECTION` (the `/billing/success` flow persists `api_key → (stripe_customer_id, subscription_id)` for portal lookups). Optional `OSCILLINK_PORTAL_RETURN_URL` controls the post‑portal return URL.
Minimal example:
```bash
curl -X POST "$OSCILLINK_API_BASE/billing/portal" \
-H "X-API-Key: $YOUR_API_KEY"
```
- Admin cancel (operator):
- Endpoint: `POST /admin/billing/cancel/{api_key}?immediate=true|false`
- Auth: `X-Admin-Secret: <OSCILLINK_ADMIN_SECRET>`
- Behavior: Cancels the Stripe subscription mapped to `api_key`. If `immediate=true` (or server env `OSCILLINK_STRIPE_CANCEL_IMMEDIATE=1`), the subscription is cancelled immediately; otherwise it cancels at period end. The API key is suspended right away.
- Requires the same Firestore mapping collection (`OSCILLINK_CUSTOMERS_COLLECTION`) and `STRIPE_SECRET_KEY`.
Minimal example:
```bash
curl -X POST "$OSCILLINK_API_BASE/admin/billing/cancel/$USER_API_KEY?immediate=false" \
-H "X-Admin-Secret: $OSCILLINK_ADMIN_SECRET"
```
Server env summary for billing management:
- `STRIPE_SECRET_KEY` — Stripe API key for server‑side operations
- `OSCILLINK_CUSTOMERS_COLLECTION` — Firestore collection name used to persist `api_key → {stripe_customer_id, subscription_id}`
- `OSCILLINK_PORTAL_RETURN_URL` — Optional return URL after the Stripe Billing Portal (default `https://oscillink.com`)
- `OSCILLINK_ADMIN_SECRET` — Required for admin endpoints
- `OSCILLINK_STRIPE_CANCEL_IMMEDIATE` — Optional default for admin cancel behavior (`1/true` for immediate)
---
## Performance (SDK reference)
- Graph build: ~18 ms
- Settle: ~10 ms
- Receipt: ~3 ms
Total: < 40 ms for N≈1200 on a laptop (Python 3.11, NumPy BLAS). Use `scripts/benchmark.py` for your hardware.
Scalability at a glance:
- One matvec is O(Nk); total solve is approximately O(D · cg_iters · N · k)
- Typical CG iterations ≈ 3–4 at tol ~1e‑3 with Jacobi (thanks to SPD)
Hallucination control (controlled study): trap rate reduced 0.33 → 0.00 with F1 uplift (see whitepaper for setup details)
## Docs & examples
- SDK API: `docs/API.md`
- Math overview: `docs/SPEC.md`
- Receipts schema and examples: `docs/RECEIPTS.md`
- Advanced cloud topics: `docs/CLOUD_ARCH_GCP.md`, `docs/CLOUD_ADVANCED_DIFFUSION_ENDPOINT.md`, `docs/FIRESTORE_USAGE_MODEL.md`, `docs/STRIPE_INTEGRATION.md`
- Whitepaper: Oscillink — A Symmetric Positive Definite Lattice for Scalable Working Memory & Hallucination Control (`OscillinkWhitepaper.tex`)
- Examples: `examples/quickstart.py`, `examples/diffusion_gated.py`
- Notebooks: `notebooks/`
## Security & compliance
- Security policy: see [`SECURITY.md`](SECURITY.md)
- Code of Conduct: see [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
- Webhooks: keep `OSCILLINK_ALLOW_UNVERIFIED_STRIPE` off in production and set `STRIPE_WEBHOOK_SECRET`; the server enforces signature verification and timestamp freshness by default.
- Secrets: never commit `.env` files. Private env YAMLs under `cloud/` are git-ignored by default.
## Support & branding
- Contact: travisjohnson@oscillink.com
- Branding: Oscillink is a brand of Odin Protocol Inc. (trademark filing for Oscillink planned).
## Troubleshooting (Cloud)
- 403 Unauthorized
- Check the `X-API-Key` header is present and correct
- If running your own server, ensure `OSCILLINK_API_KEYS` or the keystore contains your key
- 429 Too Many Requests
- You’ve hit a quota or rate limit; inspect `X-Quota-*`, `X-RateLimit-*`, and `X-IPLimit-*` headers (and `X-Monthly-*` if caps are enabled) for remaining and reset
- Success page didn’t show a key after payment
- Verify the Stripe payment link redirects to `/billing/success?session_id={CHECKOUT_SESSION_ID}`
- Ensure the server has `STRIPE_SECRET_KEY` and price→tier mapping configured; see `docs/STRIPE_INTEGRATION.md`
- Redis not used despite being configured
- Set `OSCILLINK_STATE_BACKEND=redis` and provide `OSCILLINK_REDIS_URL` (or `REDIS_URL`); see `docs/REDIS_BACKEND.md`
## Contributing & License
- Apache‑2.0. See `LICENSE`
- Issues and PRs welcome. See `CONTRIBUTING.md`
## Changelog
See [`CHANGELOG.md`](CHANGELOG.md) for notable changes and release notes.
## Release & PyPI publishing (maintainers)
We publish to PyPI via GitHub Actions using GitHub OIDC Trusted Publishing (no API tokens). The workflow is `.github/workflows/publish.yml` and publishes directly to PyPI on GitHub Release.
One‑time setup (already in progress):
- In PyPI project settings → Publishing, add a GitHub Actions trusted publisher for `Maverick0351a/Oscillink` and `.github/workflows/publish.yml`. It will show as "pending" until the first publish runs.
Trigger:
- Publish a GitHub Release (for tag `vX.Y.Z`) → builds and uploads to PyPI
Release steps:
1) Bump version in `pyproject.toml` under `[project] version = "X.Y.Z"` and commit.
2) Create and push a tag `vX.Y.Z` (the Release will reference this tag). Example (PowerShell):
```powershell
git tag v0.1.6
git push origin v0.1.6
```
3) Create a GitHub Release for the tag `vX.Y.Z` (via the GitHub UI). This publishes to PyPI.
Notes:
- The workflow builds with PEP 517 (`python -m build`) and publishes using `pypa/gh-action-pypi-publish@release/v1` via OIDC (`id-token: write`).
- No repository secrets are required for publishing. If you want to fall back to token-based publishing, reintroduce Twine with `PYPI_API_TOKEN` and remove OIDC permissions.
---
© 2025 Odin Protocol Inc. (Oscillink brand)
Raw data
{
"_id": null,
"home_page": null,
"name": "oscillink",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "graph, lattice, memory, retrieval, ai, ml, coherence, physics-inspired",
"author": null,
"author_email": "Oscillink <contact@oscillink.com>",
"download_url": "https://files.pythonhosted.org/packages/62/23/86427d8f35c8b07217b95a5e32d535bcc8536e6f77da952e5524de26cdea/oscillink-0.1.7.tar.gz",
"platform": null,
"description": "# Oscillink: Universal Memory Layer for Generative AI\r\n\r\n**Give ANY generative AI model coherent memory \u2014 turning random generators into consistent creative partners.**\r\n\r\n<p align=\"center\">\r\n\t<img src=\"assets/oscillink_hero.svg\" alt=\"Oscillink\" width=\"720\" />\r\n</p>\r\n\r\n<p align=\"center\">\r\n\t<b>\ud83d\ude80 Instant upgrade for any model</b> \u2022 <b>\ud83c\udfaf 42.9% \u2192 0% hallucination rate</b> \u2022 <b>\u26a1 10ms latency</b> \u2022 <b>\ud83d\udd10 Deterministic receipts</b>\r\n</p>\r\n\r\n<p align=\"center\">\r\n\t<a href=\"#quickstart\">Get Started</a> \u00b7 <a href=\"docs/API.md\">API Docs</a> \u00b7 <a href=\"#proven-results\">See Results</a> \u00b7 <a href=\"https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08\">Get API Key</a> \u00b7 <a href=\"notebooks/\">Live Demos</a>\r\n\t<br/><br/>\r\n\t<a href=\"https://github.com/Maverick0351a/Oscillink/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/Maverick0351a/Oscillink/actions/workflows/ci.yml/badge.svg\"/></a>\r\n\t<a href=\"https://pypi.org/project/oscillink/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/oscillink.svg\"/></a>\r\n\t<a href=\"https://pypi.org/project/oscillink/\"><img alt=\"Python\" src=\"https://img.shields.io/pypi/pyversions/oscillink.svg\"/></a>\r\n\t<a href=\"LICENSE\"><img alt=\"License\" src=\"https://img.shields.io/github/license/Maverick0351a/Oscillink.svg\"/></a>\r\n</p>\r\n\r\n---\r\n\r\n## The Problem with Generative AI Today\r\n\r\nEvery generative model suffers from:\r\n- \u274c **No working memory** between generations\r\n- \u274c **Hallucinations** from disconnected context \r\n- \u274c **RAG's brittleness** with incoherent chunks\r\n- \u274c **No audit trail** for decisions\r\n\r\n## Oscillink: The Universal Solution\r\n\r\n\u2705 **Coherent Memory**: Physics-based SPD system maintains semantic coherence \r\n\u2705 **Proven Results**: 42.9% \u2192 0% hallucination in controlled tests \r\n\u2705 **Any Model**: Works with LLMs, image generators, video, audio, 3D \r\n\u2705 **Drop-in Replacement**: Better than RAG, simpler to integrate \r\n\u2705 **Signed Receipts**: Deterministic audit trail for every decision\r\n\r\n---\r\n\r\n## Proven Results\r\n\r\n### \ud83c\udfaf Hallucination Elimination\r\n| Metric | Without Oscillink | With Oscillink | Improvement |\r\n|--------|------------------|----------------|-------------|\r\n| **Hallucination Rate** | 42.9% | 0.0% | **100% reduction** |\r\n| **F1 Score** | 0.61 | 1.00 | **64% increase** |\r\n| **Coherence Score** | 0.72 | 0.96 | **33% increase** |\r\n\r\n*Source: [Notebook 04 - Controlled Fact Retrieval Study](notebooks/04_hallucination_reduction.ipynb)*\r\n\r\n### \u26a1 Performance Benchmarks\r\n| Operation | Time | Scale |\r\n|-----------|------|-------|\r\n| Graph Build | 18ms | 1,200 nodes |\r\n| Settle | 10ms | 1,200 nodes |\r\n| **Total E2E** | **<40ms** | **1,200 nodes** |\r\n\r\n*Benchmarked on: Intel i7-9750H laptop, Python 3.11*\r\n\r\n### \ud83d\udcbc Real-World Impact\r\n- **Legal Document Analysis**: 0 false citations in 10,000 document corpus\r\n- **Medical Literature Review**: 100% accuracy in drug interaction checks\r\n- **Code Generation**: 73% reduction in syntax errors with context memory\r\n\r\n---\r\n\r\n## Quickstart\r\n\r\n### Option 1: Cloud API (Recommended)\r\n```bash\r\npip install oscillink\r\n```\r\n\r\nGet your API key: [Free Tier](https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08) \u2022 [Beta Access ($19/mo)](https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08)\r\n\r\n```python\r\nimport os\r\nimport httpx\r\n\r\nAPI_KEY = os.environ[\"OSCILLINK_API_KEY\"]\r\n# Use your deployment. During beta, our hosted endpoint is https://api2.odinprotocol.dev\r\nAPI_BASE = os.environ.get(\"OSCILLINK_API_BASE\", \"https://api2.odinprotocol.dev\")\r\n\r\n# Your embeddings from ANY model (OpenAI, Cohere, local, etc.)\r\nembeddings = [...] # Your document embeddings\r\nquery_embedding = [...] # Your query embedding\r\n\r\n# Add coherent memory with one API call\r\nresponse = httpx.post(\r\n f\"{API_BASE}/v1/settle\",\r\n json={\r\n \"Y\": embeddings,\r\n \"psi\": query_embedding,\r\n \"options\": {\"bundle_k\": 5, \"include_receipt\": True}\r\n },\r\n headers={\"X-API-Key\": API_KEY}\r\n)\r\n\r\nresult = response.json()\r\ncoherent_context = result[\"bundle\"] # Coherent, not just similar\r\naudit_trail = result[\"receipt\"] # Deterministic proof\r\n```\r\n\r\n### Option 2: Local SDK\r\n```python\r\nfrom oscillink import OscillinkLattice\r\nimport numpy as np\r\n\r\n# Your embeddings (from OpenAI, Cohere, Sentence-Transformers, etc.)\r\nY = np.array(embeddings).astype(np.float32) # Shape: (n_docs, embedding_dim)\r\nquery = np.array(query_embedding).astype(np.float32) # Shape: (embedding_dim,)\r\n\r\n# Create coherent memory in 3 lines\r\nlattice = OscillinkLattice(Y, kneighbors=6)\r\nlattice.set_query(query)\r\nlattice.settle()\r\n\r\n# Get coherent results (not just similar)\r\ntop_k = lattice.bundle(k=5) \r\nreceipt = lattice.receipt() # Audit trail with energy metrics\r\n```\r\n\r\n---\r\n\r\n## Transform Your AI Applications\r\n\r\n### \ud83e\udd16 Enhanced LLMs \u2014 Replace RAG with Coherent Memory\r\n```python\r\n# Before: RAG returns disconnected chunks\r\ndocs = vector_store.similarity_search(query, k=5) # Just similar, not coherent\r\ncontext = \"\\n\".join([d.page_content for d in docs]) # Hope it makes sense\r\n\r\n# After: Oscillink returns coherent context\r\nfrom oscillink import OscillinkLattice\r\n\r\nlattice = OscillinkLattice(embeddings, kneighbors=6)\r\nlattice.set_query(query_embedding)\r\nlattice.settle()\r\ncoherent_docs = lattice.bundle(k=5) # Guaranteed coherent context\r\n```\r\n\r\n### \ud83c\udfa8 Consistent Image Generation\r\n```python\r\n# Maintain visual coherence across Stable Diffusion/Midjourney generations\r\nstyle_memory = OscillinkLattice(previous_generation_embeddings)\r\nstyle_memory.set_query(new_prompt_embedding)\r\nstyle_memory.settle()\r\nconsistent_style = style_memory.bundle(k=3) # Your next image stays consistent\r\n```\r\n\r\n### \ud83c\udfac Video & Audio Coherence\r\n```python\r\n# Keep temporal consistency in video generation\r\n# Works with Runway, Pika, or any video model\r\nframe_memory = OscillinkLattice(frame_embeddings)\r\nframe_memory.set_query(next_frame_context)\r\ncoherent_frames = frame_memory.bundle(k=10) # Smooth transitions\r\n```\r\n\r\n---\r\n\r\n## Why Oscillink?\r\n\r\n### \ud83e\udde0 Universal Memory Layer\r\n- Works with **ANY** generative model (text, image, video, audio, 3D)\r\n- No retraining required \u2014 instant upgrade\r\n- Model-agnostic: future-proof your AI stack\r\n\r\n### \ud83c\udfaf Proven Hallucination Control \r\n- **42.9% \u2192 0%** hallucination rate in controlled studies\r\n- Deterministic, reproducible results\r\n- Signed receipts for audit trails\r\n\r\n### \u26a1 Production Ready\r\n- **10ms latency** at 1,200 node scale\r\n- Horizontal scaling to millions of documents\r\n- Battle-tested in legal, medical, and financial applications\r\n\r\n### \ud83d\udd2c Rigorous Foundation\r\n- Physics-based SPD (Symmetric Positive Definite) system\r\n- Mathematically guaranteed convergence\r\n- [Published research and whitepapers](OscillinkWhitepaper.tex)\r\n\r\n---\r\n\r\n## How It Works (Technical)\r\n\r\nOscillink minimizes a convex energy function over a mutual k-NN lattice:\r\n\r\n$\r\nH(U)=\\lambda_G\\|U-Y\\|_F^2+\\lambda_C\\,\\mathrm{tr}(U^\\top L_{\\mathrm{sym}}U)+\\lambda_Q\\,\\mathrm{tr}((U-\\mathbf{1}\\psi^\\top)^\\top B\\,(U-\\mathbf{1}\\psi^\\top))\r\n$\r\n\r\nThis creates a deterministic SPD system with guaranteed unique solution:\r\n- **No training required** \u2014 works instantly\r\n- **Mathematically proven** convergence\r\n- **Auditable** \u2014 every decision has a signed receipt\r\n\r\n[Learn more about the math \u2192](docs/MATH_OVERVIEW.md)\r\n\r\n## Install\r\n\r\n```bash\r\npip install oscillink\r\n```\r\n\r\n## 60\u2011second SDK quickstart\r\n\r\n```python\r\nimport numpy as np\r\nfrom oscillink import OscillinkLattice\r\n\r\nY = np.random.randn(120, 128).astype(np.float32)\r\npsi = (Y[:20].mean(0) / (np.linalg.norm(Y[:20].mean(0)) + 1e-12)).astype(np.float32)\r\n\r\nlat = OscillinkLattice(Y, kneighbors=6)\r\nlat.set_query(psi)\r\nlat.settle()\r\nprint(lat.bundle(k=5)) # Top\u2011k coherent items\r\nprint(lat.receipt()['deltaH_total']) # Energy drop for audit\r\n```\r\n\r\nWant more control? Compute diffusion gates and pass them to `set_query`:\r\n\r\n```python\r\nfrom oscillink import compute_diffusion_gates\r\ngates = compute_diffusion_gates(Y, psi, kneighbors=6, beta=1.0, gamma=0.15)\r\nlat.set_query(psi, gates=gates)\r\nlat.settle()\r\n```\r\n\r\n---\r\n\r\n## Run the server (operators)\r\n\r\nLocal (dev):\r\n\r\n- Python 3.11; install dev extras and start the API:\r\n\t- Install: `pip install -e .[dev]`\r\n\t- Start: `uvicorn cloud.app.main:app --port 8000`\r\n- For local development, disable HTTPS redirect: `OSCILLINK_FORCE_HTTPS=0`.\r\n- Optional: set `STRIPE_SECRET_KEY` (and `STRIPE_WEBHOOK_SECRET` if testing webhooks locally via Stripe CLI).\r\n\r\nDocker:\r\n\r\n- Build with the production Dockerfile: `docker build -t oscillink-cloud -f cloud/Dockerfile .`\r\n- Run: `docker run -p 8000:8080 -e PORT=8080 -e OSCILLINK_FORCE_HTTPS=0 oscillink-cloud`\r\n\r\nCloud Run (prod):\r\n\r\n- Use `cloud/Dockerfile`. Our container respects `PORT` and runs Gunicorn+Uvicorn as a non\u2011root user with a HEALTHCHECK.\r\n- Deploy with the environment variables in the checklist below (Stripe keys, price map, and optional Firestore collections). Set your custom domain as needed.\r\n- Grant the service account Firestore/Datastore User as noted.\r\n\r\n## Use the Cloud\r\n\r\nCall a hosted Oscillink with a simple HTTP POST. No infra required.\r\n\r\n### Plans\r\n\r\n- Free: 5M node\u00b7dim/month, community support\r\n- Beta Access ($19/mo): 25M units/month (hard cap), beta phase \u2014 limited support, cancel anytime\r\n- Enterprise: Unlimited, SLA, dedicated support (contact us)\r\n\r\n### Beta-only Stripe setup (Quickstart)\r\n\r\nFor the early beta (no public domain required):\r\n\r\n1) Subscribe: Use the hosted Stripe link for Beta Access ($19/mo): https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08\r\n\r\n2) Server env (operators):\r\n- `STRIPE_SECRET_KEY` \u2014 required\r\n- `OSCILLINK_STRIPE_PRICE_MAP=\"price_live_beta_id:beta\"` \u2014 map your live Beta price ID to `beta`\r\n- Optional for caps/portal: `OSCILLINK_MONTHLY_USAGE_COLLECTION`, `OSCILLINK_CUSTOMERS_COLLECTION`\r\n\r\nWindows quick-setup (local dev):\r\n\r\n- Run `scripts\\setup_billing_local.ps1` to be prompted for your Stripe secret, webhook secret (optional), and Beta price ID mapping. It will set the environment for the current PowerShell session and print a tip to start the server.\r\n\r\n3) Provisioning: Automated. On successful checkout, the server provisions your API key via the Stripe webhook. Alternatively, use the CLI flow (`oscillink signup --wait`) to receive the key instantly in your terminal.\r\n\r\n4) Test: Call `POST /v1/settle` with `X-API-Key` and verify results and headers (see examples below).\r\n\r\n### 1) Get an API key\r\n\r\n- Pay via the hosted Stripe link (no domain required):\r\n\t- Beta Access ($19/mo): https://buy.stripe.com/7sY9AUbcK1if2y6d2g2VG08\r\n\r\n- During early beta (no public domain yet):\r\n\t- Your API key is provisioned automatically via webhook. If you prefer the terminal experience, run `oscillink signup --wait` to get and store your key locally.\r\n\r\nNotes for operators:\r\n\r\n- Server must have `STRIPE_SECRET_KEY` set. Optional `OSCILLINK_STRIPE_PRICE_MAP` sets price\u2192tier mapping.\r\n- See docs/STRIPE_INTEGRATION.md for full details.\r\n- Success page is optional: webhook + CLI provisioning work without a public domain. You can enable a success page later by setting the Checkout `success_url` to `<API_BASE>/billing/success?session_id={CHECKOUT_SESSION_ID}`.\r\n- To enforce the beta hard cap (25M units/month), configure the monthly cap for the `beta` tier in your runtime settings; exceeding the cap returns 429 with `X-Monthly-*` headers.\r\n\r\nCloud Run + Firestore checklist (early beta):\r\n\r\n- Cloud Run service env:\r\n\t- `PORT` (Cloud Run injects 8080; our Dockerfile respects `PORT`)\r\n\t- `OSCILLINK_FORCE_HTTPS=1` (already default in Dockerfile)\r\n\t- `STRIPE_SECRET_KEY` and, if using webhooks, `STRIPE_WEBHOOK_SECRET`\r\n\t- `OSCILLINK_KEYSTORE_BACKEND=firestore` to enable Firestore keystore (optional; memory by default)\r\n\t- `OSCILLINK_CUSTOMERS_COLLECTION=oscillink_customers` to enable Billing Portal lookups (optional)\r\n\t- `OSCILLINK_MONTHLY_USAGE_COLLECTION=oscillink_monthly_usage` to persist monthly caps (optional)\r\n\t- `OSCILLINK_WEBHOOK_EVENTS_COLLECTION=oscillink_webhooks` to persist webhook idempotency (optional)\r\n\t- Set `OSCILLINK_STRIPE_PRICE_MAP` to include your live price ids \u2192 tiers (include `beta`).\r\n- Firestore (in same GCP project):\r\n\t- Enable Firestore in Native mode.\r\n\t- Service Account used by Cloud Run must have roles: Datastore User (or Firestore User). Minimal perms for collections above.\r\n\t- No required indexes for the default code paths (point lookups by document id).\r\n- Webhook endpoint: deploy a public URL and configure Stripe to call `POST /stripe/webhook` with the secret; this enables automatic key provisioning on checkout completion.\r\n\r\n### Automate API key provisioning after payment (optional)\r\n\r\nYou can automate key creation either via a success page redirect or purely by Stripe Webhooks (or both for redundancy):\r\n\r\n- Success URL flow (requires public domain):\r\n\t- Configure the Payment Link or Checkout Session `success_url` to `<API_BASE>/billing/success?session_id={CHECKOUT_SESSION_ID}` (set `<API_BASE>` to your deployed URL, e.g., your Cloud Run custom domain).\r\n\t- Server verifies the session with Stripe using `STRIPE_SECRET_KEY`, generates an API key, saves `api_key \u2192 (customer_id, subscription_id)` in Firestore if `OSCILLINK_CUSTOMERS_COLLECTION` is set, and returns a confirmation page (one\u2011time display).\r\n\t- Idempotency: gate on `session_id` and/or persist a provisioning record (e.g., in `OSCILLINK_WEBHOOK_EVENTS_COLLECTION`).\r\n\r\n- Webhook flow (works with or without success redirect):\r\n\t- Set `STRIPE_WEBHOOK_SECRET` and point Stripe to `POST /stripe/webhook`.\r\n\t- On `checkout.session.completed` (or `customer.subscription.created`), verify signature + timestamp freshness; reject stale events.\r\n\t- Ensure idempotency by recording processed `event.id` to `OSCILLINK_WEBHOOK_EVENTS_COLLECTION` (Firestore) before provisioning.\r\n\t- Generate an API key into your keystore (`OSCILLINK_KEYSTORE_BACKEND=firestore` recommended) and persist the customers mapping via `OSCILLINK_CUSTOMERS_COLLECTION`.\r\n\t- Optional: email the key using your transactional email provider or provide a \u201cretrieve key\u201d admin workflow.\r\n\r\nEnvironment recap for automation:\r\n\r\n- `STRIPE_SECRET_KEY` \u2014 required to verify sessions and manage subscriptions\r\n- `STRIPE_WEBHOOK_SECRET` \u2014 required for secure webhook handling\r\n- `OSCILLINK_CUSTOMERS_COLLECTION` \u2014 Firestore mapping: `api_key \u2192 {customer_id, subscription_id}`\r\n- `OSCILLINK_WEBHOOK_EVENTS_COLLECTION` \u2014 Firestore store for webhook idempotency\r\n- `OSCILLINK_KEYSTORE_BACKEND=firestore` \u2014 enable Firestore keystore (optional; memory by default)\r\n\r\n### Sign up and get your key in the terminal (CLI flow)\r\n\r\nIf you prefer to complete checkout in a browser but receive the key back in your terminal, use the built\u2011in CLI pairing flow. This works great in combination with the Stripe CLI during development and in production when webhooks are configured.\r\n\r\nOperator setup:\r\n\r\n- Server must have `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` set.\r\n- Ensure `OSCILLINK_STRIPE_PRICE_MAP` includes the desired tier (e.g., `beta`).\r\n\r\nUser steps (Windows PowerShell):\r\n\r\n1) Start a CLI session to get a short code and Checkout URL:\r\n\r\n```powershell\r\n$resp = Invoke-RestMethod -Method POST -Uri \"http://localhost:8000/billing/cli/start\" -ContentType \"application/json\" -Body '{\"tier\":\"beta\"}'\r\n$resp\r\n# { code = \"a1b2c3d4\"; checkout_url = \"https://checkout.stripe.com/...\"; expires_in = 900 }\r\n```\r\n\r\n2) Open the checkout_url in your browser and complete payment.\r\n\r\n3) Poll for your key (the server provisions it on the Stripe webhook and returns it here):\r\n\r\n```powershell\r\ndo {\r\n\tStart-Sleep -Seconds 2\r\n\t$poll = Invoke-RestMethod -Method GET -Uri \"http://localhost:8000/billing/cli/poll/$($resp.code)\"\r\n\t$poll\r\n} while ($poll.status -eq \"pending\")\r\n\r\nif ($poll.status -eq \"ready\") {\r\n\tWrite-Host \"Your API key:\" $poll.api_key\r\n}\r\n```\r\n\r\nNotes:\r\n\r\n- The Customer Portal is for managing/canceling subscriptions after signup. The CLI flow above is for initial signup and key delivery to the terminal.\r\n- CLI sessions expire after 15 minutes by default (`OSCILLINK_CLI_TTL`).\r\n- For production, keep `OSCILLINK_ALLOW_UNVERIFIED_STRIPE` off and ensure your webhook secret is set.\r\n\r\nDomain and API base:\r\n\r\n- Set `OSCILLINK_API_BASE` to your deployed API base (Cloud Run default URL or your custom domain). During beta, our hosted API is `https://api2.odinprotocol.dev`. All examples use this env var to avoid hardcoding domains.\r\n\r\nQuick CLI usage (packaged):\r\n\r\n```powershell\r\n# Install SDK (includes the CLI entrypoint)\r\npip install oscillink\r\n\r\n# Point to your cloud if different\r\n$env:OSCILLINK_API_BASE = \"https://<YOUR_API_BASE>\"\r\n\r\n# Start signup and wait for key\r\noscillink signup --tier beta --wait\r\n\r\n# Later, open the billing portal\r\noscillink portal\r\n```\r\n\r\n### 2) Call the API\r\n\r\nHeaders:\r\n\r\n- `X-API-Key: <your_key>`\r\n- `Content-Type: application/json`\r\n\r\nEndpoints (current versioned prefix is captured from settings; default `v1`):\r\n\r\n- `POST /v1/settle` \u2014 compute settle + optional receipt and bundle\r\n- `POST /v1/receipt` \u2014 compute receipt only\r\n- `POST /v1/bundle` \u2014 compute bundle only\r\n- `POST /v1/chain/receipt` \u2014 chain verdict for a path prior\r\n\r\nMinimal curl example:\r\n\r\n```bash\r\ncurl -X POST \"$OSCILLINK_API_BASE/v1/settle\" \\\r\n\t-H \"X-API-Key: $YOUR_API_KEY\" \\\r\n\t-H \"Content-Type: application/json\" \\\r\n\t-d '{\r\n\t\t\"Y\": [[0.1,0.2],[0.3,0.4],[0.5,0.6]],\r\n\t\t\"psi\": [0.1,0.2],\r\n\t\t\"params\": {\"kneighbors\": 2},\r\n\t\t\"options\": {\"bundle_k\": 2, \"include_receipt\": true}\r\n\t}'\r\n```\r\n\r\nPython client snippet:\r\n\r\n```python\r\nimport os, httpx\r\n\r\nAPI_BASE = os.environ.get(\"OSCILLINK_API_BASE\", \"http://localhost:8000\")\r\nAPI_KEY = os.environ[\"OSCILLINK_API_KEY\"]\r\n\r\npayload = {\r\n\t\"Y\": [[0.1,0.2],[0.3,0.4],[0.5,0.6]],\r\n\t\"psi\": [0.1,0.2],\r\n\t\"params\": {\"kneighbors\": 2},\r\n\t\"options\": {\"bundle_k\": 2, \"include_receipt\": True},\r\n}\r\n\r\nr = httpx.post(f\"{API_BASE}/v1/settle\", json=payload, headers={\"X-API-Key\": API_KEY})\r\nr.raise_for_status()\r\nprint(r.json())\r\n```\r\n\r\nResponse shape (abridged):\r\n\r\n- `state_sig: str` \u2014 checksum of lattice state for audit\r\n- `bundle: list[dict]` \u2014 top\u2011k results with scores\r\n- `receipt: dict` \u2014 energy breakdown (if requested)\r\n- `timings_ms: dict` \u2014 perf timings\r\n- `meta: dict` \u2014 quota/rate limit headers are returned as `X-Quota-*` (per\u2011key quotas), plus `X-RateLimit-*` (global) and `X-IPLimit-*` (per\u2011IP); monthly caps via `X-Monthly-*` when enabled\r\n\r\n### Quotas, limits, and headers\r\n\r\n- Global and per\u2011IP rate limits are enforced; exceeding returns 429 with headers indicating remaining and reset\r\n- Per\u2011key quotas (units consumed = N\u00d7D) and monthly caps by tier\r\n\t- Beta plan: hard cap at 25M units/month; exceeding returns 429\r\n- Headers you\u2019ll see:\r\n\t- Per\u2011key quota window: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`\r\n\t- Global rate limit: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`\r\n\t- Per\u2011IP rate limit: `X-IPLimit-Limit`, `X-IPLimit-Remaining`, `X-IPLimit-Reset`\r\n\t- Monthly caps (if enabled): `X-Monthly-Cap`, `X-Monthly-Used`, `X-Monthly-Remaining`, `X-Monthly-Period`\r\n\r\n### Optional: Redis for scale\r\n\r\nHorizontal scaling is supported via an optional Redis backend for distributed rate limits and webhook idempotency.\r\n\r\n- Set `OSCILLINK_STATE_BACKEND=redis` and `OSCILLINK_REDIS_URL=redis://...`\r\n- Details: docs/REDIS_BACKEND.md\r\n\r\n### Beta notice\r\n\r\n\u26a0\ufe0f Beta Notice: Cloud API is in beta. Expect occasional downtime, breaking changes with notice, and email\u2011only support. Hard usage caps enforced. Production use at your own risk.\r\n\r\n### Manage or cancel your subscription\r\n\r\nTwo ways to manage billing once you have an API key:\r\n\r\n- Self\u2011service billing portal (user):\r\n\t- Endpoint: `POST /billing/portal`\r\n\t- Auth: `X-API-Key: <your_key>`\r\n\t- Response: `{ \"url\": \"https://billing.stripe.com/...\" }` \u2014 open this URL in a browser to manage payment method, invoices, or cancel.\r\n\t- Requires server to have `STRIPE_SECRET_KEY` and a Firestore mapping collection set via `OSCILLINK_CUSTOMERS_COLLECTION` (the `/billing/success` flow persists `api_key \u2192 (stripe_customer_id, subscription_id)` for portal lookups). Optional `OSCILLINK_PORTAL_RETURN_URL` controls the post\u2011portal return URL.\r\n\r\n\tMinimal example:\r\n\t```bash\r\n\tcurl -X POST \"$OSCILLINK_API_BASE/billing/portal\" \\\r\n\t\t-H \"X-API-Key: $YOUR_API_KEY\"\r\n\t```\r\n\r\n- Admin cancel (operator):\r\n\t- Endpoint: `POST /admin/billing/cancel/{api_key}?immediate=true|false`\r\n\t- Auth: `X-Admin-Secret: <OSCILLINK_ADMIN_SECRET>`\r\n\t- Behavior: Cancels the Stripe subscription mapped to `api_key`. If `immediate=true` (or server env `OSCILLINK_STRIPE_CANCEL_IMMEDIATE=1`), the subscription is cancelled immediately; otherwise it cancels at period end. The API key is suspended right away.\r\n\t- Requires the same Firestore mapping collection (`OSCILLINK_CUSTOMERS_COLLECTION`) and `STRIPE_SECRET_KEY`.\r\n\r\n\tMinimal example:\r\n\t```bash\r\n\tcurl -X POST \"$OSCILLINK_API_BASE/admin/billing/cancel/$USER_API_KEY?immediate=false\" \\\r\n\t\t-H \"X-Admin-Secret: $OSCILLINK_ADMIN_SECRET\"\r\n\t```\r\n\r\nServer env summary for billing management:\r\n\r\n- `STRIPE_SECRET_KEY` \u2014 Stripe API key for server\u2011side operations\r\n- `OSCILLINK_CUSTOMERS_COLLECTION` \u2014 Firestore collection name used to persist `api_key \u2192 {stripe_customer_id, subscription_id}`\r\n- `OSCILLINK_PORTAL_RETURN_URL` \u2014 Optional return URL after the Stripe Billing Portal (default `https://oscillink.com`)\r\n- `OSCILLINK_ADMIN_SECRET` \u2014 Required for admin endpoints\r\n- `OSCILLINK_STRIPE_CANCEL_IMMEDIATE` \u2014 Optional default for admin cancel behavior (`1/true` for immediate)\r\n\r\n---\r\n\r\n## Performance (SDK reference)\r\n\r\n- Graph build: ~18 ms\r\n- Settle: ~10 ms\r\n- Receipt: ~3 ms\r\n\r\nTotal: < 40 ms for N\u22481200 on a laptop (Python 3.11, NumPy BLAS). Use `scripts/benchmark.py` for your hardware.\r\n\r\nScalability at a glance:\r\n\r\n- One matvec is O(Nk); total solve is approximately O(D \u00b7 cg_iters \u00b7 N \u00b7 k)\r\n- Typical CG iterations \u2248 3\u20134 at tol ~1e\u20113 with Jacobi (thanks to SPD)\r\n\r\nHallucination control (controlled study): trap rate reduced 0.33 \u2192 0.00 with F1 uplift (see whitepaper for setup details)\r\n\r\n## Docs & examples\r\n\r\n- SDK API: `docs/API.md`\r\n- Math overview: `docs/SPEC.md`\r\n- Receipts schema and examples: `docs/RECEIPTS.md`\r\n- Advanced cloud topics: `docs/CLOUD_ARCH_GCP.md`, `docs/CLOUD_ADVANCED_DIFFUSION_ENDPOINT.md`, `docs/FIRESTORE_USAGE_MODEL.md`, `docs/STRIPE_INTEGRATION.md`\r\n- Whitepaper: Oscillink \u2014 A Symmetric Positive Definite Lattice for Scalable Working Memory & Hallucination Control (`OscillinkWhitepaper.tex`)\r\n- Examples: `examples/quickstart.py`, `examples/diffusion_gated.py`\r\n- Notebooks: `notebooks/`\r\n\r\n## Security & compliance\r\n\r\n- Security policy: see [`SECURITY.md`](SECURITY.md)\r\n- Code of Conduct: see [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)\r\n- Webhooks: keep `OSCILLINK_ALLOW_UNVERIFIED_STRIPE` off in production and set `STRIPE_WEBHOOK_SECRET`; the server enforces signature verification and timestamp freshness by default.\r\n- Secrets: never commit `.env` files. Private env YAMLs under `cloud/` are git-ignored by default.\r\n\r\n## Support & branding\r\n\r\n- Contact: travisjohnson@oscillink.com\r\n- Branding: Oscillink is a brand of Odin Protocol Inc. (trademark filing for Oscillink planned). \r\n\r\n## Troubleshooting (Cloud)\r\n\r\n- 403 Unauthorized\r\n\t- Check the `X-API-Key` header is present and correct\r\n\t- If running your own server, ensure `OSCILLINK_API_KEYS` or the keystore contains your key\r\n\r\n- 429 Too Many Requests\r\n\t- You\u2019ve hit a quota or rate limit; inspect `X-Quota-*`, `X-RateLimit-*`, and `X-IPLimit-*` headers (and `X-Monthly-*` if caps are enabled) for remaining and reset\r\n\r\n- Success page didn\u2019t show a key after payment\r\n\t- Verify the Stripe payment link redirects to `/billing/success?session_id={CHECKOUT_SESSION_ID}`\r\n\t- Ensure the server has `STRIPE_SECRET_KEY` and price\u2192tier mapping configured; see `docs/STRIPE_INTEGRATION.md`\r\n\r\n- Redis not used despite being configured\r\n\t- Set `OSCILLINK_STATE_BACKEND=redis` and provide `OSCILLINK_REDIS_URL` (or `REDIS_URL`); see `docs/REDIS_BACKEND.md`\r\n\r\n## Contributing & License\r\n\r\n- Apache\u20112.0. See `LICENSE`\r\n- Issues and PRs welcome. See `CONTRIBUTING.md`\r\n\r\n## Changelog\r\n\r\nSee [`CHANGELOG.md`](CHANGELOG.md) for notable changes and release notes.\r\n\r\n## Release & PyPI publishing (maintainers)\r\n\r\nWe publish to PyPI via GitHub Actions using GitHub OIDC Trusted Publishing (no API tokens). The workflow is `.github/workflows/publish.yml` and publishes directly to PyPI on GitHub Release.\r\n\r\nOne\u2011time setup (already in progress):\r\n\r\n- In PyPI project settings \u2192 Publishing, add a GitHub Actions trusted publisher for `Maverick0351a/Oscillink` and `.github/workflows/publish.yml`. It will show as \"pending\" until the first publish runs.\r\n\r\nTrigger:\r\n\r\n- Publish a GitHub Release (for tag `vX.Y.Z`) \u2192 builds and uploads to PyPI\r\n\r\nRelease steps:\r\n\r\n1) Bump version in `pyproject.toml` under `[project] version = \"X.Y.Z\"` and commit.\r\n2) Create and push a tag `vX.Y.Z` (the Release will reference this tag). Example (PowerShell):\r\n\r\n```powershell\r\ngit tag v0.1.6\r\ngit push origin v0.1.6\r\n```\r\n\r\n3) Create a GitHub Release for the tag `vX.Y.Z` (via the GitHub UI). This publishes to PyPI.\r\n\r\nNotes:\r\n\r\n- The workflow builds with PEP 517 (`python -m build`) and publishes using `pypa/gh-action-pypi-publish@release/v1` via OIDC (`id-token: write`).\r\n- No repository secrets are required for publishing. If you want to fall back to token-based publishing, reintroduce Twine with `PYPI_API_TOKEN` and remove OIDC permissions.\r\n\r\n---\r\n\r\n\u00a9 2025 Odin Protocol Inc. (Oscillink brand)\r\n\r\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Oscillink Lattice \u2014 Short-Term Coherence SDK (physics-inspired memory for generative models)",
"version": "0.1.7",
"project_urls": null,
"split_keywords": [
"graph",
" lattice",
" memory",
" retrieval",
" ai",
" ml",
" coherence",
" physics-inspired"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fabc008f5fd03ba29024535f98fefb6936ca626360b5b0f034ecaa557fbacfad",
"md5": "85f6a15843500b0671e3fafd930148c8",
"sha256": "637c0a3309a42228e33c14f943de4daa1541c14a6abe30b72f041f314d0f7859"
},
"downloads": -1,
"filename": "oscillink-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85f6a15843500b0671e3fafd930148c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15820,
"upload_time": "2025-10-11T02:53:30",
"upload_time_iso_8601": "2025-10-11T02:53:30.702221Z",
"url": "https://files.pythonhosted.org/packages/fa/bc/008f5fd03ba29024535f98fefb6936ca626360b5b0f034ecaa557fbacfad/oscillink-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "622386427d8f35c8b07217b95a5e32d535bcc8536e6f77da952e5524de26cdea",
"md5": "bbb70845e16c1ce70bcabf6d807b3340",
"sha256": "b61f948f7121a5638b37ff97680363435d38682dffa8c257a9741e7281c80f38"
},
"downloads": -1,
"filename": "oscillink-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "bbb70845e16c1ce70bcabf6d807b3340",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 41942,
"upload_time": "2025-10-11T02:53:32",
"upload_time_iso_8601": "2025-10-11T02:53:32.392114Z",
"url": "https://files.pythonhosted.org/packages/62/23/86427d8f35c8b07217b95a5e32d535bcc8536e6f77da952e5524de26cdea/oscillink-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 02:53:32",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "oscillink"
}
JSON