JS Brains

JS Brains is a collection of lightweight modules for building intelligent applications with JavaScript. It's designed to empower developers to easily integrate AI capabilities into their projects, with a focus on minimal dependencies, extendability, and security.

---

Top-Level Overview

• smart-environment/
  Manages global runtime configuration, settings loading/saving, and provides a context to integrate collections, file systems, and model adapters.

• smart-collections/
  Generalized collection framework for persisting items (sources, blocks, messages) using JSON, AJSON, or SQLite, offering CRUD, filtering, and batch processing utilities.

  • smart-entities/
    Adds embeddings, semantic searches, and nearest-neighbor lookups for items within collections, enhancing entities with vector-based intelligence.
    • smart-sources/ Handles structured documents (sources) and their embedded blocks, integrating with embeddings and semantic lookups.
    • smart-blocks/ Manages block-level granularity within sources, representing distinct sections or pieces of content for targeted embedding, search, and tool integration.

• smart-model/
  Base classes for model abstractions and adapter management, setting a pattern for uniform access to various AI model types.

  • smart-chat-model/
    Provides a unified API for chat-completion models (OpenAI, Anthropic, Cohere), handling streaming responses, function calling, and multi-provider fallback.
  • smart-embed-model/
    Offers a uniform interface to embedding models (OpenAI, Transformers, Ollama), allowing generation of vector embeddings and efficient semantic searches.
  • smart-rank-model/
    Specializes in ranking documents using LLM-based rerankers (Cohere, local Transformer models), enabling sorting of candidate answers or documents by relevance.

• smart-fs/ Abstracts file system operations through multiple adapters (Node.js FS, Obsidian Vault, Web File System Access), adding support for ignore patterns, AJSON, and other features.

• smart-actions/ Registers and executes reusable actions, enabling automation workflows and command dispatching across modules.

• smart-contexts/ Builds and merges context templates for prompts or configuration generation, supporting variable interpolation and adapters.

• smart-settings/ Persists user-facing configuration with schema-driven forms and hot-reload support.

• smart-view/ Handles UI and rendering tasks for settings interfaces, markdown previewing, and icon sets, with adapters tailored to Node.js, Obsidian, or browser environments.

• smart-events/ Event bus coordinating module communication.

• smart-settings/ Centralized configuration accessible across modules.

• smart-groups/ Organizes items into labeled groups with vector-based summaries.

• smart-directories/ Generates directory structures from collections and sources.

• smart-notices/ Delivers predefined notices through adapters to the DOM.

---

Vision and Mission

Our mission is to democratize AI development for JavaScript developers, providing a robust toolkit that simplifies the creation of smart, AI-powered applications while maintaining high standards of performance and security. We aim to:

• Lower the barrier to entry for AI integration in web applications
• Promote best practices in AI development and deployment
• Foster a community of developers building intelligent, scalable applications
• Empower individuals with AI tools that respect their privacy and enhance productivity

Core Principles

• Minimal Dependencies: Designed to be lightweight and secure, reducing potential vulnerabilities and simplifying integration.
• Web-Native: Optimized for performance in web environments, ensuring smooth operation across various platforms.
• Extendable: Flexible architecture allowing for custom solutions and easy integration of new AI models or services.
• Developer-Friendly: Simplifies AI integration for developers of all skill levels, with clear documentation and intuitive APIs.
• Security-Focused: Minimizes vulnerabilities through careful dependency management and secure coding practices.
• User-Aligned: Prioritizes user privacy and control, ensuring that AI tools serve the user's best interests.

---

Comprehensive Documentation

Below is a condensed but comprehensive reference to these libraries, detailing directory structures, classes, and usage patterns.

Contents

• Overview & Intent

• Module Summaries

  • smart-environment
  • smart-collections
  • smart-entities
  • smart-sources
  • smart-blocks
  • smart-actions
  • smart-contexts
  • smart-settings
  • smart-fs
  • smart-groups
  • smart-directories
  • smart-model
  • smart-embed-model
  • smart-chat-model
  • smart-rank-model
  • smart-http-request
  • smart-clusters
  • smart-view

• Key Concepts & Core Classes

• Directory & File Structures

• Usage Flow & Adapters

• Testing & Scripts

• Additional Implementation Notes

• Design Patterns

  • Adapter Pattern
  • Collection Pattern

• High-Level Flow

• Use Cases: Smart Connections

• Our Mission: Empowering Individuals with AI

---

Overview & Intent

The "smart-*" set of libraries in JS Brains comprise a modular ecosystem for:

• Managing entities, sources, blocks, directories, clusters, and templates.
• Integrating with AI models (embeddings, chat completions, ranking).
• Handling HTTP requests and rendering views or settings in multiple environments.

---

Module Summaries

smart-environment

• Coordinates configuration and lifecycle for all modules.
• Exposes a shared context where collections, file systems, and models register.

smart-collections

• Generic collection framework with CRUD, filtering, and adapter-backed load/save queues.
• Collection and CollectionItem form the base for higher-level collections.

smart-entities

• Extends collections with embeddings and semantic search utilities.
• Supports nearest-neighbor lookups and vector-based comparisons.

smart-sources

• Manages structured documents and their metadata.
• Integrates with embeddings to link sources with relevant entities.

smart-blocks

• Tracks block-level segments inside sources.
• Enables targeted embedding, search, and tool integration per block.

smart-actions

• Registers commands and automation actions.
• Dispatches actions across modules via a lightweight registry.

smart-contexts

• Builds prompt and config templates with variable interpolation.
• Merges contexts from multiple sources or scopes.

smart-settings

• Persists user-visible settings with schema-driven forms.
• Supports hot reloading when configuration changes.

smart-fs

• Abstract file-system layer with pluggable adapters (Node, Obsidian, Web).
• Adds ignore patterns, AJSON helpers, and cache utilities.

smart-groups

• Groups items like sources or files.
• SmartGroups manages multiple SmartGroup instances and supports batch updates and labeling.

smart-directories

• Manages embedded directory trees using SmartGroups primitives.
• Tracks parent relationships and directory statistics.

smart-model

• Base class for AI model abstractions.
• Handles adapter lifecycle, settings config, and state transitions for specialized models.

smart-embed-model

• Embedding-focused model built on SmartModel.
• Provides embed() and embed_batch() to produce vectors via local or remote adapters.

smart-chat-model

• Unified chat-completion API across providers.
• Normalizes requests/responses and supports streaming, tools, and function calling.

smart-rank-model

• Reranks documents or answers by relevance.
• Extends SmartModel with rank(query, documents) and adapters for Cohere or Transf