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.

---

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

---

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 Transformers.

smart-http-request

• Minimal HTTP client with swappable adapters.
• Includes wrappers for fetch, Obsidian's requestUrl, and more.

smart-clusters

• Clusters vectorized items and computes centroids.
• Built atop SmartGroups for grouping semantics.

smart-view

• Renders dynamic settings/UI across various environments.
• SmartView with environment-specific adapters like SmartViewNodeAdapter or SmartViewObsidianAdapter.
• Offers standard setting types (dropdown, toggle, text, etc.) plus markdown rendering.

---

Key Concepts & Core Classes

• Adapters: Provide environment or provider-specific logic for data, models, or rendering.
• Collections & Items: Common pattern for storing entities in memory with persistent data adapters.
• SmartModel: The base for specialized AI models (chat, embed, rank).
• Integration: Modules can be combined for advanced use-cases (embedding + clustering, chat + templates, etc.).

---

Directory & File Structures

Common structure:

smart-xyz
├── adapters
│   └── ...
├── index.js
├── package.json
├── [library_name].js
└── test
		└── ...

---

Usage Flow & Adapters

1. Install relevant smart-* library.
2. Import classes and adapters.
3. Initialize a collection/model with chosen adapters.
4. Call main methods (init(), build_groups(), embed(), complete(), rank(), etc.).
5. Process the results or items as needed.

---

Testing & Scripts

• Uses AVA for unit tests (npx ava).
• Example: smart-sources/test/ajson_multi_file.test.js verifies multi-file storage.
• Some integration tests generate content (like test_content.js).

---

Additional Implementation Notes

• “env” object (SmartEnv) orchestrates references: env.smart_sources, env.smart_clusters, etc.
• The system heavily uses the adapter pattern.
• Some advanced features:
  • Median vectors or center embeddings in groups/clusters.
  • Function calling in chat models.