arcadedb 0.5.0 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d7f1f29472b0fb31734654c9456ec5bdfb31cd42fd46b658139ac840691c6f6
-  data.tar.gz: 4c1c95707c8e2c528654f2a7509b1b6943ef9615fe203c81cd421d52636dcac7
+  metadata.gz: 110182caec09f3fc4bf3ae6cb1980e6ba46f86818aa5d35d2c6f933af0516ea3
+  data.tar.gz: af268bcc336188268d48ed65c651ec3fba2c0d67a9de0cfdbe1fc1b6cad3010d
 SHA512:
-  metadata.gz: f54746f04760ebfbc8c1588e66fb0bb52e820eef83df564e3563e37219835ff86c93e5b3d2e2a7617452218938c30a5aabff099361d0fd829890e2ac83411fc8
-  data.tar.gz: 0f8bf3623302c5204ca56552fb41694bfd506c493dc72463b8000e66c82aacddb7f42188f41508c84e9fc5bf93fa78e42e4235ed904982b97d38a4a5c8d4ff40
+  metadata.gz: '052078657583b093639c2a8f10764d11d8f1ad331cf128bc1999b420969e86f573a5af8aa3d26b6988969eea287ba64f6f658e8d361f491a5484a1643c26c7eb'
+  data.tar.gz: 8b42dadea114563262cdf3e803a48f5d0b0af56e5f033b0dfa3af01bf04994af670bc6acdd1860a3a199b51c7ceabeb8d0d734a88fd72243f8e8bc7ffdb3ea38

data/.gitignore

@@ -55,3 +55,6 @@ build-iPhoneSimulator/
 
 # Used by RuboCop. Remote config files pulled in from inherit_from directive.
 # .rubocop-https?--*
+
+.qwen/
+QWEN.md

data/CHANGELOG.md

@@ -31,3 +31,34 @@ All notable changes to this project will be documented in this file.
 - Arcade::Match simple match-statement generator
 - return to Arcade::QueryError messages instead of HTTPX::HTTPError
 - The ProjectRoot Const is used to read configuration files (Changed from Arcade::ProjectRoot)
+
+## 0.5.1 - 2024-1-16
+- Included Arcade::RevisionRecord and Arcade::Revision model classes
+- Both provide basic support for audit proofed bookings
+## 0.5.2 - 2025-02-11
+- Include method Object#descendants (part of active-support)
+- Separate Dry::Type definitions to /lib/types.rb
+- added Vertex#coe (count of edeges) as service method for to_human
+- updated Match#inE, #outE methods to facilitate queries on properties on edges
+##       - 2025-03-15
+- support of Match.new vertex: {a prefetched Arcade::Vertex} and match.node( vertex: ...) 
+##       - 2025-03-25
+- support of Vertex.match( where conditions [, as: :return_element] )
+- added Vertex#match to build  'MATCH type: {class} rid: {rid}'
+
+
+## 0.5.3 - 2026-04-02
+- support for RAG
+- RAG modus is invoked through "rag_db_init"  in the model file
+
+## 0.5.4 - 2026-10-20
+- Arcade::Timeseries — model class for native time-series types
+  - schema DSL: timestamp (precision-aware) / tags / fields → CREATE TIMESERIES TYPE
+  - write / write_many via InfluxDB Line Protocol (new Api.post_text)
+  - range, bucket (ts.timeBucket + ts.last aggregates), latest (Api.get_json / post_json)
+  - create_type waits for asynchronous type registration
+- README rebuilt for machine-readable consumption; server-quirk table added
+  (schema:types blind to TS types, DELETE reports but does not delete TS rows on 26.10.1,
+   ns timestamp default, reserved word `bucket`)
+- spec/lib/timeseries_spec.rb (5 examples)
+

data/Gemfile

@@ -4,7 +4,6 @@ source "https://rubygems.org"
 
 #git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 gemspec
