type AccountKey ¶ added in v0.3.0

type AccountKey struct {
	ID                    string  `json:"id"`
	Name                  string  `json:"name"`
	KeyPrefix             string  `json:"key_prefix"`
	MonthlyBudgetMicroUsd *int64  `json:"monthly_budget_micro_usd"`
	CurrentMtdMicroUsd    int64   `json:"current_mtd_micro_usd"`
	CreatedAt             string  `json:"created_at"`
	LastUsedAt            *string `json:"last_used_at"`
	RevokedAt             *string `json:"revoked_at"`
}

AccountKey is the wire shape of a `dgsk_acc_…` org-wide credential.

JSON tags mirror the Python and JS SDKs exactly (key_prefix, monthly_budget_micro_usd, …) so admin payloads are interchangeable across the three SDKs.

type AccountKeyCreated ¶ added in v0.3.0

type AccountKeyCreated struct {
	AccountKey
	Plaintext string `json:"plaintext"`
}

AccountKeyCreated is the response of AccountKeys.Create. The Plaintext token is returned exactly once — persist it now or revoke and recreate.

type AccountKeysService ¶ added in v0.3.0

type AccountKeysService struct {
	// contains filtered or unexported fields
}

AccountKeysService manages `dgsk_acc_…` keys for the caller's org. Returned by Client.AccountKeys; never construct one yourself.

func (s *AccountKeysService) Create(
	ctx context.Context, in CreateAccountKeyInput,
) (*AccountKeyCreated, error)

func (s *AccountKeysService) List(ctx context.Context) ([]AccountKey, error)

func (s *AccountKeysService) Revoke(ctx context.Context, keyID string) error

func (s *AccountKeysService) SetBudget(
	ctx context.Context, keyID string, monthlyBudgetMicroUsd *int64,
) (*AccountKey, error)

type AgentFlowResult ¶ added in v0.3.0

type AgentFlowResult struct {
	FlowID    string `json:"flow_id"`
	Slug      string `json:"slug"`
	Name      string `json:"name"`
	WebhookID string `json:"webhook_id"`
	Created   bool   `json:"created"`
}

AgentFlowResult is what the server returns from UpsertAgent.

type AgentFlowSpec ¶ added in v0.3.0

type AgentFlowSpec struct {
	Slug                string        `json:"slug"`
	Name                string        `json:"name"`
	Provider            string        `json:"provider"`
	Model               string        `json:"model"`
	SystemPrompt        string        `json:"system_prompt"`
	Temperature         *float64      `json:"temperature,omitempty"`
	MaxTokens           *int          `json:"max_tokens,omitempty"`
	HistoryTurns        *int          `json:"history_turns,omitempty"`
	RecentTurns         *int          `json:"recent_turns,omitempty"`
	MaxToolIterations   *int          `json:"max_tool_iterations,omitempty"`
	Tools               []FlowToolRef `json:"tools,omitempty"`
	MemoryFactsSchema   any           `json:"memory_facts_schema,omitempty"`
	MemorySummaryConfig any           `json:"memory_summary_config,omitempty"`
	ContextMemoryKeys   []string      `json:"context_memory_keys,omitempty"`
	// CoalesceEnabled, when set to false, disables the inbound coalesce
	// debounce + dedup for this flow. Use it when the caller's UI already
	// gates the composer client-side and a buffered turn would just add
	// latency. Defaults to true (coalesce on) when nil.
	CoalesceEnabled *bool `json:"coalesce_enabled,omitempty"`
}

AgentFlowSpec is the high-level declaration of a conversational agent flow. Each call to UpsertAgent uses Slug as the org-scoped identity: the first call creates the flow + webhook, subsequent calls update the agent config. The webhook id stays stable across upserts.

type AnalyticsService ¶ added in v0.5.2

type AnalyticsService struct {
	// contains filtered or unexported fields
}

AnalyticsService reads the caller's org usage snapshot from GET /v1/org/analytics. The org is resolved from the API key — there is no input.

func (s *AnalyticsService) GetOrg(ctx context.Context) (*OrgAnalytics, error)

type AudioStreamOptions ¶ added in v0.3.0

type AudioStreamOptions struct {
	APIURL string
	Token  string

	// SessionID ties this audio stream to a conversation. Pass the same
	// value to the companion WebhookStreamSession so the flow sees them
	// as one session_key. Empty → SDK mints a random one.
	SessionID string

	// Codec must be one of SupportedAudioCodecs. Defaults to "pcm16".
	Codec string

	// SampleRate is required when Codec == "pcm16" so the STT provider
	// knows the rate of the frames. Leave 0 for container codecs.
	SampleRate int

	// ReadyTimeout caps how long Connect blocks waiting for the server's
	// `ready` JSON frame. Default 10s.
	ReadyTimeout time.Duration
}

AudioStreamOptions configures an upstream-only audio session that pushes raw PCM (or other supported codec) chunks to Daguito's /v1/audio/:session_id WebSocket. Transcript / flow events arrive over the companion WebhookStreamSession on /v1/webhooks/:id/stream.

type AudioStreamReady ¶ added in v0.3.0

type AudioStreamReady struct {
	SessionKey string         `json:"session_key"`
	Codec      string         `json:"codec"`
	Guards     map[string]any `json:"guards,omitempty"`
}

AudioStreamReady carries the server-confirmed session metadata returned in the first JSON frame after a successful handshake.

type AudioStreamSession ¶ added in v0.3.0

type AudioStreamSession struct {
	// contains filtered or unexported fields
}

AudioStreamSession is a long-lived upstream audio channel.

Lifecycle:

