dexkit 0.9.0 → 0.11.0

data/guides/llm/QUERY.md

@@ -10,12 +10,17 @@ All examples below build on this query unless noted otherwise:
 
 ```ruby
 class UserSearch < Dex::Query
+  description "Search and filter users"
+
   scope { User.all }
 
   prop? :name,   String
   prop? :role,   _Array(String)
   prop? :age_min, Integer
   prop? :status, String
+  prop? :tenant, String
+
+  context tenant: :current_tenant
 
   filter :name,    :contains
   filter :role,    :in
@@ -71,6 +76,51 @@ prop? :age_min, Integer              # optional integer
 
 Reserved prop names: `scope`, `sort`, `resolve`, `call`, `from_params`, `to_params`, `param_key`.
 
+### Description
+
+```ruby
+class UserSearch < Dex::Query
+  description "Search and filter users"
+end
+```
+
+### Context
+
+Same `context` DSL as Operation and Event. Auto-fills props from `Dex.with_context`:
+
+```ruby
+class UserSearch < Dex::Query
+  prop? :tenant, String
+  context tenant: :current_tenant
+end
+
+# In a controller around_action:
+Dex.with_context(current_tenant: current_tenant) do
+  UserSearch.call(name: "ali")  # tenant auto-filled
+end
+```
+
+Identity shorthand: `context :locale` maps prop `:locale` to context key `:locale`.
+
+Explicit values always win over ambient context. Inheritance merges parent + child mappings.
+
+---
+
+## Registry & Export
+
+Queries extend `Registry` — same API as Operation, Event, and Form:
+
+```ruby
+Dex::Query.registry                     # => Set of all named Query subclasses
+UserSearch.description                   # => "Search and filter users"
+
+UserSearch.to_h                          # => { name:, description:, props:, filters:, sorts:, context: }
+UserSearch.to_json_schema                # => JSON Schema (Draft 2020-12)
+
+Dex::Query.export(format: :hash)         # => sorted array of all query to_h
+Dex::Query.export(format: :json_schema)  # => sorted array of all query to_json_schema
+```
+
 ---
 
 ## Filters
@@ -346,3 +396,9 @@ class UserSearchTest < Minitest::Test
   end
 end
 ```
+
+---
+
+## LLM Tools
+
+To expose a query as an LLM-callable tool, see `TOOL.md`.

data/guides/llm/TOOL.md

