How adilshamim8/neurobridge works
1. Repository shape
- This is a multi-package product repo, not a single app. It contains a Python library, a Python FastAPI service, a JavaScript/TypeScript SDK, a marketing/docs website, a demo app, ML assets, and a test/benchmark suite.
- The architectural center is the Python neurobridge package, with the other surfaces wrapping or re-exposing its behavior.
2. Primary runtime boundary: the Python core library
- neurobridge/core is the main adaptation pipeline.
- The core flow is: input from an LLM or text source → profile selection/persistence → transform pipeline → format adaptation → adapted output.
- This is the boundary that turns raw model output into cognitive-accessibility-specific output.
3. Core subsystems inside the Python package
- bridge.py coordinates the end-to-end wrapper behavior.
- profile.py, quiz.py, and validators.py handle profile definitions, assessment, and input validation.
- transform.py and format_adapter.py are the main content-processing layers.
- memory.py stores user preference deltas and profile-related state across sessions.
- exceptions.py provides a shared error boundary for the package.
4. How data moves through the product
- The application supplies an LLM client or raw text.
- NeuroBridge determines a cognitive profile either from explicit selection, quiz results, or remembered preferences.
- Text is then rewritten by a sequence of transforms tailored to that profile.
- The transformed content is rendered through a format adapter for markdown, HTML, JSON, plain text, or TTS-oriented output.
5. Profile and memory layer
- The profile system is not just a static enum; it supports a quiz-driven profile selection flow and custom profiles.
- Memory is a separate concern from transformation: it tracks user edits and long-lived preferences so the system can adapt over time.
- The memory backend is abstracted, with SQLite as the default and Redis/custom backends supported by configuration.
6. LLM integration adapters
- neurobridge/integrations contains provider-specific wrappers for OpenAI, Anthropic, Hugging Face, and LangChain.
- These adapters exist to keep the core transform pipeline provider-agnostic while still fitting each ecosystem’s calling conventions.
- The important architectural boundary is that providers remain upstream data sources; NeuroBridge intercepts and adapts their outputs without owning the model inference path.
7. REST API server as a language-agnostic entry point
- neurobridge/server exposes the core capabilities over FastAPI.
- Routers split the API by concern: adapt, quiz, profiles, and health.
- This service is the integration boundary for non-Python clients and for deployments that want a centralized adaptation layer.
8. ML-based detection subsystem
- neurobridge/ml is a separate subsystem for profile detection/training, with feature extraction, training, tracking, and detector code.
- The presence of model.pkl indicates a prebuilt model artifact used at runtime, while trainer.py and generator.py support offline model generation.
- This ML path complements the quiz/manual profile flow and feeds the same profile-selection boundary.
9. JavaScript/TypeScript SDK
- packages/neurobridge-js mirrors the product concept for JS consumers.
- It includes bridge logic, integrations, memory abstractions, and transform utilities similar to the Python stack, but packaged for Node/browser environments.
- This is a separate distribution boundary, useful when the host app is JavaScript-native and does not want Python in-process.
10. Website and API routes
- website is a Next.js application that serves docs, marketing pages, playgrounds, stats, and user-facing flows like quiz, shared outputs, and newsletter signup.
- Its API routes handle product-adjacent concerns such as adapt requests, feedback, GitHub stars, stats, newsletter subscription, and Open Graph generation.
- These routes are distinct from the core NeuroBridge API server; they support the public site and community funnel rather than the library itself.
11. Demo, examples, and benchmarks
- demo is a small interactive showcase app, likely used to demonstrate transformations on sample “before/after” text.
- examples provides integration-oriented usage snippets for Python consumers.
- benchmarks measures API, pipeline, memory, and transform performance, indicating the main nonfunctional concern is transform latency overhead on LLM output.
12. Test and quality architecture
- The tests are broad and subsystem-aligned: core bridge, memory, transforms, profiles, quiz, server APIs, integrations, streaming, ML, and performance.
- tests/cassettes suggests VCR-style recorded integration tests for external provider calls.
- CI workflows plus release docs indicate a strong gated release process around correctness, compatibility, and packaging.
13. External dependencies that shape the architecture
- The core product depends on third-party LLM providers and optional backends like Redis.
- The server side uses FastAPI; the website uses Next.js/Vercel-style deployment; the JS SDK is built with a bundler for npm distribution.
- These aren’t incidental—they define the main system boundaries: library, API service, frontend site, and SDK distributions.
14. Overall diagram takeaway
- The central diagram should show a shared “adaptation engine” in the Python core, fed by LLM outputs or raw text, with profile selection/memory/ML influencing transforms and formatting.
- Around that core are three major access paths: in-process Python integration, REST API server, and JS SDK.
- The website, demo, and docs sit outside the core product path as presentation and onboarding surfaces, while tests/benchmarks validate the behavior of every subsystem.
Main entry points: bridge.py Bridge · tests Tests · routers API routes · profile.py Profiles
Components 23
Python core
Primary adaptation engine and shared runtime boundary.
- Bridge · Coordinates end-to-end adaptation flow from input to output.
neurobridge/core/bridge.py - Profiles · Defines cognitive profiles and custom profile selection rules.
neurobridge/core/profile.py - Quiz · Collects answers to infer or refine the best-fit profile.
neurobridge/core/quiz.py - Validators · Validates inputs and guards the core boundary.
neurobridge/core/validators.py - Memory · Persists user preference deltas and profile-related state across sessions.
neurobridge/core/memory.py - Transforms · Applies profile-specific content rewrites and normalization steps.
neurobridge/core/transform.py - Format adapter · Converts adapted content into markdown, HTML, JSON, plain text, or TTS-oriented output.
neurobridge/core/format_adapter.py - Errors · Shared exception types for package-wide failure handling.
neurobridge/exceptions.py
Python surfaces
Entry points that expose the core library to users and applications.
- LLM adapters · Provider-specific wrappers that keep the core pipeline upstream-provider agnostic.
neurobridge/integrations - FastAPI server · Language-agnostic REST entry point for adaptation, quiz, profiles, and health.
neurobridge/server/app.py - API routes · Splits the service into adapt, quiz, profiles, and health routers.
neurobridge/server/routers - Detector · Uses the runtime model to infer profiles from text features.
neurobridge/ml/detector.py - Trainer · Builds and updates the profile detection model from synthetic or tracked data.
neurobridge/ml/trainer.py - Model artifact · Prebuilt model artifact used by the detection path at runtime.
neurobridge/ml/model.pkl
JS SDK
TypeScript distribution for Node and browser consumers.
- JS bridge · TypeScript bridge that mirrors the Python adaptation flow for JS consumers.
packages/neurobridge-js/src/bridge.ts - JS adapters · Provider wrappers for OpenAI, Anthropic, and Vercel AI ecosystems.
packages/neurobridge-js/src/integrations - JS memory · Browser and Node memory abstractions for persisting preferences.
packages/neurobridge-js/src/memory - JS transforms · TypeScript transformation utilities that mirror the core rewrite stages.
packages/neurobridge-js/src/transform
Website and demo
Public site, docs, and showcase surfaces around the product.
- Website app · Docs, marketing pages, playgrounds, quiz, shared outputs, and stats views.
website/app - Site API · Public-site endpoints for adapt, feedback, stars, stats, newsletter, quiz, and OG generation.
website/app/api - Demo app · Interactive example app for before-and-after transformation demos.
demo/app.py
Quality and validation
Benchmarks and tests that validate the core behavior and integrations.
- Benchmarks · Measures API, pipeline, memory, and transform performance.
benchmarks - Tests · Covers core behavior, integrations, server APIs, ML, streaming, and performance.
tests
Connections 32
- Bridge → Validators: validates · Checks incoming text, requests, and configuration before adaptation.
- Bridge → Profiles: selects · Chooses an explicit, quiz-derived, remembered, or detected profile.
- Bridge → Memory: reads/writes · Loads remembered preferences and persists preference deltas.
- Bridge → Transforms: applies · Runs the profile-specific rewrite pipeline over the content.
- Bridge → Format adapter: renders · Exports the adapted result in the requested output format.
- Quiz → Profiles: infers · Maps assessment responses to a usable profile selection.
- Memory → Profiles: biases · Long-lived preferences influence future profile choice.
- Transforms → Format adapter: passes to · Hands structured adapted content to the final renderer.
- Errors → Bridge: shared by · Provides common error types for the core orchestration layer.
- LLM adapters → Bridge: feeds input · Wraps provider outputs and sends them into the adaptation pipeline.
- LLM adapters → Validators: adapts · Normalizes provider-specific payloads before core validation.
- FastAPI server → API routes: mounts · Composes the REST service from concern-specific routers.
- API routes → Bridge: calls · Exposes core adaptation through the API boundary.
- API routes → Quiz: calls · Supports quiz-driven profile selection over HTTP.
- API routes → Profiles: calls · Serves profile inspection and selection endpoints.
- API routes → Detector: calls · Uses ML inference when profile detection is enabled.
- Detector → Model artifact: loads · Reads the prebuilt classifier artifact for runtime detection.
- Trainer → Model artifact: produces · Creates or refreshes the detector artifact offline.
- Trainer → Profiles: trains for · Optimizes detection around the same profile boundary used by the core.
- JS bridge → JS transforms: applies · Runs the JS-side adaptation steps over input text.
- JS bridge → JS memory: reads/writes · Persists browser or Node preferences for future sessions.
- JS bridge → JS adapters: wraps · Integrates with provider SDKs while keeping the product flow consistent.
- Website app → Site API: uses · Frontend pages call site-specific API endpoints for quiz, stats, and sharing.
- Site API → Bridge: adapts via · Public-site adapt endpoints delegate to the core engine.
- Demo app → Bridge: demonstrates · Showcases the adaptation flow on sample before/after content.
- Benchmarks → Bridge: measures · Profiles the end-to-end pipeline latency and overhead.
- Benchmarks → Memory: measures · Tracks persistence and lookup costs of the memory layer.
- Tests → Bridge: verifies · Covers the core orchestration and rewrite behavior.
- Tests → FastAPI server: verifies · Exercises the REST API contract and service behavior.
- Tests → LLM adapters: verifies · Uses recorded provider interactions for integration coverage.
- Tests → Detector: verifies · Checks inference and feature extraction behavior.
- Tests → JS bridge: verifies · Covers the SDK surface and distribution behavior.