s := NewAudioStreamSession(opts)
if err := s.Connect(ctx); err != nil { ... }
defer s.Close()
for chunk := range mic.Chunks() {
    if err := s.SendAudio(ctx, chunk); err != nil { ... }
}

SendAudio is safe to call from a single goroutine; concurrent senders must serialize themselves. Connect / Close are safe for concurrent use.

func NewAudioStreamSession(opts AudioStreamOptions) *AudioStreamSession

func (s *AudioStreamSession) Close() error

func (s *AudioStreamSession) Connect(ctx context.Context) error

func (s *AudioStreamSession) Pause(ctx context.Context) error

func (s *AudioStreamSession) Ready() *AudioStreamReady

func (s *AudioStreamSession) Resume(ctx context.Context) error

func (s *AudioStreamSession) SendAudio(ctx context.Context, chunk []byte) error

func (s *AudioStreamSession) SendControl(ctx context.Context, control string) error

func (s *AudioStreamSession) SessionID() string

type BudgetsService ¶ added in v0.3.0

type BudgetsService struct {
	// contains filtered or unexported fields
}

BudgetsService manages the org-level monthly budget. Per-key budgets live on AccountKeysService.SetBudget / PublicKeysService.SetBudget.

func (s *BudgetsService) GetOrg(ctx context.Context) (*OrgBudget, error)

func (s *BudgetsService) SetOrg(
	ctx context.Context, monthlyBudgetMicroUsd *int64,
) (*OrgBudget, error)

type Client ¶ added in v0.3.0

type Client struct {
	APIURL string
	APIKey string

	AccountKeys *AccountKeysService
	PublicKeys  *PublicKeysService
	Budgets     *BudgetsService
	Flows       *FlowsService
	Templates   *TemplatesService
	Models      *ModelsService
}

Client is the top-level admin client. It bundles the sub-services against the Daguito admin REST surface:

client.AccountKeys.List(ctx)
client.PublicKeys.Create(ctx, flowID, daguito.CreatePublicKeyInput{...})
client.Budgets.GetOrg(ctx)
client.Flows.UpsertAgent(ctx, daguito.AgentFlowSpec{...})

Auth uses a `dgsk_acc_…` account key (the dashboard session JWT is also accepted server-side). The existing top-level helpers — RunWebhook, WebhookStreamSession, KnowledgeSession, UploadFile — are unchanged; the Client is purely additive for management workflows.

func NewClient(opts ClientOptions) (*Client, error)

type ClientOptions ¶ added in v0.3.0

type ClientOptions struct {
	// APIURL is the Daguito ingest gateway root. When empty, NewClient falls
	// back to DefaultAPIURL.
	APIURL string
	APIKey string
	// HTTPClient is an optional override. When nil, NewClient uses
	// http.DefaultClient.
	HTTPClient *http.Client
}

ClientOptions configures NewClient.

type ClosedEvent ¶

type ClosedEvent struct {
	Code   int
	Reason string
}

ClosedEvent fires when the transport closes. Code/Reason are best-effort — some closures (peer drop, network) leave them empty.

type CreateAccountKeyInput ¶ added in v0.3.0

type CreateAccountKeyInput struct {
	Name                  string `json:"name"`
	MonthlyBudgetMicroUsd *int64 `json:"monthly_budget_micro_usd,omitempty"`
}

CreateAccountKeyInput is the request body for AccountKeys.Create.

Pass a pointer for MonthlyBudgetMicroUsd so callers can distinguish "no cap" (nil) from "explicit zero" — the wire shape needs the same distinction.

type CreateKnowledgeSourceInput ¶ added in v0.5.2