@@ -0,0 +1,308 @@
+# Dex::Tool — LLM Reference
+
+Install with `rake dex:guides` or copy manually to `AGENTS.md`.
+
+---
+
+## Overview
+
+`Dex::Tool` bridges Dex primitives to LLM tool calling via ruby-llm. It accepts Operation or Query classes and returns `RubyLLM::Tool` instances ready for `chat.with_tools(...)`.
+
+Requires `gem "ruby_llm"` in your Gemfile. Lazy-loaded — ruby-llm is only required when you call `Dex::Tool`.
+
+---
+
+## Operation Tools
+
+### Creating
+
+```ruby
+tool = Dex::Tool.from(Orders::Place)       # single operation
+tools = Dex::Tool.all                       # all registered operations
+tools = Dex::Tool.from_namespace("Orders")  # operations under Orders::
+```
+
+`from` accepts no options for Operation classes. `all` and `from_namespace` return sorted arrays.
+
+### Tool Schema
+
+The tool name is derived from the class name: `Orders::Place` becomes `dex_orders_place`.
+
+The description includes:
+- The operation's `description` (or class name if none)
+- Guard preconditions (if any)
+- Declared error codes (if any)
+
+The params schema is the operation's `contract.to_json_schema`.
+
+### Execution Flow
+
+1. Params are symbolized
+2. Operation is instantiated with params
+3. Called via `.safe.call` (returns `Ok` or `Err`, never raises)
+4. `Ok` — returns `value.as_json` (or raw value if no `as_json`)
+5. `Err` — returns `{ error:, message:, details: }`
+
+### Example
+
+```ruby
+class Orders::Place < Dex::Operation
+  description "Place a new order for a customer"
+
+  prop :customer_id, _Ref(Customer)
+  prop :product_id, _Ref(Product)
+  prop? :quantity, Integer, default: 1
+
+  error :out_of_stock, :invalid_quantity
+
+  guard :sufficient_stock, "Product must be in stock" do
+    Product.find(product_id).stock >= quantity
+  end
+
+  def perform
+    error!(:invalid_quantity) if quantity <= 0
+    Order.create!(customer_id: customer_id, product_id: product_id, quantity: quantity)
+  end
+end
+
+tool = Dex::Tool.from(Orders::Place)
+chat = RubyLLM.chat.with_tools(tool)
+chat.ask("Place an order for customer #12, product #42, quantity 3")
+```
+
+### Error Shape
+
+When an operation returns `Err`, the tool returns:
+
+```ruby
+{ error: :out_of_stock, message: "out_of_stock", details: nil }
+```
+
+---
+
+## Explain Tool
+
+A meta-tool that checks whether an operation can execute with given params, without running it:
+
+```ruby
+tool = Dex::Tool.explain_tool
+chat = RubyLLM.chat.with_tools(tool)
+chat.ask("Can I place an order for product #42?")
+```
+
+The LLM calls it with `{ operation: "Orders::Place", params: { product_id: 42 } }`. Returns:
+
+```ruby
+{ callable: true, guards: [{ name: :sufficient_stock, passed: true }], once: nil, lock: nil }
+```
+
+If the operation is not in the registry: `{ error: "unknown_operation", message: "..." }`.
+
+---
+
+## Query Tools
+
+### Creating
+
+```ruby
+tool = Dex::Tool.from(Product::Query,
+  scope: -> { Current.user.products },
+  serialize: ->(record) { record.as_json(only: %i[id name price stock]) })
+```
+
+### Required Options
+
+Both `scope:` and `serialize:` are mandatory for Query tools.
+
+**`scope:`** — a lambda returning the base relation. Called at execution time:
+
+```ruby
+Dex::Tool.from(Order::Query,
+  scope: -> { Current.user.orders },
+  serialize: ->(r) { r.as_json })
+
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.where(active: true) },
+  serialize: ->(r) { r.as_json })
+```
+
+**`serialize:`** — a lambda converting each record to a hash:
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json(only: %i[id name price]) })
+
+Dex::Tool.from(Order::Query,
+  scope: -> { Current.user.orders },
+  serialize: ->(r) { { id: r.id, total: r.total, status: r.status } })
+```
+
+### Optional Restrictions
+
+**`limit:`** — max results per page (default: 50). The LLM can request fewer but never more:
+
+```ruby
+Dex::Tool.from(Product::Query, scope: -> { Product.all }, serialize: ->(r) { r.as_json }, limit: 25)
+```
+
+**`only_filters:`** — allowlist of filters exposed to the LLM:
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json },
+  only_filters: %i[name category])
+```
+
+**`except_filters:`** — denylist of filters hidden from the LLM (mutually exclusive with `only_filters:`):
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json },
+  except_filters: %i[internal_code])
+```
+
+**`only_sorts:`** — allowlist of sort columns. Must include the query's default sort if one exists:
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json },
+  only_sorts: %i[name price created_at])
+```
+
+### Auto-Exclusions
+
+These props are automatically excluded from the tool schema (the LLM never sees them):
+
+- Props mapped via `context` (filled from ambient context)
+- `_Ref` typed props (model references)
+- Props for hidden filters (via `only_filters:` / `except_filters:`)
+
+If an auto-excluded prop is required with no default and no context mapping, `from` raises `ArgumentError` at build time.
+
+### Tool Schema
+
+The tool name is `dex_query_{class_name}` (lowercased, `::` replaced with `_`).
+
+The description includes:
+- The query's `description` (or class name)
+- Available filters with type hints and enum values
+- Available sorts with default indicator
+- Max results per page
+
+The params schema includes visible filter props plus:
+
+- `sort` — enum of allowed sort values (prefix with `-` for descending; custom sorts have no `-` variant)
+- `limit` — integer, max results
+- `offset` — integer, skip N results (for pagination)
+
+### Execution Flow
+
+1. Extract `limit`, `offset`, `sort` from params
+2. Clamp `limit` to max (default 50); zero or negative resets to max
+3. Floor `offset` at 0
+4. Validate sort value against allowed sorts; drop invalid (falls back to query default)
+5. Custom sorts reject `-` prefix (direction is baked into the block)
+6. Strip context-mapped and excluded filter params
+7. Inject scope from `scope:` lambda
+8. Build query via `from_params` (coercion, blank stripping, validation)
+9. Resolve, count total, apply offset/limit
+10. Serialize each record via `serialize:` lambda
+
+### Return Shape
+
+```json
+{
+  "records": [{ "id": 1, "name": "Widget", "price": 9.99 }],
+  "total": 142,
+  "limit": 50,
+  "offset": 0
+}
+```
+
+`total` is `nil` if the count query fails (e.g., complex GROUP BY).
+
+### Error Handling
+
+Invalid params or type errors:
+
+```ruby
+{ error: "invalid_params", message: "..." }
+```
+
+Any other error:
+
+```ruby
+{ error: "query_failed", message: "..." }
+```
+
+---
+
+## Context
+
+`Dex.with_context` provides ambient values to both Operation and Query tools. Props with `context` mappings are auto-filled and hidden from the LLM:
+
+```ruby
+class Orders::Place < Dex::Operation
+  prop :customer_id, _Ref(Customer)
+  context customer_id: :current_customer_id
+  # ...
+end
+
+class Order::Query < Dex::Query
+  scope { Order.all }
+  prop? :customer_id, _Ref(Customer)
+  context customer_id: :current_customer_id
+  filter :customer_id
+  # ...
+end
+
+Dex.with_context(current_customer_id: current_user.customer_id) do
+  chat.ask("Show me my recent orders")
+end
+```
+
+The LLM never sees `customer_id` in either tool's schema — it is injected from context.
+
+---
+
+## Security Model
+
+Five layers protect against misuse:
+
+1. **Scope lambda** — called at execution time, applies authorization (`Current.user.orders`, `policy_scope(...)`)
+2. **Context injection** — security-sensitive props (tenant, user) are filled from ambient context, invisible to the LLM
+3. **Filter restrictions** — `only_filters:` / `except_filters:` control what the LLM can search on
+4. **Sort restrictions** — `only_sorts:` limits available sort columns
+5. **Limit cap** — `limit:` sets a hard ceiling on results per page; the LLM cannot exceed it
+
+---
+
+## Combining Operation + Query Tools
+
+```ruby
+order_tools = Dex::Tool.from_namespace("Orders")
+
+search_tool = Dex::Tool.from(Product::Query,
+  scope: -> { Current.user.products },
+  serialize: ->(r) { r.as_json(only: %i[id name price stock]) },
+  limit: 20,
+  only_filters: %i[name category],
+  only_sorts: %i[name price])
+
+explain = Dex::Tool.explain_tool
+
+chat = RubyLLM.chat
+chat.with_tools(*order_tools, search_tool, explain)
+
+Dex.with_context(current_customer_id: current_user.customer_id) do
+  chat.ask("Find products under $50, then place an order for the cheapest one")
+end
+```
+
+---
+
+**End of reference.**

