feat(usage): update Usage module

Author: roxblnfk

src/actor/src/_index.yaml

@@ -8,7 +8,7 @@ entries:
     meta:
       description: "Testing component"
     component: "wippy/test"
-    version: ">=v0.0.1"
+    version: ">=v0.2.0"
 
   # wippy.actor:actor
   - name: actor

src/llm/src/_index.yaml

@@ -8,7 +8,7 @@ entries:
     meta:
       description: "Testing component"
     component: "wippy/test"
-    version: ">=v0.0.1"
+    version: ">=v0.2.0"
 
   # wippy.llm:embedder
   - name: embedder

src/usage/_index.yaml src/usage/src/_index.yamlsrc/usage/_index.yaml renamed to src/usage/src/_index.yaml

@@ -8,18 +8,19 @@ entries:
     meta:
       description: "Application database ID for usage tracking"
     targets:
-      - entry: env-target_db
+      - entry: wippy.usage.env:target_db
         path: ".default"
       - entry: wippy.usage.migrations:01_create_token_usage_table
         path: ".meta.env-target_db"
+    default: "app:db"
 
   # Dependencies
   - name: __dependency.wippy.test
     kind: "ns.dependency"
     meta:
       description: "Testing component"
     component: "wippy/test"
-    version: ">=v0.0.1"
+    version: ">=v0.2.0"
 
   - name: __dependency.wippy.migration
     kind: "ns.dependency"
@@ -28,21 +29,6 @@ entries:
     component: "wippy/migration"
     version: ">=v0.0.7"
 
-  # wippy.usage:envs
-  - name: envs
-    kind: env.storage.os
-    meta:
-      type: envstorage
-      comment: OS storage for environment variables
-
-  # wippy.usage:env-target_db
-  - name: env-target_db
-    kind: env.variable
-    meta:
-      type: config_key
-      comment: Database resource identifier
-    storage: wippy.usage:envs
-
   # wippy.usage:token_usage_repo
   - name: token_usage_repo
     kind: library.lua
@@ -58,7 +44,6 @@ entries:
       - json
       - uuid
       - time
-      - env
 
   # wippy.usage:token_usage_repo_test
   - name: token_usage_repo_test
@@ -67,7 +52,7 @@ entries:
       name: Token Usage Repository Test
       type: test
       comment: Tests for the token usage repository functionality
-      group: Usage Tests
+      group: LLM / Usage Tests
       tags:
         - usage
         - tokens
@@ -85,3 +70,36 @@ entries:
       test: wippy.test:test
       token_usage_repo: wippy.usage:token_usage_repo
     method: run_tests
+
+  # wippy.usage:usage_tracker
+  - name: usage_tracker
+    kind: function.lua
+    meta:
+      comment: Usage tracker contract handler for recording LLM token usage
+      tags:
+        - usage
+        - tokens
+        - tracking
+    source: file://usage_tracker.lua
+    modules:
+      - security
+    imports:
+      token_usage_repo: wippy.usage:token_usage_repo
+    method: track_usage
+    pool:
+      max_size: 25
+
+  # wippy.usage:usage_tracker_binding
+  - name: usage_tracker_binding
+    kind: contract.binding
+    meta:
+      comment: Usage tracker contract binding to token usage repository
+      tags:
+        - usage
+        - binding
+        - contract
+    contracts:
+      - contract: wippy.llm:usage_tracker
+        default: true
+        methods:
+          track_usage: wippy.usage:usage_tracker

src/usage/src/env/_index.yaml

@@ -0,0 +1,11 @@
+version: "1.0"
+namespace: wippy.usage.env
+
+entries:
+  # wippy.usage.env:target_db
+  - name: target_db
+    kind: env.variable
+    meta:
+      type: config_key
+      comment: Database resource identifier
+    storage: wippy.usage:envs

src/usage/src/migrations/01_create_token_usage_table.lua