type CreateKnowledgeSourceInput struct {
	OrgID       string `json:"org_id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Kind        string `json:"kind,omitempty"`
}

CreateKnowledgeSourceInput is the request body for CreateSource. Kind is one of "url", "file", "text", "sitemap"; the server defaults to "text" when empty.

type CreatePublicKeyInput ¶ added in v0.3.0

type CreatePublicKeyInput struct {
	Name                  string   `json:"name"`
	AllowedOrigins        []string `json:"allowed_origins"`
	MonthlyBudgetMicroUsd *int64   `json:"monthly_budget_micro_usd,omitempty"`
}

CreatePublicKeyInput is the request body for PublicKeys.Create.

type DeleteChunksByMetadataInput ¶ added in v0.5.2

type DeleteChunksByMetadataInput struct {
	MetadataKey   string
	MetadataValue string
}

DeleteChunksByMetadataInput targets every chunk in a source whose metadata key equals the given value. Idempotent — DeletedCount=0 when nothing matches.

type DeleteChunksByMetadataResult ¶ added in v0.5.2

type DeleteChunksByMetadataResult struct {
	DeletedCount int `json:"deleted_count"`
}

DeleteChunksByMetadataResult is the response of DeleteChunksByMetadata.

type ErrorEvent ¶

type ErrorEvent struct {
	Message string
}

ErrorEvent carries a protocol-level error (auth failure, malformed frame, etc.). It is not the same as NodeFailedEvent / FlowFailedEvent — those are flow-execution failures.

type EventType ¶

type EventType string

EventType is the wire-level event name for a StreamEvent. Mirrors the Python `StreamEvent` literal union.

const (
	EventReady         EventType = "ready"
	EventClosed        EventType = "closed"
	EventNodeStarted   EventType = "node.started"
	EventNodeToken     EventType = "node.token"
	EventNodeCompleted EventType = "node.completed"
	EventNodeFailed    EventType = "node.failed"
	EventNodeEmit      EventType = "node.emit"
	EventFlowCompleted EventType = "flow.completed"
	EventFlowFailed    EventType = "flow.failed"
	EventError         EventType = "error"
)

type FlowCompletedEvent ¶

type FlowCompletedEvent struct {
	ElapsedMs int
	Output    any
}

FlowCompletedEvent fires when the engine finishes the run. ElapsedMs is measured client-side from session.started.

type FlowFailedEvent ¶

type FlowFailedEvent struct {
	Error string
}

FlowFailedEvent fires when the engine errors out.

type FlowGraph ¶ added in v0.4.1

type FlowGraph struct {
	Nodes []FlowGraphNode `json:"nodes"`
	Edges []FlowGraphEdge `json:"edges"`
	// CoalesceEnabled, when set to false, disables the inbound coalesce
	// debounce + dedup for this flow — same flag as AgentFlowSpec, but for
	// custom graphs. Declared here so a graph JSON can carry it inline.
	// Nodes may omit `position`; the server auto-lays-out any that do, so a
	// minimal graph is just nodes + edges. Defaults to true when nil.
	CoalesceEnabled *bool `json:"coalesce_enabled,omitempty"`
}

FlowGraph is a complete node/edge graph for a custom flow.

type FlowGraphEdge ¶ added in v0.4.1

type FlowGraphEdge struct {
	ID           string `json:"id"`
	Source       string `json:"source"`
	Target       string `json:"target"`
	SourceHandle string `json:"sourceHandle,omitempty"`
}

FlowGraphEdge wires one node's output to another node's input.

type FlowGraphNode ¶ added in v0.4.1

type FlowGraphNode struct {
	ID       string         `json:"id"`
	Type     string         `json:"type,omitempty"`
	Kind     string         `json:"kind,omitempty"`
	Config   map[string]any `json:"config,omitempty"`
	Position *FlowNodePos   `json:"position,omitempty"`
}

FlowGraphNode is one node of a custom flow graph. `Config` carries the node's `step_type` plus every step-specific field — its shape depends on the step type, so it stays a free-form map.

type FlowNodePos ¶ added in v0.4.1

type FlowNodePos struct {
	X float64 `json:"x"`
	Y float64 `json:"y"`
}

FlowNodePos is the editor canvas position of a node (cosmetic).

type FlowResult ¶ added in v0.4.1

type FlowResult struct {
	FlowID    string `json:"flow_id"`
	Slug      string `json:"slug"`
	Name      string `json:"name"`
	WebhookID string `json:"webhook_id"`
	Created   bool   `json:"created"`
}

FlowResult is what the server returns from UpsertFlow.

type FlowSpec ¶ added in v0.4.1

type FlowSpec struct {
	Slug string `json:"slug"`
	Name string `json:"name"`
	// TriggerType for the flow row; defaults to "message" server-side when
	// empty. Streaming consultations use "message".
	TriggerType string    `json:"trigger_type,omitempty"`
	Graph       FlowGraph `json:"graph"`
}

FlowSpec declares a flow as a full custom graph. Unlike AgentFlowSpec (the `trigger → ai_agent` preset), this carries any node/edge graph — STT pipelines, extraction chains, multi-branch flows. Identity is (org_id, slug); the org comes from the client's API key.

type FlowToolRef ¶ added in v0.3.0

type FlowToolRef struct {
	Kind         string         `json:"kind"`
	Name         string         `json:"name"`
	Config       map[string]any `json:"config,omitempty"`
	RequiresData *RequiresData  `json:"requires_data,omitempty"`
}

FlowToolRef declares a single tool the agent can call. Today only the `handler` kind (server-side registered tools like `search_knowledge`, `web_search`) is supported via this endpoint.

type FlowsService ¶ added in v0.3.0

type FlowsService struct {
	// contains filtered or unexported fields
}

FlowsService administers flow definitions on Daguito. Today exposes the "agent" preset (system_prompt + tools + model + memory + a trigger → agent graph built server-side). Full flow CRUD with custom graphs is Phase 3.

func (s *FlowsService) ResolveWebhook(
	ctx context.Context, slug string,
) (*ResolvedFlowWebhook, error)

func (s *FlowsService) UpsertAgent(
	ctx context.Context, spec AgentFlowSpec,
) (*AgentFlowResult, error)

func (s *FlowsService) UpsertFlow(
	ctx context.Context, spec FlowSpec,
) (*FlowResult, error)

type IngestJob ¶ added in v0.5.2

type IngestJob struct {
	JobID  string         `json:"job_id"`
	Status string         `json:"status"`
	OrgID  string         `json:"org_id,omitempty"`
	Raw    map[string]any `json:"-"`
}

IngestJob is the response of IngestURL / IngestText admin calls plus GetIngestJob. The shape mirrors the server's ingest-queue snapshot; extra fields (`progress`, `result`, …) ride through as Raw.

func (j *IngestJob) UnmarshalJSON(data []byte) error

type IngestTextAdminInput ¶ added in v0.5.2

type IngestTextAdminInput struct {
	Text     string         `json:"text"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

IngestTextAdminInput is the request body for IngestText on the admin surface. Identical shape to KnowledgeSession.IngestText but routed through `/api/public/knowledge/sources/:id/text`.

type IngestTextInput ¶

type IngestTextInput struct {
	Text     string
	Metadata map[string]any
	SourceID string // overrides DefaultSourceID when set
}

IngestTextInput is the input to KnowledgeSession.IngestText.

type IngestTextResult ¶

type IngestTextResult struct {
	SourceID   string
	ChunkCount int
	TokenCount int
}

IngestTextResult is the response of a successful text-ingest.

type IngestURLInput ¶ added in v0.5.2

type IngestURLInput struct {
	URL      string         `json:"url"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

IngestURLInput is the request body for IngestURL.

type KnowledgeBase ¶ added in v0.5.2

type KnowledgeBase struct {
	ID                string  `json:"id"`
	Name              string  `json:"name"`
	Description       *string `json:"description"`
	Dim               int     `json:"dim"`
	TenancyTier       string  `json:"tenancy_tier"`
	EmbeddingProvider string  `json:"embedding_provider"`
	EmbeddingModel    string  `json:"embedding_model"`
}

KnowledgeBase is the wire shape of a knowledge_bases row returned by GET /api/public/knowledge/bases.

type KnowledgeService ¶ added in v0.5.2

type KnowledgeService struct {
	// contains filtered or unexported fields
}

KnowledgeService is the management surface for knowledge bases and sources. It uses the `dgsk_acc_…` / `sk_dgt_…` account credential bound to the org — every call resolves the org server-side.

The data-plane KB session (text ingest + search via a per-source `sk_dgt_…` key) lives separately in KnowledgeSession; both can be used independently or together.

func (s *KnowledgeService) CreateSource(
	ctx context.Context, in CreateKnowledgeSourceInput,
) (*KnowledgeSource, error)

func (s *KnowledgeService) DeleteChunksByMetadata(
	ctx context.Context, sourceID string, in DeleteChunksByMetadataInput,
) (*DeleteChunksByMetadataResult, error)

func (s *KnowledgeService) DeleteSource(ctx context.Context, sourceID string) error

func (s *KnowledgeService) GetIngestJob(
	ctx context.Context, jobID string,
) (*IngestJob, error)

func (s *KnowledgeService) IngestText(
	ctx context.Context, sourceID string, in IngestTextAdminInput,
) (*IngestJob, error)

func (s *KnowledgeService) IngestURL(
	ctx context.Context, sourceID string, in IngestURLInput,
) (*IngestJob, error)

func (s *KnowledgeService) ListBases(
	ctx context.Context, opts ListKnowledgeOptions,
) ([]KnowledgeBase, error)

func (s *KnowledgeService) ListSources(
	ctx context.Context, opts ListKnowledgeOptions,
) ([]KnowledgeSource, error)

func (s *KnowledgeService) UpdateChunksMetadata(
	ctx context.Context, sourceID string, in UpdateChunksMetadataInput,
) (*UpdateChunksMetadataResult, error)

type KnowledgeSession ¶

type KnowledgeSession struct {
	// contains filtered or unexported fields
}

KnowledgeSession is an HTTP client for the Daguito KB ingest + search endpoints. It is safe to reuse across goroutines.

func NewKnowledgeSession(opts KnowledgeSessionOptions) *KnowledgeSession

func (s *KnowledgeSession) IngestText(ctx context.Context, in IngestTextInput) (*IngestTextResult, error)

func (s *KnowledgeSession) Search(ctx context.Context, in SearchInput) (*SearchResult, error)

type KnowledgeSessionOptions ¶

type KnowledgeSessionOptions struct {
	APIURL          string
	APIKey          string // sk_dgt_... — kb:read / kb:write scoped key
	DefaultSourceID string // optional default sourceId for IngestText
	Timeout         time.Duration
	HTTPClient      *http.Client
}

KnowledgeSessionOptions configures a KnowledgeSession.

type KnowledgeSource ¶ added in v0.5.2

type KnowledgeSource struct {
	ID          string  `json:"id"`
	OrgID       string  `json:"org_id"`
	KbID        string  `json:"kb_id"`
	Name        string  `json:"name"`
	Description *string `json:"description"`
	Kind        string  `json:"kind"`
	Status      string  `json:"status"`
	ChunkCount  int     `json:"chunk_count"`
	TokenCount  int     `json:"token_count"`
	SourceCount int     `json:"source_count,omitempty"`
	CreatedAt   string  `json:"created_at"`
	UpdatedAt   string  `json:"updated_at"`
}

KnowledgeSource is the rolled-up "one card per kb" shape the dashboard endpoint returns. ID is the latest underlying source row id; SourceCount reveals how many raw sources were merged.

type ListKnowledgeOptions ¶ added in v0.5.2

type ListKnowledgeOptions struct {
	OrgID string
}

ListKnowledgeOptions is the input to ListBases / ListSources. OrgID is required — the server enforces it against the calling key.

type MediaKind ¶

type MediaKind string

MediaKind enumerates the message kinds that carry an uploaded attachment. The values match the canonical MessageKind enum in @daguito/core (packages/core/src/messages/kinds.ts).

const (
	MediaKindImage    MediaKind = "image"
	MediaKindAudio    MediaKind = "audio"
	MediaKindDocument MediaKind = "document"
	MediaKindVideo    MediaKind = "video"
)

type Model ¶ added in v0.5.2

type Model struct {
	Provider    string `json:"provider"`
	ID          string `json:"model_id"`
	DisplayName string `json:"display_name"`
	Tier        string `json:"tier,omitempty"`
}

Model is one curated LLM entry. ID is the `<provider>/<model>` string that flow node configs expect (e.g. `google/gemini-3.5-flash`). DisplayName + Tier are UI hints — Tier is the free-form bucket the dashboard surfaces ("fast", "balanced", "smart"), empty when the operator hasn't tagged it.

type ModelsService ¶ added in v0.5.2

type ModelsService struct {
	// contains filtered or unexported fields
}

ModelsService wraps the `/v1/models` endpoint. The endpoint returns the curated LLM picker list — the same rows the dashboard's flow builder shows — so SDK / MCP integrations can render a model selector and pass the chosen id into flow node configs (e.g. `ai_agent.model`, pre-recorded / realtime LLM nodes inside graph flows).

Auth is the same `dgsk_acc_…` bearer key used by the other admin services — the list is scoped to the caller's org.

func (s *ModelsService) List(ctx context.Context) ([]Model, error)

type NodeCatalog ¶ added in v0.5.2

type NodeCatalog = map[string]any

NodeCatalog is the raw catalog the server returns. Its shape evolves frequently (new node kinds, new descriptors), so the SDK keeps it as a pass-through map — callers index by `step_type` and read whatever fields they need without coupling to a frozen Go struct.

type NodeCompletedEvent ¶

type NodeCompletedEvent struct {
	NodeID     string
	DurationMs int
	Output     any
}

NodeCompletedEvent fires when a node finishes successfully. DurationMs is populated when the server reports it; Output may be any JSON-shaped value.

type NodeEmitEvent ¶

type NodeEmitEvent struct {
	NodeID string
	Kind   string
	Data   map[string]any
}

NodeEmitEvent carries custom telemetry. Kind discriminates the payload; common values: "tool_progress" (use ParseToolProgress), "intent", "agent.tool_call_started".

type NodeFailedEvent ¶

type NodeFailedEvent struct {
	NodeID string
	Error  string
}

NodeFailedEvent fires when a node errors out.

type NodeStartedEvent ¶

type NodeStartedEvent struct {
	NodeID string
}

NodeStartedEvent fires when the engine enters a flow node.

type NodeTokenEvent ¶

type NodeTokenEvent struct {
	NodeID string
	Text   string
}

NodeTokenEvent carries a single LLM token (or the smallest unit the model streamed). Concatenate Text across consecutive events to reconstruct the full response.

type NodesService ¶ added in v0.5.2

type NodesService struct {
	// contains filtered or unexported fields
}

NodesService reads the flow-builder node catalog. Backed by GET /api/public/nodes/catalog — no auth required, but the SDK still sends the bearer to match the rest of the surface.

func (s *NodesService) GetCatalog(ctx context.Context) (NodeCatalog, error)

type OrgAnalytics ¶ added in v0.5.2

type OrgAnalytics struct {
	OrgID         string            `json:"org_id"`
	LLMToday      OrgLLMUsage       `json:"llm_today"`
	MessagesToday OrgMessagesUsage  `json:"messages_today"`
	HTTPToday     OrgHTTPUsage      `json:"http_today"`
	Budget        OrgBudgetSnapshot `json:"budget"`
}

OrgAnalytics is the wire shape of GET /v1/org/analytics.

type OrgBudget ¶ added in v0.3.0

type OrgBudget struct {
	MonthlyBudgetMicroUsd *int64  `json:"monthly_budget_micro_usd"`
	CurrentMtdMicroUsd    int64   `json:"current_mtd_micro_usd"`
	MtdResetAt            *string `json:"mtd_reset_at"`
}

OrgBudget is the org-level spending state returned by Budgets.GetOrg.

type OrgBudgetSnapshot ¶ added in v0.5.2

type OrgBudgetSnapshot struct {
	OrgCapMicroUsd *int64 `json:"org_cap_micro_usd"`
	OrgMtdMicroUsd int64  `json:"org_mtd_micro_usd"`
	KeyCapMicroUsd *int64 `json:"key_cap_micro_usd"`
	KeyMtdMicroUsd int64  `json:"key_mtd_micro_usd"`
}

OrgBudgetSnapshot is the budget portion of OrgAnalytics. Caps are micro-USD (1e-6 USD) — same unit as the Budgets surface. Cap fields are pointers because the server returns JSON `null` when the cap is unset.

type OrgHTTPUsage ¶ added in v0.5.2

type OrgHTTPUsage struct {
	Total  int            `json:"total"`
	ByPath map[string]int `json:"by_path"`
}

OrgHTTPUsage is the HTTP request volume for the org over the current day.

type OrgLLMUsage ¶ added in v0.5.2

type OrgLLMUsage struct {
	Requests int     `json:"requests"`
	Tokens   int     `json:"tokens"`
	CostUSD  float64 `json:"cost_usd"`
}

OrgLLMUsage is today's LLM activity for the caller's org.

type OrgMessagesUsage ¶ added in v0.5.2

type OrgMessagesUsage struct {
	Inbound         map[string]int `json:"inbound"`
	OutboundLast24h int            `json:"outbound_last_24h"`
}

OrgMessagesUsage is the message volume snapshot returned by GetOrg. Inbound is keyed by channel (whatsapp, widget, instagram, …) — the SDK keeps it as a map so new channels show up without a code change.

type PublicKey ¶ added in v0.3.0

type PublicKey struct {
	ID                    string   `json:"id"`
	FlowID                string   `json:"flow_id"`
	Name                  string   `json:"name"`
	KeyPrefix             string   `json:"key_prefix"`
	AllowedOrigins        []string `json:"allowed_origins"`
	MonthlyBudgetMicroUsd *int64   `json:"monthly_budget_micro_usd"`
	CurrentMtdMicroUsd    int64    `json:"current_mtd_micro_usd"`
	CreatedAt             string   `json:"created_at"`
	LastUsedAt            *string  `json:"last_used_at"`
	RevokedAt             *string  `json:"revoked_at"`
}

PublicKey is the wire shape of a `dgpk_flow_…` browser-safe credential bound to a single flow + an allowed-origins allowlist.

type PublicKeyCreated ¶ added in v0.3.0

type PublicKeyCreated struct {
	PublicKey
	Plaintext string `json:"plaintext"`
}

PublicKeyCreated is the response of PublicKeys.Create.

type PublicKeysService ¶ added in v0.3.0

type PublicKeysService struct {
	// contains filtered or unexported fields
}

PublicKeysService manages `dgpk_flow_…` browser-safe keys per flow. Returned by Client.PublicKeys.

func (s *PublicKeysService) Create(
	ctx context.Context, flowID string, in CreatePublicKeyInput,
) (*PublicKeyCreated, error)

func (s *PublicKeysService) List(ctx context.Context, flowID string) ([]PublicKey, error)

func (s *PublicKeysService) Revoke(ctx context.Context, flowID, keyID string) error

func (s *PublicKeysService) SetBudget(
	ctx context.Context, flowID, keyID string, monthlyBudgetMicroUsd *int64,
) (*PublicKey, error)

type ReadyEvent ¶

type ReadyEvent struct {
	WebhookID string
}

ReadyEvent fires after the WS upgrade and bearer-token auth succeed.

type RequiresData ¶ added in v0.5.2

type RequiresData struct {
	// KBScope = true: hide unless the session's KB scope has any chunks.
	// Used by `search_knowledge` so the LLM doesn't call it before any
	// document has been indexed for the scope.
	KBScope bool `json:"kb_scope,omitempty"`
}

RequiresData gates a tool from the LLM until the named data is available on the session. Daguito hides the tool from the model when the gate is unmet, so the prompt stays clean of dead-end calls.

type ResolvedFlowWebhook ¶ added in v0.4.0

type ResolvedFlowWebhook struct {
	FlowID       string `json:"flow_id"`
	Slug         string `json:"slug"`
	Name         string `json:"name"`
	WebhookID    string `json:"webhook_id"`
	WebhookToken string `json:"webhook_token"`
}

ResolvedFlowWebhook is the streaming webhook a flow resolves to.

type SearchHit ¶

type SearchHit struct {
	ID       string
	SourceID string
	Content  string
	Score    float64
	Metadata map[string]any
}

SearchHit is a single chunk returned by the KB search.

type SearchInput ¶

type SearchInput struct {
	Query         string
	TopK          *int
	SourceIDs     []string
	EnableRewrite *bool
	EnableRerank  *bool
	EnableCache   *bool
}

SearchInput is the input to KnowledgeSession.Search. Set pointers via the helper constructors below — the SDK omits nil pointers from the wire body so server defaults apply.

type SearchResult ¶

type SearchResult struct {
	Hits           []SearchHit
	QueryOriginal  string
	QueryRewritten string
	Raw            map[string]any
}

SearchResult is the response of a KB search.

type SendableMessage ¶

type SendableMessage struct {
	Kind string `json:"kind"`
	Text string `json:"text,omitempty"`

	ImageURL  string   `json:"image_url,omitempty"`
	ImageURLs []string `json:"image_urls,omitempty"`

	MediaKey string `json:"media_key,omitempty"`
	// MediaURL is a short-lived presigned GET the integrator hosts in ITS OWN
	// storage. When set, Daguito fetches the bytes from here instead of signing
	// MediaKey against its own storage (client-owned media; see MediaRefSchema.url
	// in @daguito/core). MediaKey stays the stable identity that keys the
	// description cache / cross-turn memory.
	MediaURL  string `json:"media_url,omitempty"`
	MimeType  string `json:"mime_type,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`

	FormID  string         `json:"form_id,omitempty"`
	Payload map[string]any `json:"payload,omitempty"`
}

SendableMessage is the wire shape accepted by WebhookStreamSession.Send. In TypeScript this is a discriminated union; in Go we model it as a struct with optional fields and a Kind tag. Use the helper constructors below — they fill the correct subset of fields for each kind. The session wraps MediaKey/MimeType/SizeBytes into the nested `media` object Daguito expects inside `toInbound`.

Wire kinds:

• "text"
• "image" with ImageURL or MediaKey (pre-uploaded)
• "image-multi" with ImageURLs
• "audio" / "document" / "video" with MediaKey
• "form-response" with FormID + Payload

func FormResponseMessage(formID string, payload map[string]any) SendableMessage

func ImageMultiMessage(imageURLs []string, text string) SendableMessage

func ImageURLMessage(imageURL, text string) SendableMessage

func MediaKeyMessage(kind MediaKind, mediaKey, mimeType string, sizeBytes int64, text string) SendableMessage

func MediaURLMessage(kind MediaKind, key, mediaURL, mimeType string, sizeBytes int64, text string) SendableMessage

func TextMessage(text string) SendableMessage

type StreamEvent ¶

type StreamEvent struct {
	Type EventType

	Ready         *ReadyEvent
	Closed        *ClosedEvent
	NodeStarted   *NodeStartedEvent
	NodeToken     *NodeTokenEvent
	NodeCompleted *NodeCompletedEvent
	NodeFailed    *NodeFailedEvent
	NodeEmit      *NodeEmitEvent
	FlowCompleted *FlowCompletedEvent
	FlowFailed    *FlowFailedEvent
	Error         *ErrorEvent
}

StreamEvent is the sum type delivered on WebhookStreamSession.Events(). The Type field selects which of the typed payload pointers is populated; at most one is non-nil. Switch on Type when handling, or use the helper accessor methods.

type TemplateFieldDetail ¶ added in v0.4.3

type TemplateFieldDetail struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Type        string   `json:"type"`
	EnumValues  []string `json:"enum_values,omitempty"`
}