-gem 'sdoc'
 group :development, :test do
 	gem "awesome_print"
   gem 'pastel'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    arcadedb (0.4.1)
+    arcadedb (0.5.2)
       dry-configurable
       dry-core
       dry-schema
@@ -12,47 +12,53 @@ GEM
   remote: https://rubygems.org/
   specs:
     awesome_print (1.9.2)
+    bigdecimal (4.1.0)
     coderay (1.1.3)
-    concurrent-ruby (1.2.2)
-    diff-lcs (1.5.0)
-    dry-configurable (1.1.0)
-      dry-core (~> 1.0, < 2)
+    concurrent-ruby (1.3.6)
+    diff-lcs (1.6.2)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    dry-core (1.0.1)
+    dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
+      logger
       zeitwerk (~> 2.6)
-    dry-inflector (1.0.0)
-    dry-initializer (3.1.1)
-    dry-logic (1.5.0)
+    dry-inflector (1.3.1)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
       concurrent-ruby (~> 1.0)
-      dry-core (~> 1.0, < 2)
+      dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    dry-schema (1.13.3)
+    dry-schema (1.16.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 1.0, >= 1.0.1)
-      dry-core (~> 1.0, < 2)
-      dry-initializer (~> 3.0)
-      dry-logic (>= 1.4, < 2)
-      dry-types (>= 1.7, < 2)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.9, >= 1.9.1)
       zeitwerk (~> 2.6)
-    dry-struct (1.6.0)
-      dry-core (~> 1.0, < 2)
-      dry-types (>= 1.7, < 2)
+    dry-struct (1.8.1)
+      dry-core (~> 1.1)
+      dry-types (~> 1.8, >= 1.8.2)
       ice_nine (~> 0.11)
       zeitwerk (~> 2.6)
-    dry-types (1.7.1)
+    dry-types (1.9.1)
+      bigdecimal (>= 3.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0)
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
-    ffi (1.16.3)
-    formatador (1.1.0)
+    ffi (1.17.4-x86_64-linux-gnu)
+    formatador (1.2.3)
+      reline
     given_core (3.8.2)
       sorcerer (>= 0.3.7)
-    guard (2.18.1)
+    guard (2.20.1)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
+      logger (~> 1.6)
       lumberjack (>= 1.0.12, < 2.0)
       nenv (~> 0.1)
       notiffany (~> 0.0)
@@ -64,67 +70,68 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    http-2-next (1.0.1)
-    httpx (1.1.0)
-      http-2-next (>= 1.0.1)
+    http-2 (1.1.3)
+    httpx (1.7.5)
+      http-2 (>= 1.1.3)
     ice_nine (0.11.2)
-    listen (3.8.0)
+    io-console (0.8.2)
+    listen (3.10.0)
+      logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
-    lumberjack (1.2.9)
-    method_source (1.0.0)
+    logger (1.7.0)
+    lumberjack (1.4.2)
+    method_source (1.1.0)
     nenv (0.3.0)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
     pastel (0.8.0)
       tty-color (~> 0.5)
-    pry (0.14.2)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    psych (5.1.1.1)
-      stringio
-    rake (13.0.6)
+      reline (>= 0.6.0)
+    rake (13.3.1)
     rb-fsevent (0.11.2)
-    rb-inotify (0.10.1)
+    rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rdoc (6.5.0)
-      psych (>= 4.0.0)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
     rspec-collection_matchers (1.2.1)
       rspec-expectations (>= 2.99.0.beta1)
     rspec-context-private (0.0.1)
-    rspec-core (3.12.2)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.3)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
+      rspec-support (~> 3.13.0)
     rspec-given (3.8.2)
       given_core (= 3.8.2)
       rspec (>= 2.14.0)
-    rspec-its (1.3.0)
-      rspec-core (>= 3.0.0)
-      rspec-expectations (>= 3.0.0)
+    rspec-its (2.0.0)
+      rspec-core (>= 3.13.0)
+      rspec-expectations (>= 3.13.0)
     rspec-legacy_formatters (1.0.2)
       rspec (~> 3.0)