@@ -0,0 +1,154 @@
+-- 01_create_token_usage_table.lua (updated)
+return require("migration").define(function()
+    migration("Create token_usage table", function()
+        database("postgres", function()
+            up(function(db)
+                -- Create token_usage table
+                local success, err = db:execute([[
+                    CREATE TABLE token_usage (
+                        usage_id TEXT PRIMARY KEY,
+                        user_id TEXT NOT NULL,
+                        context_id TEXT,
+                        model_id TEXT NOT NULL,
+                        prompt_tokens INTEGER NOT NULL,
+                        completion_tokens INTEGER NOT NULL,
+                        thinking_tokens INTEGER NOT NULL DEFAULT 0,
+                        cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+                        cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+                        timestamp timestamp NOT NULL DEFAULT now(),
+                        meta TEXT
+                    )
+                ]])
+
+                if err then
+                    error(err)
+                end
+
+                -- Create indexes
+                success, err = db:execute("CREATE INDEX idx_token_usage_user ON token_usage(user_id)")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("CREATE INDEX idx_token_usage_context ON token_usage(context_id)")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("CREATE INDEX idx_token_usage_model ON token_usage(model_id)")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("CREATE INDEX idx_token_usage_timestamp ON token_usage(timestamp)")
+                if err then
+                    error(err)
+                end
+            end)
+
+            down(function(db)
+                -- Drop indexes first
+                local success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_user")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_context")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_model")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_timestamp")
+                if err then
+                    error(err)
+                end
+
+                -- Drop table
+                success, err = db:execute("DROP TABLE IF EXISTS token_usage")
+                if err then
+                    error(err)
+                end
+            end)
+        end)
+
+        database("sqlite", function()
+            up(function(db)
+                -- Create token_usage table
+                local success, err = db:execute([[
+                    CREATE TABLE token_usage (
+                        usage_id TEXT PRIMARY KEY,
+                        user_id TEXT NOT NULL,
+                        context_id TEXT,
+                        model_id TEXT NOT NULL,
+                        prompt_tokens INTEGER NOT NULL,
+                        completion_tokens INTEGER NOT NULL,
+                        thinking_tokens INTEGER NOT NULL DEFAULT 0,
+                        cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+                        cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+                        timestamp INTEGER NOT NULL,
+                        meta TEXT
+                    )
+                ]])
+
+                if err then
+                    error(err)
+                end
+
+                -- Create indexes
+                success, err = db:execute("CREATE INDEX idx_token_usage_user ON token_usage(user_id)")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("CREATE INDEX idx_token_usage_context ON token_usage(context_id)")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("CREATE INDEX idx_token_usage_model ON token_usage(model_id)")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("CREATE INDEX idx_token_usage_timestamp ON token_usage(timestamp)")
+                if err then
+                    error(err)
+                end
+            end)
+
+            down(function(db)
+                -- Drop indexes first
+                local success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_user")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_context")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_model")
+                if err then
+                    error(err)
+                end
+
+                success, err = db:execute("DROP INDEX IF EXISTS idx_token_usage_timestamp")
+                if err then
+                    error(err)
+                end
+
+                -- Drop table
+                success, err = db:execute("DROP TABLE IF EXISTS token_usage")
+                if err then
+                    error(err)
+                end
+            end)
+        end)
+    end)
+end)

src/usage/src/migrations/_index.yaml

@@ -0,0 +1,21 @@
+version: "1.0"
+namespace: wippy.usage.migrations
+
+entries:
+  # wippy.usage.migrations:01_create_token_usage_table
+  - name: 01_create_token_usage_table
+    kind: function.lua
+    meta:
+      type: migration
+      tags:
+        - usage
+        - tokens
+        - database
+      description: Create token_usage table for tracking LLM token consumption
+      target_db: app:db
+      timestamp: "2025-04-08T10:00:00Z"
+    source: file://01_create_token_usage_table.lua
+    imports:
+      migration: wippy.migration:migration
+    method: migrate
+    

src/usage/token_usage_repo.lua src/usage/src/token_usage_repo.luasrc/usage/token_usage_repo.lua renamed to src/usage/src/token_usage_repo.lua

@@ -2,7 +2,9 @@ local sql = require("sql")
 local json = require("json")
 local uuid = require("uuid")
 local time = require("time")
-local env = require("env")
+
+-- Hardcoded database resource name
+local DB_RESOURCE = "app:db"
 
 local token_usage_repo = {}
 
@@ -16,9 +18,6 @@ token_usage_repo.INTERVAL = {
 
 -- Get a database connection
 local function get_db()
-    -- Get database resource from environment
-    local DB_RESOURCE, _ = env.get("wippy.usage:env-target_db")
-
     local db, err = sql.get(DB_RESOURCE)
     if err then
         return nil, "Failed to connect to database: " .. err
@@ -49,9 +48,9 @@ function token_usage_repo.create(user_id, model_id, prompt_tokens, completion_to
 
     -- Convert meta to JSON if it's a table
     local meta_json = nil
-    if options.meta then
-        if type(options.meta) == "table" then
-            local encoded, err = json.encode(options.meta)
+    if options.metadata then
+        if type(options.metadata) == "table" then
+            local encoded, err = json.encode(options.metadata)
             if err then
                 return nil, "Failed to encode meta: " .. err
             end
@@ -276,7 +275,7 @@ FROM
         -- SQLite implementation using recursive CTE
         local interval_seconds
         local date_format
-
+        
         if interval == token_usage_repo.INTERVAL.HOUR then
             interval_seconds = 3600
             date_format = "%Y-%m-%d %H:00:00"
@@ -293,7 +292,7 @@ FROM
             db:release()
             return nil, "Invalid interval: must be hour, day, week, or month"
         end
-
+        
         query_sql = [[
 WITH RECURSIVE
 time_buckets(bucket_start, bucket_end) AS (
@@ -435,4 +434,4 @@ function token_usage_repo.get_usage_by_model(start_time, end_time)
     return results
 end
 
-return token_usage_repo
+return token_usage_repo

src/usage/token_usage_repo_test.lua src/usage/src/token_usage_repo_test.luasrc/usage/token_usage_repo_test.lua renamed to src/usage/src/token_usage_repo_test.lua

@@ -71,7 +71,7 @@ local function define_tests()
         -- Clean up test data after all tests
         after_all(function()
             -- Get a database connection for cleanup
-            local db_resource, _ = env.get("wippy.usage:env-target_db")
+            local db_resource, _ = env.get("wippy.usage.env:target_db")
             local db, err = sql.get(db_resource)
             if err then
                 error("Failed to connect to database: " .. err)
@@ -120,7 +120,7 @@ local function define_tests()
             local end_time = test_data.base_time + 3600   -- 1 hour from now
 
             -- Query only for our test users to isolate the data
-            local db_resource, _ = env.get("wippy.usage:env-target_db")
+            local db_resource, _ = env.get("wippy.usage.env:target_db")
             local db, db_err = sql.get(db_resource)
             if db_err then error(db_err) end