TemplateFieldDetail describes a single placeholder in the template, with the inferred type and (for enum fields) the candidate values.

type TemplatePreviewExample ¶ added in v0.4.3

type TemplatePreviewExample struct {
	Transcript       string         `json:"transcript"`
	TranscriptOrigin string         `json:"transcript_origin"`
	Extracted        map[string]any `json:"extracted"`
	Model            string         `json:"model"`
}

TemplatePreviewExample is the model-extracted example payload the server returns when an example transcript is available. Extracted is a free-form map keyed by placeholder name — its values come from the LLM and reflect the inferred schema.

type TemplatePreviewInput ¶ added in v0.4.3

type TemplatePreviewInput struct {
	TemplateBody    string `json:"template_body"`
	Vertical        string `json:"vertical,omitempty"`
	Model           string `json:"model,omitempty"`
	ForceRegenerate bool   `json:"force_regenerate,omitempty"`
}

TemplatePreviewInput is the request body for Preview. TemplateBody is required; every other field is optional.

type TemplatePreviewResult ¶ added in v0.4.3

type TemplatePreviewResult struct {
	TemplateSchema TemplateSchema           `json:"template_schema"`
	FieldNames     []string                 `json:"field_names"`
	FieldCount     int                      `json:"field_count"`
	FieldsDetail   []TemplateFieldDetail    `json:"fields_detail"`
	Example        *TemplatePreviewExample  `json:"example"`
	Warnings       []TemplatePreviewWarning `json:"warnings"`
	BodyHash       string                   `json:"body_hash"`
}