data/lib/dex/context_dsl.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dex
+  # Shared context DSL extracted from ContextSetup.
+  #
+  # Provides the `context` class method, `context_mappings` inheritance,
+  # and `_context_own` storage.  Includers must implement:
+  #   _context_prop_declared?(name) → true/false
+  # and may override:
+  #   _context_field_label → "prop" | "field" (used in error messages)
+  module ContextDSL
+    def context(*names, **mappings)
+      names.each do |name|
+        unless name.is_a?(Symbol)
+          raise ArgumentError, "context shorthand must be a Symbol, got: #{name.inspect}"
+        end
+        mappings[name] = name
+      end
+
+      raise ArgumentError, "context requires at least one mapping" if mappings.empty?
+
+      label = _context_field_label
+      mappings.each do |prop_name, context_key|
+        unless _context_prop_declared?(prop_name)
+          raise ArgumentError,
+            "context references undeclared #{label} :#{prop_name}. Declare the #{label} before calling context."
+        end
+        unless context_key.is_a?(Symbol)
+          raise ArgumentError,
+            "context key must be a Symbol, got: #{context_key.inspect} for #{label} :#{prop_name}"
+        end
+      end
+
+      _context_own.merge!(mappings)
+    end
+
+    def context_mappings
+      parent = superclass.respond_to?(:context_mappings) ? superclass.context_mappings : {}
+      parent.merge(_context_own)
+    end
+
+    private
+
+    def _context_own
+      @_context_own_mappings ||= {}
+    end
+
+    def _context_prop_declared?(_name)
+      raise NotImplementedError, "#{self} must implement _context_prop_declared?"
+    end
+
+    def _context_field_label
+      "prop"
+    end
+  end
+end

