KosmoKrator

data

Deepgram Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Deepgram KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.deepgram.*. Use lua_read_doc("integrations.deepgram") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Deepgram workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.deepgram.transcribe_url({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("deepgram"))' --json
kosmo integrations:lua --eval 'print(docs.read("deepgram.transcribe_url"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local deepgram = app.integrations.deepgram
local result = deepgram.transcribe_url({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.deepgram, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.deepgram.default.* or app.integrations.deepgram.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Deepgram, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Deepgram

Namespace: deepgram

Deepgram provides speech-to-text, text intelligence, text-to-speech, and management APIs. This integration uses Authorization: Token <API_KEY> and defaults to https://api.deepgram.com/v1.

Speech To Text

Use deepgram_transcribe_url for hosted media:

local result = deepgram.transcribe_url({
  body = { url = "https://example.test/audio.wav" },
  model = "nova-3",
  smart_format = true,
  diarize = true,
  utterances = true
})

Use deepgram_transcribe_audio when the host has already read audio bytes:

local result = deepgram.transcribe_audio({
  content = audio_bytes,
  content_type = "audio/wav",
  model = "nova-3",
  smart_format = true
})

The REST tools cover prerecorded transcription. Deepgram live transcription and live TTS are WebSocket APIs and are not exposed by this JSON tool package.

Text Intelligence

Use deepgram_analyze_text for summaries, topics, intents, and sentiment.

local analysis = deepgram.analyze_text({
  body = { text = "Customer transcript goes here." },
  summarize = true,
  sentiment = true,
  topics = true,
  intents = true
})

Text To Speech

Use deepgram_speak to generate speech from text. The response returns content_type and audio_base64.

local audio = deepgram.speak({
  body = { text = "Hello from Deepgram." },
  model = "aura-2-thalia-en"
})

Models And Project Management

Model tools:

  • deepgram_list_models
  • deepgram_get_model
  • deepgram_list_project_models
  • deepgram_get_project_model

Project tools:

  • deepgram_list_projects
  • deepgram_get_project
  • deepgram_update_project
  • deepgram_list_project_keys
  • deepgram_create_project_key
  • deepgram_delete_project_key
  • deepgram_list_project_balances
  • deepgram_get_project_balance
  • deepgram_get_usage_breakdown
  • deepgram_get_project_request

Create/update tools accept a body object matching Deepgram’s official request schema. Use fake values in tests and docs; never commit real project IDs, API keys, or request IDs.

Raw agent markdown 
# Deepgram

Namespace: `deepgram`

Deepgram provides speech-to-text, text intelligence, text-to-speech, and management APIs. This integration uses `Authorization: Token <API_KEY>` and defaults to `https://api.deepgram.com/v1`.

## Speech To Text

Use `deepgram_transcribe_url` for hosted media:

```lua
local result = deepgram.transcribe_url({
  body = { url = "https://example.test/audio.wav" },
  model = "nova-3",
  smart_format = true,
  diarize = true,
  utterances = true
})
```

Use `deepgram_transcribe_audio` when the host has already read audio bytes:

```lua
local result = deepgram.transcribe_audio({
  content = audio_bytes,
  content_type = "audio/wav",
  model = "nova-3",
  smart_format = true
})
```

The REST tools cover prerecorded transcription. Deepgram live transcription and live TTS are WebSocket APIs and are not exposed by this JSON tool package.

## Text Intelligence

Use `deepgram_analyze_text` for summaries, topics, intents, and sentiment.

```lua
local analysis = deepgram.analyze_text({
  body = { text = "Customer transcript goes here." },
  summarize = true,
  sentiment = true,
  topics = true,
  intents = true
})
```

## Text To Speech

Use `deepgram_speak` to generate speech from text. The response returns `content_type` and `audio_base64`.

```lua
local audio = deepgram.speak({
  body = { text = "Hello from Deepgram." },
  model = "aura-2-thalia-en"
})
```

## Models And Project Management

Model tools:

- `deepgram_list_models`
- `deepgram_get_model`
- `deepgram_list_project_models`
- `deepgram_get_project_model`

Project tools:

- `deepgram_list_projects`
- `deepgram_get_project`
- `deepgram_update_project`
- `deepgram_list_project_keys`
- `deepgram_create_project_key`
- `deepgram_delete_project_key`
- `deepgram_list_project_balances`
- `deepgram_get_project_balance`
- `deepgram_get_usage_breakdown`
- `deepgram_get_project_request`

Create/update tools accept a `body` object matching Deepgram's official request schema. Use fake values in tests and docs; never commit real project IDs, API keys, or request IDs.
Metadata-derived Lua example 
local result = app.integrations.deepgram.transcribe_url({})
print(result)

Functions

transcribe_url Read

Transcribe prerecorded media from a hosted URL.

Lua path
app.integrations.deepgram.transcribe_url
Full name
deepgram.deepgram_transcribe_url
ParameterTypeRequiredDescription
No parameters.
transcribe_audio Read

Transcribe raw audio bytes submitted by the host.

Lua path
app.integrations.deepgram.transcribe_audio
Full name
deepgram.deepgram_transcribe_audio
ParameterTypeRequiredDescription
No parameters.
analyze_text Read

Analyze text or a URL for summaries, topics, intents, and sentiment.

Lua path
app.integrations.deepgram.analyze_text
Full name
deepgram.deepgram_analyze_text
ParameterTypeRequiredDescription
No parameters.
speak Read

Generate speech audio from text and return base64 audio.

Lua path
app.integrations.deepgram.speak
Full name
deepgram.deepgram_speak
ParameterTypeRequiredDescription
No parameters.
list_models Read

List public Deepgram STT and TTS models.

Lua path
app.integrations.deepgram.list_models
Full name
deepgram.deepgram_list_models
ParameterTypeRequiredDescription
No parameters.
get_model Read

Get public Deepgram model metadata.

Lua path
app.integrations.deepgram.get_model
Full name
deepgram.deepgram_get_model
ParameterTypeRequiredDescription
No parameters.
list_projects Read

List projects visible to the API key.

Lua path
app.integrations.deepgram.list_projects
Full name
deepgram.deepgram_list_projects
ParameterTypeRequiredDescription
No parameters.
get_project Read

Get Deepgram project details.

Lua path
app.integrations.deepgram.get_project
Full name
deepgram.deepgram_get_project
ParameterTypeRequiredDescription
No parameters.
update_project Write

Update Deepgram project settings such as name.

Lua path
app.integrations.deepgram.update_project
Full name
deepgram.deepgram_update_project
ParameterTypeRequiredDescription
No parameters.
list_project_keys Read

List API keys for a project.

Lua path
app.integrations.deepgram.list_project_keys
Full name
deepgram.deepgram_list_project_keys
ParameterTypeRequiredDescription
No parameters.
create_project_key Write

Create an API key for a project.

Lua path
app.integrations.deepgram.create_project_key
Full name
deepgram.deepgram_create_project_key
ParameterTypeRequiredDescription
No parameters.
delete_project_key Write

Delete an API key from a project.

Lua path
app.integrations.deepgram.delete_project_key
Full name
deepgram.deepgram_delete_project_key
ParameterTypeRequiredDescription
No parameters.
list_project_balances Read

List outstanding balances for a project.

Lua path
app.integrations.deepgram.list_project_balances
Full name
deepgram.deepgram_list_project_balances
ParameterTypeRequiredDescription
No parameters.
get_project_balance Read

Get one project balance by ID.

Lua path
app.integrations.deepgram.get_project_balance
Full name
deepgram.deepgram_get_project_balance
ParameterTypeRequiredDescription
No parameters.
get_usage_breakdown Read

Get project usage breakdown with filters and groupings.

Lua path
app.integrations.deepgram.get_usage_breakdown
Full name
deepgram.deepgram_get_usage_breakdown
ParameterTypeRequiredDescription
No parameters.
get_project_request Read

Get one project request by ID.

Lua path
app.integrations.deepgram.get_project_request
Full name
deepgram.deepgram_get_project_request
ParameterTypeRequiredDescription
No parameters.
list_project_models Read

List public and private models available to a project.

Lua path
app.integrations.deepgram.list_project_models
Full name
deepgram.deepgram_list_project_models
ParameterTypeRequiredDescription
No parameters.
get_project_model Read

Get project-specific model metadata.

Lua path
app.integrations.deepgram.get_project_model
Full name
deepgram.deepgram_get_project_model
ParameterTypeRequiredDescription
No parameters.