TemplatePreviewResult is what the server returns from POST /v1/templates/preview. Example is nil when the API did not run the extractor (e.g. no transcript supplied + Generate disabled). BodyHash is a stable digest of the input template body — callers can use it as a cache key for downstream LLM prompts.

type TemplatePreviewWarning ¶ added in v0.4.3

type TemplatePreviewWarning struct {
	Code    string `json:"code"`
	Field   string `json:"field,omitempty"`
	Message string `json:"message"`
	Hint    string `json:"hint,omitempty"`
}

TemplatePreviewWarning is a non-fatal hint emitted by the parser (placeholder with no body, duplicate name, etc).

type TemplateSchema ¶ added in v0.4.3

type TemplateSchema struct {
	Name   string         `json:"name"`
	Schema map[string]any `json:"schema"`
}

TemplateSchema is the JSON schema inferred from the template body. Schema mirrors the JSON Schema object the API returns — kept as a generic map because callers compose it into LLM tool definitions.

type TemplatesService ¶ added in v0.4.3

type TemplatesService struct {
	// contains filtered or unexported fields
}

TemplatesService wraps the `/v1/templates/preview` endpoint. The endpoint inspects a template body that uses `[[natural-language description]]` placeholders, infers a JSON schema for it, and (when the server decides to run the extractor) asks the model to extract a sample payload. The placeholder body is plain description — there is no `| type` syntax, the model infers the field type downstream.