data/lib/dex/context_setup.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Dex
-  # Shared context DSL for Operation and Event.
+  # Context DSL for Operation and Event (Literal::Properties-backed).
   #
   # Maps declared props to ambient context keys so they can be auto-filled
   # from Dex.context when not passed explicitly as kwargs.
@@ -9,34 +9,7 @@ module Dex
     extend Dex::Concern
 
     module ClassMethods
-      def context(*names, **mappings)
-        names.each do |name|
-          unless name.is_a?(Symbol)
-            raise ArgumentError, "context shorthand must be a Symbol, got: #{name.inspect}"
-          end
-          mappings[name] = name
-        end
-
-        raise ArgumentError, "context requires at least one mapping" if mappings.empty?
-
-        mappings.each do |prop_name, context_key|
-          unless _context_prop_declared?(prop_name)
-            raise ArgumentError,
-              "context references undeclared prop :#{prop_name}. Declare the prop before calling context."
-          end
-          unless context_key.is_a?(Symbol)
-            raise ArgumentError,
-              "context key must be a Symbol, got: #{context_key.inspect} for prop :#{prop_name}"
-          end
-        end
-
-        _context_own.merge!(mappings)
-      end
-
-      def context_mappings
-        parent = superclass.respond_to?(:context_mappings) ? superclass.context_mappings : {}
-        parent.merge(_context_own)
-      end
+      include ContextDSL
 
       def new(**kwargs)
         mappings = context_mappings
@@ -52,10 +25,6 @@ module Dex
 
       private
 
-      def _context_own
-        @_context_own_mappings ||= {}
-      end
-
       def _context_prop_declared?(name)
         respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
       end

data/lib/dex/event/bus.rb

@@ -44,19 +44,18 @@ module Dex
         def publish(event, sync:)
           return if Suppression.suppressed?(event.class)
 
-          persist(event)
+          trace_data = trace_data_for(event)
+          persist(event, trace_data)
           handlers = subscribers_for(event.class)
           return if handlers.empty?
 
-          event_frame = event.trace_frame
-
           handlers.each do |handler_class|
             if sync
-              Trace.restore(event_frame) do
+              Dex::Trace.restore(trace_data) do
                 handler_class._event_handle(event)
               end
             else
-              enqueue(handler_class, event, event_frame)
+              enqueue(handler_class, event, trace_data)
             end
           end
         end
@@ -67,33 +66,102 @@ module Dex
 
         private
 
-        def persist(event)
+        def persist(event, trace_data)
           store = Dex.configuration.event_store
           return unless store
 