-    rspec-mocks (3.12.6)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.1)
-    sdoc (2.6.1)
-      rdoc (>= 5.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
     shellany (0.0.1)
     sorcerer (2.0.1)
-    stringio (3.0.8)
-    terminal-table (3.0.2)
-      unicode-display_width (>= 1.1.1, < 3)
-    thor (1.3.0)
+    terminal-table (4.0.0)
+      unicode-display_width (>= 1.1.1, < 4)
+    thor (1.5.0)
     tty-color (0.6.0)
-    unicode-display_width (2.5.0)
-    zeitwerk (2.6.12)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    zeitwerk (2.7.5)
 
 PLATFORMS
   x86_64-linux
@@ -144,7 +151,6 @@ DEPENDENCIES
   rspec-given
   rspec-its
   rspec-legacy_formatters
-  sdoc
   terminal-table
   zeitwerk
 

data/RAG_SCHEMA.md

@@ -0,0 +1,239 @@
+# RAG Schema Module
+
+A module to implement a RAG (Retrieval-Augmented Generation) compatible database schema for ArcadeDB.
+
+## Overview
+
+The `Arcade::Ragschema` module provides a default-index configuration optimized for:
+- **Vector similarity search** (semantic embeddings)
+- **Metadata filtering**
+
+## Installation
+
+The module is included in the gem and automatically available when you require `arcade`.
+
+## Usage
+
+### Basic Setup
+
+```ruby
+require 'arcade'
+
+module MyApp
+  class Document < Arcade::Vertex
+    include Arcade::Ragschema
+
+    attribute :content, Types::String
+    attribute :embedding?, Types::Array.of(Types::Float).optional
+    attribute :metadata?, Types::Hash.optional
+  end
+end
+
+# Create the database type with RAG indexes
+MyApp::Document.create_type
+```
+
+### Custom Schema Configuration
+
+```ruby
+module MyApp
+  class Document < Arcade::Vertex
+    include Arcade::Ragschema
+
+    attribute :content, Types::String
+    attribute :embedding?, Types::Array.of(Types::Float).optional
+    attribute :title?, Types::String.optional
+    attribute :metadata?, Types::Hash.optional
+
+    def self.db_init
+      # Custom schema with 768-dimensional embeddings
+      rag_db_init(vector_dimension: 768)
+    end
+  end
+end
+```
+
+### Inserting Documents with Embeddings
+
+```ruby
+# Generate embedding using your preferred service (OpenAI, HuggingFace, etc.)
+embedding = generate_embedding("Your text content here")
+
+doc = MyApp::Document.create(
+  content: "The content of your document",
+  embedding: embedding,
+  metadata: {
+    author: "John Doe",
+    tags: ["ruby", "database"],
+    category: "technical"
+  },
+  source_url: "https://example.com/document",
+  created_at: DateTime.now
+)
+```
+
+### Vector Similarity Search
+
+Perform semantic search using vector embeddings:
+
+```ruby
+# Generate embedding for the query
+query_embedding = generate_embedding("What is a graph database?")
+
+# Search for similar documents
+results = MyApp::Document.vector_search(
+  query_embedding,
+  limit: 10,        # Maximum number of results
+  threshold: 0.7    # Minimum similarity score (0.0 to 1.0)
+)
+
+results.each do |doc|
+  puts "#{doc[:content]} (similarity: #{doc[:similarity]})"
+end
+```
+
+### Hybrid Search
+
+Combine vector similarity with SQL LIKE text filtering:
+
+```ruby
+query_embedding = generate_embedding("graph database")
+
+results = MyApp::Document.hybrid_search(
+  query_embedding,
+  "Ruby programming",  # SQL LIKE search term
+  limit: 10,
+  vector_threshold: 0.7
+)
+```
+
+### Instance Method
+
+You can also call `vector_search` on an instance (delegates to class method):
+
+```ruby
+doc = MyApp::Document.first
+results = doc.vector_search(query_embedding, limit: 5)
+```
+
+## Schema Details
+
+The RAG schema creates the following properties and indexes:
+
+### Properties
+- `embedding` - ARRAY_OF_FLOATS type for vector storage
+- `content` - STRING for full document content
+- `metadata` - MAP for flexible metadata
+- `source_url` - STRING for source tracking
+- `created_at` - DATETIME for timestamp
+
+### Indexes
+- **LSM_VECTOR** index on `embedding` for similarity search with COSINE similarity
+- **LSM_TREE** index on `metadata` for filtering
+
+## Configuration Options
+
+### `rag_db_init` Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `vector_dimension` | 1536 | Dimension of vector embeddings (OpenAI default) |
+
+### `vector_search` Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `limit` | 10 | Maximum number of results to return |
+| `threshold` | 0.7 | Minimum similarity score (0.0-1.0) |
+
+### `hybrid_search` Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `limit` | 10 | Maximum number of results |
+| `vector_threshold` | 0.7 | Minimum vector similarity score |
+
+## API Reference
+
+### `rag_schema(vector_dimension:)`
+
+Returns the SQL commands for creating RAG indexes.
+
+```ruby
+schema = MyApp::Document.rag_schema(vector_dimension: 768)
+# => "CREATE INDEX ON my_document (embedding) LSM_VECTOR METADATA {dimensions: 768, similarity: 'COSINE'}\n..."
+```
+
+### `rag_db_init(vector_dimension:)`
+
+Returns the SQL commands for creating properties and indexes. This is typically called from `db_init`.
+
+```ruby
+sql = MyApp::Document.rag_db_init(vector_dimension: 768)
+```
+
+### `.vector_search(query_embedding, limit:, threshold:)`
+
+Perform vector similarity search across all documents. Returns metadata only (not embedding vectors) for efficiency.
+
+```ruby
+results = MyApp::Document.vector_search(query_embedding, limit: 10, threshold: 0.7)
+# Returns: Array of Hashes with :title, :content, :category, :similarity, etc.
+```
+
+### `.hybrid_search(query_embedding, text_query, limit:, vector_threshold:)`
+
+Perform hybrid search combining vector similarity with SQL LIKE text filtering.
+
+```ruby
+results = MyApp::Document.hybrid_search(query_embedding, "search terms", limit: 10, vector_threshold: 0.7)
+```
+
+### `#vector_search(query_embedding, limit:, threshold:)`
+
+Instance method that delegates to the class method.
+
+```ruby
+doc = MyApp::Document.first
+results = doc.vector_search(query_embedding, limit: 5)
+```
+
+## Limitations
+
+### Full-Text Search
+
+**Full-text search is not yet implemented.** The `FULLTEXT` index type is not supported in the current ArcadeDB server version. 
+
+For text filtering, use the `hybrid_search` method which uses SQL `LIKE` pattern matching instead:
+
+```ruby
+# Instead of full-text search, use LIKE-based filtering
+results = MyApp::Document.hybrid_search(
+  query_embedding,
+  "search term",  # Uses: content LIKE '%search term%'
+  limit: 10
+)
+```
+
+Future versions may add support for:
+- Apache Lucene-based full-text indexes
+- Tokenization and stemming
+- Relevance scoring
+
+## Example
+
+See `examples/rag_usecase_demo.rb` for a complete working example.
+
+## Requirements
+
+- ArcadeDB server with vector search support (version 23.12+)
+- External embedding service (OpenAI, HuggingFace, etc.) for generating embeddings
+
+## Testing
+
+Run the RAG schema tests:
+
+```bash
+bundle exec rspec spec/lib/rag_schema_spec.rb
+bundle exec rspec spec/lib/usecase/rag_integration_spec.rb
+```