Auth is the same `dgsk_acc_…` bearer key used by FlowsService — templates run in the org bound to the account key.

func (s *TemplatesService) Preview(
	ctx context.Context, in TemplatePreviewInput,
) (*TemplatePreviewResult, error)

type ToolHandler ¶

type ToolHandler func(ctx context.Context, args json.RawMessage) (any, error)

ToolHandler runs locally when the agent invokes a registered tool. Return any JSON-serialisable value as the tool result. Return an error to surface a failure to the LLM.

type ToolProgressEvent ¶

type ToolProgressEvent struct {
	Tool     string
	Stage    string
	Progress float64 // 0..1; -1 when not reported
	Resource *ToolProgressResource
	Result   *ToolProgressResult
	TraceID  string
	Attempt  int
}

ToolProgressEvent is the typed view over a NodeEmitEvent whose Kind is "tool_progress". Returned by ParseToolProgress. Consumers compose the user-facing copy from (Tool, Stage, Resource, Result) via their own i18n layer — the SDK never localises strings.

func ParseToolProgress(evt *NodeEmitEvent) *ToolProgressEvent

type ToolProgressItem ¶

type ToolProgressItem struct {
	Title   string
	Snippet string
	URL     string
}

ToolProgressItem is one hit in a search-like tool result.

