API Tools¶

Import pattern¶

In consumer scripts, normalize the namespace once:

const ASTX = ASTLib.AST || ASTLib;

`ASTX.Series`¶

Use Series for one-dimensional transforms and aggregations.

Key capabilities:

Element-wise transforms: apply, arithmetic methods, comparisons.
Filtering: filter, query.
Stats: sum, mean, median, mode, std, var.
String/date namespaces: series.str.*, series.dt.*.

Important contract:

query accepts function predicates only.
string evaluation is intentionally not supported.

const s = ASTX.Series.fromArray([1, 2, 3, 4, 5], 'numbers');
const odd = s.query((_series, value) => value % 2 === 1);

Complexity notes:

arithmetic/boolean transforms are linear in series length (O(n)).
query and filter are linear scans (O(n)).

`ASTX.DataFrame`¶

DataFrame is the primary tabular abstraction.

Creation:

fromRecords(records)
fromColumns(columns, options)
fromArrays(arrays, options)
fromSheet(sheet, headerRow)
fromQuery(request)

Transform:

select, selectExpr, selectExprDsl, drop, rename, assign, merge, sort, pivot, groupBy, window.
dropDuplicates(subset = []) with explicit subset semantics.

Output:

toColumns(options)
toRecords, toArrays, toJson, toMarkdown, toSheet, toTable.
schema contracts:
DataFrame.validateSchema(dataFrame, schema, options) / df.validateSchema(schema, options)
DataFrame.enforceSchema(dataFrame, schema, options) / df.enforceSchema(schema, options)

const df = ASTX.DataFrame.fromColumns({
  id: [1, 2],
  amount: [10, 20]
});

const out = df.assign({ amount_x2: frame => frame.amount.multiply(2) });

Window and expression projection examples:

const projected = df.selectExpr({
  id: 'id',
  amount_x2: row => row.amount * 2
});

const withWindows = df
  .window({
    partitionBy: ['region'],
    orderBy: [{ column: 'event_ts', ascending: true }]
  })
  .assign({
    row_number: w => w.rowNumber(),
    amount_lag_1: w => w.col('amount').lag(1),
    amount_running_sum: w => w.col('amount').running('sum')
  });

High-signal behavior:

key comparisons normalize null, undefined, and missing values to the same key state.
object/date subset keys are compared canonically by value.

Complexity guidance:

sort: O(n log n)
dropDuplicates: O(n * k) where k is subset key count
hash-join style merge is approximately O(n + m + matches)

Schema contract example:

const schema = {
  id: { type: 'integer', nullable: false },
  amount: { type: 'float', nullable: true }
};

const report = df.validateSchema(schema, { allowExtraColumns: false });
if (!report.valid) {
  Logger.log(report.violations);
}

const enforced = df.enforceSchema(schema, {
  coerce: true,
  dropExtraColumns: false,
  strict: true
});

`ASTX.GroupBy`¶

Create grouped workflows from DataFrame.groupBy(keys).

agg(mapping) supports named aggregators or custom functions.
apply(fn) runs per-group transforms and concatenates output.

const grouped = df.groupBy(['region']).agg({ amount: ['sum', 'mean'] });

`ASTX.Sql`¶

SQL runtime surface with direct execution, prepared execution, and provider execution control.

Primary methods:

ASTX.Sql.run(request)
ASTX.Sql.prepare(request)
ASTX.Sql.executePrepared(request)
ASTX.Sql.status(request)
ASTX.Sql.cancel(request)
ASTX.Sql.providers()
ASTX.Sql.capabilities(provider)

High-signal behavior:

providers: databricks, bigquery.
run(...) validates provider/sql/parameters/placeholders/options shape.
unsafe placeholder interpolation is disabled by default for run(...).
prepare(...) compiles {{param}} template placeholders and returns a runtime statementId.
executePrepared(...) safely serializes typed params and returns { dataFrame, execution }.
status(...) and cancel(...) call provider-specific execution-control helpers.

See SQL Contracts for provider-specific request details.

`ASTX.Sheets` and `ASTX.Drive`¶

Workspace interoperability surfaces:

ASTX.Sheets.openById, ASTX.Sheets.openByUrl
ASTX.Drive.read, ASTX.Drive.create

`ASTX.Cache`¶

General-purpose cache layer for repeated API results and computed artifacts.

Backends:

memory
drive_json
script_properties
storage_json (persists via AST.Storage URI: gcs://, s3://, dbfs:/)

Production recommendation:

use storage_json for shared multi-user app traffic.
use memory for per-execution memoization only.
avoid drive_json and script_properties for high-concurrency hot paths.

Primary methods:

ASTX.Cache.get(key, options)
ASTX.Cache.set(key, value, options)
ASTX.Cache.delete(key, options)
ASTX.Cache.invalidateByTag(tag, options)
ASTX.Cache.stats(options)
ASTX.Cache.backends() and ASTX.Cache.capabilities(backend)
ASTX.Cache.configure(config) / ASTX.Cache.getConfig() / ASTX.Cache.clearConfig()
ASTX.Cache.clear(options) to clear all entries in a namespace/backend

High-signal behavior:

config precedence is per-call options, then runtime configure(...), then script properties.
deterministic TTL semantics via ttlSec.
tags are normalized and de-duplicated for invalidation workflows.
stats() returns backend/namespace entry counts and hit/miss counters.

ASTX.Cache.configure({
  backend: 'memory',
  namespace: 'my_project',
  defaultTtlSec: 300
});

ASTX.Cache.set('rag:query:abc', { chunks: [1, 2, 3] }, {
  ttlSec: 120,
  tags: ['rag', 'search']
});

const cached = ASTX.Cache.get('rag:query:abc');

storage_json example:

ASTX.Cache.configure({
  backend: 'storage_json',
  namespace: 'my_project',
  storageUri: 's3://my-bucket/cache/ast-cache.json'
});

`ASTX.RAG` retrieval modes¶

ASTX.RAG.search(...) and ASTX.RAG.answer(...) both support:

retrieval.mode = 'vector' (default cosine-only ranking)
retrieval.mode = 'hybrid' (weighted vector + lexical fusion)
retrieval.mode = 'lexical' (BM25-only ranking; no embedding call)
retrieval.lexicalPrefilterTopN for optional lexical shortlist before vector scoring
retrieval.rerank for optional top-N reranking
retrieval.access for source-level allow/deny constraints
generation.maxContextChars / generation.maxContextTokensApprox for bounded grounding context packing
optional request/runtime cache controls (cache.enabled, backend overrides, TTLs)

const answer = ASTX.RAG.answer({
  indexFileId: 'YOUR_INDEX_FILE_ID',
  question: 'What are the top project risks?',
  retrieval: {
    mode: 'hybrid',
    topK: 8,
    minScore: 0.2,
    vectorWeight: 0.6,
    lexicalWeight: 0.4,
    lexicalPrefilterTopN: 100,
    rerank: { enabled: true, topN: 12 },
    access: {
      allowedFileIds: ['file_public_1', 'file_public_2'],
      deniedFileIds: ['file_sensitive_1']
    }
  },
  generation: { provider: 'vertex_gemini' },
  options: { enforceAccessControl: true },
  cache: {
    enabled: true,
    backend: 'storage_json',
    namespace: 'rag_prod',
    storageUri: 's3://my-bucket/ast-cache',
    embeddingTtlSec: 900,
    answerTtlSec: 180
  }
});

`ASTX.Storage`¶

Cross-provider object storage surface:

providers: gcs, s3, dbfs
operations: list, head, read, write, delete, exists, copy, move, signed_url, multipart_write
URI model: gcs://, s3://, dbfs:/

Primary methods:

ASTX.Storage.run(request) for explicit operation routing.
ASTX.Storage.list/head/read/write/delete(request) convenience wrappers.
ASTX.Storage.exists/copy/move/signedUrl/multipartWrite(request) advanced object lifecycle wrappers.
ASTX.Storage.providers() and ASTX.Storage.capabilities(provider) for runtime checks.
ASTX.Storage.configure(config) to set runtime defaults from script properties.
ASTX.Storage.getConfig() and ASTX.Storage.clearConfig() for runtime config inspection/reset.

High-signal behavior:

auth/config resolution: per-call override first, then ASTX.Storage.configure(...), then script properties.
write payload contract is base64-first with text/json helper inputs.
head/read/delete missing objects throw AstStorageNotFoundError.
exists returns output.exists.exists=false for missing objects.
copy/move require same-provider fromUri and toUri in this release.
signedUrl is supported for gcs and s3; DBFS reports typed capability error.
transport retries apply to transient HTTP statuses (429, 5xx) only.

const out = ASTX.Storage.read({
  uri: 'gcs://my-bucket/data/config.json'
});

Logger.log(out.output.data.json || out.output.data.text);

See:

`ASTX.Config`¶

Script property extraction helpers for deterministic runtime bootstrap.

Primary methods:

ASTX.Config.fromScriptProperties(options) to read and normalize script properties.

High-signal behavior:

values are normalized to trimmed strings.
supports keys filtering and prefix filtering (prefix, stripPrefix).
gracefully returns {} when script properties are unavailable.

const props = ASTX.Config.fromScriptProperties({
  prefix: 'OPENAI_',
  stripPrefix: true
});

`ASTX.Runtime`¶

One-shot runtime configuration hydration across module namespaces.

Primary methods:

ASTX.Runtime.configureFromProps(options) to apply script properties to module configure(...) hooks.
ASTX.Runtime.modules() to list supported runtime-configurable module names.

High-signal behavior:

default target modules: AI, RAG, Cache, Storage, Telemetry, Jobs.
configuration merge policy is controlled by options.merge (default true).
supports scoped application with options.modules (for example ['AI', 'RAG']).

const summary = ASTX.Runtime.configureFromProps({
  modules: ['AI', 'RAG', 'Storage']
});

Logger.log(summary.configuredModules);

`ASTX.Telemetry`¶

Observability foundation for request traces and operational diagnostics.

Primary methods:

ASTX.Telemetry.configure(config, options) to set runtime telemetry defaults.
ASTX.Telemetry.getConfig() to inspect current runtime telemetry config.
ASTX.Telemetry.clearConfig() to reset runtime telemetry config.
ASTX.Telemetry.startSpan(name, context) to begin a trace span.
ASTX.Telemetry.endSpan(spanId, result) to close span state and persist sink output.
ASTX.Telemetry.recordEvent(event) to append structured event records.
ASTX.Telemetry.getTrace(traceId) to retrieve in-memory trace state.
ASTX.Telemetry.flush(options) to force buffered sink flushes (used by drive_json and storage_json manual mode).

Sink support:

logger (default) emits JSON payloads to Apps Script Logger.
drive_json writes partitioned NDJSON batch files in Drive (events/YYYY/MM/DD[/HH]).
storage_json writes NDJSON batch files to gcs://, s3://, or dbfs:/ via AST.Storage.

High-signal behavior:

configure(...) supports sink, redaction/sampling, drive settings, storage sink settings (storageUri, flushMode, batchMaxEvents, batchMaxBytes, retries/timeouts), and trace limits.
sensitive keys and token-like values are redacted by default.
telemetry calls should never block functional execution paths.
span IDs and trace IDs are generated if not supplied.

const traceSpan = ASTX.Telemetry.startSpan('demo.operation', {
  requestId: 'req_123'
});

try {
  const value = ASTX.Utils.arraySum([1, 2, 3, 4]);
  ASTX.Telemetry.endSpan(traceSpan, {
    status: 'ok',
    result: { value }
  });
} catch (error) {
  ASTX.Telemetry.endSpan(traceSpan, {
    status: 'error',
    error
  });
  throw error;
}

See:

`ASTX.TelemetryHelpers`¶

Safe wrappers around span/event operations for app-level workflows.

Primary methods:

ASTX.TelemetryHelpers.startSpanSafe(name, context, options)
ASTX.TelemetryHelpers.endSpanSafe(spanId, result, options)
ASTX.TelemetryHelpers.recordEventSafe(event, options)
ASTX.TelemetryHelpers.withSpan(name, context, task, options)
ASTX.TelemetryHelpers.wrap(name, task, options)

High-signal behavior:

never throws from telemetry API failures.
withSpan(...) always attempts to close the span on both success and error.
task errors are re-thrown after telemetry finalization.

const sum = ASTX.TelemetryHelpers.withSpan(
  'app.compute.sum',
  { requestId: 'req_1' },
  () => ASTX.Utils.arraySum([1, 2, 3, 4]),
  { includeResult: true }
);

`ASTX.Jobs`¶

Checkpointed job orchestration for multi-step workflows that need retry and resume semantics.

Primary methods:

ASTX.Jobs.run(request) to enqueue and execute immediately until completion/pause/failure.
ASTX.Jobs.enqueue(request) to persist a queued job without executing it.
ASTX.Jobs.resume(jobId, options) to continue a queued/paused job from checkpoint.
ASTX.Jobs.status(jobId, options) to fetch a single persisted job record.
ASTX.Jobs.list(filters, options) to list persisted job records.
ASTX.Jobs.cancel(jobId, options) to cancel a queued/paused job.
ASTX.Jobs.configure(config, options) / ASTX.Jobs.getConfig() / ASTX.Jobs.clearConfig().

High-signal behavior:

steps require unique id, handler, and optional dependsOn.
handlers must be globally resolvable named functions in Apps Script runtime.
async step handlers are not supported; handlers must return JSON-serializable outputs.
checkpoints are persisted in script properties with configurable key prefix.
retries are bounded by maxRetries; jobs pause on retryable step failure.
currently supported checkpoint store is properties.

const queued = ASTX.Jobs.enqueue({
  name: 'daily_reconciliation',
  steps: [
    { id: 'extract', handler: 'extractStep' },
    { id: 'transform', handler: 'transformStep', dependsOn: ['extract'] },
    { id: 'publish', handler: 'publishStep', dependsOn: ['transform'] }
  ],
  options: {
    maxRetries: 2,
    maxRuntimeMs: 240000,
    propertyPrefix: 'AST_JOBS_JOB_'
  }
});

const resumed = ASTX.Jobs.resume(queued.id);
Logger.log(resumed.status);

See:

Jobs Contracts

`ASTX.Chat`¶

Durable chat-state module for user-scoped thread persistence, turn appends, and history building.

Primary methods:

ASTX.Chat.configure(config, options) / ASTX.Chat.getConfig() / ASTX.Chat.clearConfig().
ASTX.Chat.ThreadStore.create(config) to create a store instance with resolved runtime config.

Store instance methods:

getOrCreateState(userContext) initialize or fetch per-user state.
listThreads(userContext) list thread metadata for a user.
getThread(userContext, { threadId }) fetch a single thread and persisted turns.
newThread(userContext, args) create thread metadata.
switchThread(userContext, { threadId }) change active thread.
appendTurn(userContext, { threadId?, turn }) append a turn and enforce caps.
buildHistory(userContext, options) build bounded chat history for model calls.
clearUser(userContext) remove cached + durable state for a user key.

High-signal behavior:

state is isolated by normalized user key and persisted via cache backend configuration.
defaults use hot memory cache + durable drive_json store.
durable backend can be switched to storage_json (for gcs://, s3://, dbfs:/) or script_properties.
lock-aware writes support explicit degraded mode when allowLockFallback=true.
deterministic limits enforce threadMax and turnsMax.

const store = ASTX.Chat.ThreadStore.create({
  keyPrefix: 'my_app',
  durable: {
    backend: 'drive_json',
    namespace: 'my_app_threads',
    driveFolderId: 'FOLDER_ID',
    driveFileName: 'threads.json'
  },
  limits: {
    threadMax: 25,
    turnsMax: 200
  }
});

const user = { userKey: 'user-123' };
const created = store.newThread(user, { title: 'New chat' });
store.appendTurn(user, {
  threadId: created.threadId,
  turn: { role: 'user', content: 'Summarize open blockers.' }
});

const history = store.buildHistory(user, {
  threadId: created.threadId,
  maxPairs: 10,
  systemMessage: 'You are a project assistant.'
});

See:

Chat Contracts

`ASTX.AI`¶

Unified AI surface across:

openai
gemini
vertex_gemini
openrouter
perplexity

Primary methods:

ASTX.AI.run(request) for explicit operation routing.
ASTX.AI.text(request) for text generation.
ASTX.AI.structured(request) for schema-constrained JSON output.
ASTX.AI.tools(request) for bounded auto tool execution.
ASTX.AI.image(request) for image generation paths.
ASTX.AI.stream(request) for callback-based token/tool event streaming.
ASTX.AI.OutputRepair.continueIfTruncated(request) for bounded continuation repair.
ASTX.AI.providers() and ASTX.AI.capabilities(provider) for runtime checks.
ASTX.AI.configure(config) to set runtime defaults (for example from consumer script properties).
ASTX.AI.getConfig() and ASTX.AI.clearConfig() for runtime config inspection/reset.

High-signal behavior:

auth/config resolution: per-call override first, then ASTX.AI.configure(...) runtime config, then script properties.
unsupported provider-operation pairs throw AstAiCapabilityError.
tool calls support function handlers and global-name handlers.
tool execution is sequential and bounded by options.maxToolRounds.
stream mode emits start, token, tool_call, tool_result, done, and error events via onEvent.
optional routing supports provider fallback using priority, fastest, or cost_first strategies.
deterministic provider 4xx errors only fail over when routing.retryOn.providerErrors=true.
response metadata includes response.route.attempts with per-provider attempt status and retryability.
structured mode has bounded reliability controls via options.reliability:
maxSchemaRetries
repairMode (none, json_repair, llm_repair)
strictValidation
set options.includeRaw=true to include provider raw payloads.
output continuation repair can be applied to partial text with passes + maxOutputTokens.

const out = ASTX.AI.structured({
  provider: 'openai',
  input: 'Return JSON with priority and owner.',
  schema: {
    type: 'object',
    properties: {
      priority: { type: 'string' },
      owner: { type: 'string' }
    },
    required: ['priority', 'owner'],
    additionalProperties: false
  },
  options: {
    reliability: {
      maxSchemaRetries: 2,
      repairMode: 'json_repair',
      strictValidation: true
    }
  }
});

Logger.log(JSON.stringify(out.output.json));

const streamResult = ASTX.AI.stream({
  provider: 'openai',
  input: 'Give me a short status update.',
  onEvent: event => {
    if (event.type === 'token') {
      Logger.log(event.delta);
    }
  }
});

Logger.log(streamResult.output.text);

See:

`ASTX.RAG`¶

Drive-backed retrieval-augmented generation surface for Apps Script chat workflows.

Primary methods:

ASTX.RAG.buildIndex(...) to create a Drive JSON index from Drive sources.
ASTX.RAG.syncIndex(...) to refresh existing indexes after file changes.
ASTX.RAG.search(...) for cosine-ranked retrieval over indexed chunks.
ASTX.RAG.previewSources(...) for citation-ready source cards and reusable retrieval payloads.
ASTX.RAG.answer(...) for grounded answering with strict citation mapping and abstention.
ASTX.RAG.inspectIndex(...) for index metadata/health checks.
ASTX.RAG.buildRetrievalCacheKey(...), putRetrievalPayload(...), getRetrievalPayload(...), deleteRetrievalPayload(...) for retrieval payload interop.
ASTX.RAG.Citations.* for inline citation normalization/filtering/url mapping.
ASTX.RAG.Fallback.fromCitations(...) for deterministic citation-only fallback synthesis.
ASTX.RAG.IndexManager.create(...) for build/sync/fast-state orchestration.
ASTX.RAG.embeddingProviders() and ASTX.RAG.embeddingCapabilities(...).
ASTX.RAG.registerEmbeddingProvider(...) and ASTX.RAG.unregisterEmbeddingProvider(...).

Source support:

plain text
PDF
Google Docs
Google Slides (slide text + speaker notes)

High-signal behavior:

embedding provider/model is bound at index build time and enforced for retrieval.
answer(...) returns status='insufficient_context' when citation grounding fails.
source parse failures can be downgraded to warnings with options.skipParseFailures=true.
repeated hot queries can be accelerated by enabling cache controls on search(...)/answer(...).
answer flows can reuse previewSources payloads via retrievalPayload or retrievalPayloadKey.
answer(...) supports retrieval recovery controls (retrieval.recovery) before generation.
answer(...) supports deterministic fallback policy controls (fallback.onRetrievalError, fallback.onRetrievalEmpty).
search(...) and answer(...) support retrieval budgets via options.maxRetrievalMs.
answer(...) supports retrieval-timeout behavior via options.onRetrievalTimeout (error, insufficient_context, fallback).
answer(...) prompt controls include generation.instructions, generation.style, and generation.forbiddenPhrases.
IndexManager.ensure(...) can optionally fallback unsupported MIME requests to supported MIME sets with diagnostics.
answer(...) can return stable diagnostics for retrieval/generation phase timing + pipeline path when options.diagnostics=true (or RAG_DIAGNOSTICS_ENABLED=true).
diagnostics include cache backend/lock metadata and lock timing/contention (cache.lockScope, timings.lockWaitMs, cache.lockContention).

See:

`ASTX.Utils`¶

Utils exposes public utility helpers.

Examples:

ASTX.Utils.arraySum([1, 2, 3])
ASTX.Utils.dateAdd(new Date(), 1, 'days')
ASTX.Utils.toSnakeCase('Hello World')

For release stability, call through ASTX.Utils rather than relying on global utility symbols.

API Tools¶

Import pattern¶

ASTX.Series¶

ASTX.DataFrame¶

ASTX.GroupBy¶

ASTX.Sql¶

ASTX.Sheets and ASTX.Drive¶

ASTX.Cache¶

ASTX.RAG retrieval modes¶

ASTX.Storage¶

ASTX.Config¶

ASTX.Runtime¶

ASTX.Telemetry¶

ASTX.TelemetryHelpers¶

ASTX.Jobs¶

ASTX.Chat¶

ASTX.AI¶

ASTX.RAG¶

ASTX.Utils¶

`ASTX.Series`¶

`ASTX.DataFrame`¶

`ASTX.GroupBy`¶

`ASTX.Sql`¶

`ASTX.Sheets` and `ASTX.Drive`¶

`ASTX.Cache`¶

`ASTX.RAG` retrieval modes¶

`ASTX.Storage`¶

`ASTX.Config`¶

`ASTX.Runtime`¶

`ASTX.Telemetry`¶

`ASTX.TelemetryHelpers`¶

`ASTX.Jobs`¶

`ASTX.Chat`¶

`ASTX.AI`¶

`ASTX.RAG`¶

`ASTX.Utils`¶