-          store.create!(
+          actor = actor_from_trace(trace_data[:frames])
+          attrs = safe_store_attributes(store, {
+            id: event.id,
+            trace_id: event.trace_id,
+            actor_type: actor&.dig(:actor_type),
+            actor_id: actor&.dig(:id),
+            trace: trace_data[:frames],
             event_type: event.class.name,
             payload: event._props_as_json,
             metadata: event.metadata.as_json
-          )
+          })
+
+          store.create!(**attrs)
         rescue => e
           Event._warn("Failed to persist event: #{e.message}")
         end
 
         def enqueue(handler_class, event, trace_data)
           ensure_active_job_loaded!
-          ctx = event.context
 
           Dex::Event::Processor.perform_later(
             handler_class: handler_class.name,
             event_class: event.class.name,
             payload: event._props_as_json,
             metadata: event.metadata.as_json,
-            trace: trace_data,
-            context: ctx
+            trace: trace_data
           )
         end
 
+        def trace_data_for(event)
+          ambient = Dex::Trace.dump
+          frames = if ambient && trace_matches_event?(ambient, event)
+            trace_frames(ambient)
+          elsif ambient
+            actor_frames(trace_frames(ambient))
+          else
+            []
+          end
+
+          {
+            trace_id: event.trace_id,
+            frames: frames,
+            event_context: event_context_for(event)
+          }
+        end
+
+        def actor_from_trace(frames)
+          Array(frames).find do |frame|
+            frame_type = frame[:type] || frame["type"]
+            frame_type && frame_type.to_sym == :actor
+          end
+        end
+
+        def actor_frames(frames)
+          Array(frames).select do |frame|
+            frame_type = frame[:type] || frame["type"]
+            frame_type && frame_type.to_sym == :actor
+          end
+        end
+
+        def trace_frames(trace_data)
+          Array(trace_data[:frames] || trace_data["frames"])
+        end
+
+        def trace_matches_event?(trace_data, event)
+          trace_id = trace_data[:trace_id] || trace_data["trace_id"]
+          trace_id.to_s == event.trace_id.to_s
+        end
+
+        def event_context_for(event)
+          {
+            id: event.id,
+            trace_id: event.trace_id,
+            event_class: event.class.name,
+            event_ancestry: event.event_ancestry
+          }
+        end
+
+        def safe_store_attributes(store, attributes)
+          if store.respond_to?(:column_names)
+            allowed = store.column_names.to_set
+            attributes.select { |key, _| allowed.include?(key.to_s) }
+          elsif store.respond_to?(:fields)
+            attributes.select do |key, _|
+              field_name = key.to_s
+              store.fields.key?(field_name) || (field_name == "id" && store.fields.key?("_id"))
+            end
+          else
+            attributes
+          end
+        end
+
         def ensure_active_job_loaded!
           return if defined?(ActiveJob::Base)
 

data/lib/dex/event/handler.rb

@@ -69,9 +69,26 @@ module Dex
       end
 
       def self._event_handle(event)
+        execution_id = Dex::Id.generate("hd_")
+        auto_started = Dex::Trace.ensure_started!(trace_id: event.trace_id)
+        pushed = false
+        Dex::Trace.push(
+          type: :handler,
+          id: execution_id,
+          class: name,
+          event_class: event.class.name,
+          event_id: event.id,
+          event_ancestry: event.metadata.event_ancestry
+        )
+        pushed = true
+
         instance = new
         instance.instance_variable_set(:@event, event)
+        instance.instance_variable_set(:@_dex_execution_id, execution_id)
         instance.send(:call)
+      ensure
+        Dex::Trace.pop if pushed
+        Dex::Trace.stop! if auto_started
       end
 
       def self._event_handle_from_payload(event_class_name, payload, metadata_hash)
@@ -96,7 +113,7 @@ module Dex
             timestamp: Time.parse(metadata_hash["timestamp"]),
             trace_id: metadata_hash["trace_id"],
             caused_by_id: metadata_hash["caused_by_id"],
-            context: metadata_hash["context"]
+            event_ancestry: metadata_hash["event_ancestry"] || []
           )
           instance.instance_variable_set(:@metadata, metadata)
           instance.freeze