type ToolProgressResource ¶

type ToolProgressResource struct {
	Kind     string
	Name     string
	MediaKey string
	URL      string
}

ToolProgressResource describes what a tool is operating on. Every field is optional — the server only fills what's relevant for the stage.

type ToolProgressResult ¶

type ToolProgressResult struct {
	Summary string
	Items   []ToolProgressItem
}

ToolProgressResult carries the data the tool produced. Summary is the raw caption/transcript text for a single-resource tool; Items lists multiple hits for search-like tools.

type ToolSpec ¶

type ToolSpec struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
	// TimeoutMS caps how long the SDK waits for the local handler before
	// reporting a tool error back to the LLM. Defaults to 30s.
	TimeoutMS int `json:"client_timeout_ms,omitempty"`
}

ToolSpec is the OpenAI-shaped declaration the LLM sees. Parameters is a JSON Schema fragment (typically `{"type":"object","properties":{...}}`).

type UpdateChunksMetadataInput ¶ added in v0.5.2

type UpdateChunksMetadataInput struct {
	Match UpdateChunksMetadataMatch
	Patch map[string]any
}

UpdateChunksMetadataInput patches every chunk in a source that matches Match. Patch keys overwrite, others are preserved (shallow merge).

type UpdateChunksMetadataMatch ¶ added in v0.5.2

type UpdateChunksMetadataMatch struct {
	MetadataKey   string
	MetadataValue string
}

UpdateChunksMetadataMatch is the matcher passed to UpdateChunksMetadata.

type UpdateChunksMetadataResult ¶ added in v0.5.2

type UpdateChunksMetadataResult struct {
	UpdatedCount int `json:"updated_count"`
}

UpdateChunksMetadataResult is the response of UpdateChunksMetadata.

type UploadInput ¶

