aistudio

Documentation

Overview

Package aistudio implements the `nself ai-studio` command subtree. SP-12.B36: Google AI Studio bridge via Cloudflare Tunnel + short-lived JWT + read-only enforcement.

Index

• Variables
• type BridgeSession
• type ColumnInfo
• type SchemaContext
• type TableInfo

Variables

var AiStudioCmd = &cobra.Command{
	Use:   "ai-studio",
	Short: "Google AI Studio integration for local nSelf instances",
	Long: `Integrate Google AI Studio with your local nSelf instance via a
secure Cloudflare Tunnel. Gemini can query your local Postgres schema
without any cloud deployment.`,
	RunE: func(cmd *cobra.Command, args []string) error { return cmd.Help() },
}

AiStudioCmd is the top-level `nself ai-studio` command.

var BridgeCmd = &cobra.Command{
	Use:   "bridge",
	Short: "Start a secure AI Studio bridge via Cloudflare Tunnel",
	Long: `Start a local proxy that exposes your nSelf instance to Google AI Studio
via an ephemeral Cloudflare Tunnel (trycloudflare.com — no account required).

The bridge:
  - Issues a short-lived session token (30-minute idle TTL) scoped to one project
  - Enforces schema READ-ONLY (no mutations, DDL, or DML through the tunnel)
  - Injects your Postgres schema as X-Nself-Schema-Context on every response
  - Auto-closes after 30 minutes of inactivity (--idle-timeout to override)
  - Optionally restricts access to specific IP CIDRs via --ip-allowlist

Usage in AI Studio:
  1. Run:  nself ai-studio bridge
  2. Copy the printed tunnel URL
  3. In AI Studio: Custom connector, paste the URL + Authorization header

Examples:
  nself ai-studio bridge
  nself ai-studio bridge --no-context
  nself ai-studio bridge --dry-run
  nself ai-studio bridge --ip-allowlist 192.168.1.0/24
  nself ai-studio bridge --idle-timeout 60`,
	RunE: runBridge,
}

BridgeCmd is the `nself ai-studio bridge` subcommand.

Types

type BridgeSession

type BridgeSession struct {
	TunnelURL  string    `json:"tunnel_url"`
	StartedAt  time.Time `json:"started_at"`
	RequestsN  int64     `json:"requests_n"`
	SchemaHash string    `json:"schema_hash,omitempty"`
	ProjectID  string    `json:"project_id,omitempty"`
}

BridgeSession holds runtime state for one active tunnel session.

type ColumnInfo

type ColumnInfo struct {
	Name     string `json:"name"`
	DataType string `json:"data_type"`
	Nullable bool   `json:"nullable"`
}

ColumnInfo holds column metadata.

type SchemaContext

type SchemaContext struct {
	Tables     []TableInfo `json:"tables"`
	ActiveRole string      `json:"active_role"`
	SchemaHash string      `json:"schema_hash,omitempty"`
	CapturedAt string      `json:"captured_at"`
}

SchemaContext is the payload injected in X-Nself-Schema-Context.

type TableInfo

type TableInfo struct {
	Name    string       `json:"name"`
	Schema  string       `json:"schema"`
	Columns []ColumnInfo `json:"columns"`
}

TableInfo holds minimal schema information for one table.