chore(docs): document context and token utility functions

Adds documentation for `llm_context_size()`, `llm_context_used()`, and `llm_token_count(text)` functions.

Author: andinux

API.md

@@ -245,6 +245,35 @@ Frees the current inference context.
 SELECT llm_context_free();
 ```
 
+---
+## `llm_context_size()`
+
+**Returns:** `INTEGER`
+
+**Description**:
+Returns the total token capacity (context window) of the current llama context. Use this after `llm_context_create` to confirm the configured `context_size`. Raises an error if no context is active.
+
+```sql
+SELECT llm_context_size();
+-- 4096
+```
+
+---
+
+## `llm_context_used()`
+
+**Returns:** `INTEGER`
+
+**Description:**
+Returns how many tokens of the current llama context have already been consumed. Combine this with `llm_context_size()` to monitor usage. Raises an error if no context is active.
+
+**Example:**
+
+```sql
+SELECT llm_context_used();
+-- 1024
+```
+
 ---
 
 ## `llm_sampler_create()`
@@ -546,6 +575,22 @@ SELECT llm_sampler_init_penalties(64, 1.2, 0.5, 0.8);
 
 ---
 
+## `llm_token_count(text TEXT)`
+
+**Returns:** `INTEGER`
+
+**Description:**
+Returns how many tokens the current model would consume for the supplied `text`, using the active context’s vocabulary. Requires a context created via `llm_context_create`.
+
+**Example:**
+
+```sql
+SELECT llm_token_count('Hello world!');
+-- 5
+```
+
+---
+
 ## `llm_embed_generate(text TEXT, options TEXT)`
 
 **Returns:** `BLOB` or `TEXT`

src/sqlite-ai.c

@@ -2351,27 +2351,6 @@ static void llm_context_create (sqlite3_context *context, int argc, sqlite3_valu
     llm_context_create_with_options(context, ai, options, NULL);
 }
 
-static void llm_context_size (sqlite3_context *context, int argc, sqlite3_value **argv) {
-    ai_context *ai = (ai_context *)sqlite3_user_data(context);
-    if (!ai->ctx) {
-        sqlite_context_result_error(context, SQLITE_MISUSE, "No context found. Please call llm_context_create() before using this function.");
-        return;
-    }
-    uint32_t n_ctx = llama_n_ctx(ai->ctx);
-    sqlite3_result_int(context, n_ctx);
-}
-
-static void llm_context_used (sqlite3_context *context, int argc, sqlite3_value **argv) {
-    ai_context *ai = (ai_context *)sqlite3_user_data(context);
-    if (!ai->ctx) {
-        sqlite_context_result_error(context, SQLITE_MISUSE, "No context found. Please call llm_context_create() before using this function.");
-        return;
-    }
-    int32_t n_ctx_used = llama_memory_seq_pos_max(llama_get_memory(ai->ctx), 0) + 1;
-    if (n_ctx_used < 0) n_ctx_used = 0;
-    sqlite3_result_int(context, n_ctx_used);
-}
-
 static void llm_context_create_embedding (sqlite3_context *context, int argc, sqlite3_value **argv) {
     const char *options = AI_DEFAULT_CONTEXT_EMBEDDING_OPTIONS;
     const char *options2 = (argc > 0) ? (const char *)sqlite3_value_text(argv[0]) : NULL;
@@ -2393,6 +2372,27 @@ static void llm_context_create_textgen (sqlite3_context *context, int argc, sqli
     llm_context_create_with_options(context, ai, options, options2);
 }
 
+static void llm_context_size (sqlite3_context *context, int argc, sqlite3_value **argv) {
+    ai_context *ai = (ai_context *)sqlite3_user_data(context);
+    if (!ai->ctx) {
+        sqlite_context_result_error(context, SQLITE_MISUSE, "No context found. Please call llm_context_create() before using this function.");
+        return;
+    }
+    uint32_t n_ctx = llama_n_ctx(ai->ctx);
+    sqlite3_result_int(context, n_ctx);
+}
+
+static void llm_context_used (sqlite3_context *context, int argc, sqlite3_value **argv) {
+    ai_context *ai = (ai_context *)sqlite3_user_data(context);
+    if (!ai->ctx) {
+        sqlite_context_result_error(context, SQLITE_MISUSE, "No context found. Please call llm_context_create() before using this function.");
+        return;
+    }
+    int32_t n_ctx_used = llama_memory_seq_pos_max(llama_get_memory(ai->ctx), 0) + 1;
+    if (n_ctx_used < 0) n_ctx_used = 0;
+    sqlite3_result_int(context, n_ctx_used);
+}
+
 static void llm_model_free (sqlite3_context *context, int argc, sqlite3_value **argv) {
     ai_context *ai = (ai_context *)sqlite3_user_data(context);
     ai_cleanup((void *)ai, true, false);