type UploadInput struct {
	APIURL    string
	WebhookID string
	Token     string
	Kind      MediaKind
	Path      string
	Data      []byte
	Filename  string
	MimeType  string
	Timeout   time.Duration // optional; defaults to 30s
	// HTTPClient is an optional override. When nil, UploadFile uses
	// http.DefaultClient.
	HTTPClient *http.Client
}

UploadInput is the input to UploadFile. Exactly one of Path or Data must be set. When Data is provided, Filename is required (used for both the extension-based MIME fallback and the storage key suffix).

type UploadResult ¶

type UploadResult struct {
	MediaKey     string
	MimeType     string
	SizeBytes    int64
	ExpiresInSec int
}

UploadResult is the output of a successful presign + PUT.

func UploadFile(ctx context.Context, input UploadInput) (*UploadResult, error)

type WebhookRunInput ¶

type WebhookRunInput struct {
	APIURL  string
	Token   string
	Input   map[string]any
	Timeout time.Duration // optional; defaults to 90s
	// HTTPClient is an optional override. When nil, RunWebhook uses
	// http.DefaultClient with the configured timeout applied via context.
	HTTPClient *http.Client
}

WebhookRunInput is the input to RunWebhook. ApiURL is the Daguito ingest gateway root (e.g. https://ingest.daguito.com); Token is the raw sk_wh_... bearer.

type WebhookRunResult ¶

type WebhookRunResult struct {
	OK          bool
	ExecutionID string
	Status      string
	Output      any
}

WebhookRunResult is the typed response of /h/:token. Output is the JSON value the flow produced — its shape is flow-dependent.

func RunWebhook(ctx context.Context, input WebhookRunInput) (*WebhookRunResult, error)

type WebhookRunStreamInput ¶ added in v0.5.5

type WebhookRunStreamInput struct {
	APIURL string
	// WebhookID is the streaming webhook id ("wh_..."). Resolve via
	// Client.Flows.ResolveWebhook when only the slug is known.
	WebhookID string
	// Token is the webhook bearer ("sk_wh_...").
	Token string
	// Input is the free-form payload forwarded to the flow as base_input.
	Input map[string]any
	// Text is the inline message text sent on the WS. Defaults to a single
	// space when empty — webhook agents typically read everything from
	// base_input and don't need a user-facing message.
	Text string
	// SessionKey is an optional caller-supplied id. A fresh uuid is minted
	// when empty.
	SessionKey string
	// Timeout caps how long the SDK waits for flow.completed. No default —
	// WS has no edge timeout, so this is opt-in.
	Timeout time.Duration
}

WebhookRunStreamInput is the input to RunWebhookStream. Mirrors WebhookRunInput but adds WebhookID (resolve via Client.Flows.ResolveWebhook) since the streaming surface lives at /v1/webhooks/:id/stream rather than /h/:token.

type WebhookRunStreamResult ¶ added in v0.5.5

type WebhookRunStreamResult struct {
	OK          bool
	ExecutionID string
	// Status is "completed", "failed" or "unknown".
	Status    string
	Output    any
	ElapsedMs int64
}

WebhookRunStreamResult mirrors WebhookRunResult plus ElapsedMs measured client-side from session.started to flow.completed.

func RunWebhookStream(ctx context.Context, input WebhookRunStreamInput) (*WebhookRunStreamResult, error)

type WebhookStreamOptions ¶

type WebhookStreamOptions struct {
	APIURL    string
	WebhookID string
	Token     string

	// SessionKey is an optional caller-supplied id for resuming a session.
	// When empty, the SDK mints a random one.
	SessionKey string

	// BaseInput is applied to every send when the caller doesn't pass one
	// explicitly. Useful for static metadata (user_id, locale, …).
	BaseInput map[string]any

	// Scope is the server-enforced metadata filter for KB searches in this
	// session. Only primitive values (string, int, float, bool) are
	// forwarded — arrays/objects are silently dropped at the wire boundary.
	// The LLM never sees these values; Daguito injects them at the tool
	// boundary so a hallucinated id can't widen scope or leak across
	// conversations.
	Scope map[string]any

	// AutoReconnect re-opens the socket transparently on unexpected drops.
	// Reuses the same SessionKey so the daguito server resumes the running
	// flow execution — consumers don't see an EventClosed and Events() keeps
	// delivering. The new handshake re-sends session.start, then drains any
	// `pending` sends queued during the outage. Default false (opt-in) to
	// preserve the historical one-shot semantics for chatbot turns; long-
	// lived bridges (audio/video consultations, monitoring loops) should
	// flip this on.
	AutoReconnect bool
}

WebhookStreamOptions configures a WebhookStreamSession.

type WebhookStreamSession ¶

type WebhookStreamSession struct {
	// contains filtered or unexported fields
}

WebhookStreamSession is a long-lived bidirectional session for streaming webhooks (WS /v1/webhooks/:id/stream).

Lifecycle:

s := NewWebhookStreamSession(opts)
if err := s.Connect(ctx); err != nil { ... }
defer s.Close()
for evt := range s.Events() {
    switch evt.Type {
    case EventNodeToken: ...
    case EventFlowCompleted: return
    }
}

All methods are safe for concurrent use. Events() is single-consumer — call it once per session.

func NewWebhookStreamSession(opts WebhookStreamOptions) *WebhookStreamSession

func (s *WebhookStreamSession) Close() error

func (s *WebhookStreamSession) Connect(ctx context.Context) error

func (s *WebhookStreamSession) Events() <-chan StreamEvent

func (s *WebhookStreamSession) RegisterTool(spec ToolSpec, handler ToolHandler) error

func (s *WebhookStreamSession) Send(ctx context.Context, msg SendableMessage, baseInput map[string]any) error

func (s *WebhookStreamSession) SendRaw(ctx context.Context, frame map[string]any) error