palveron

README

palveron sdk-go

Official Go SDK for the Palveron AI Governance Gateway — policy enforcement, trace verification, and blockchain-anchored audit trails for every AI interaction.

---

Every AI interaction your Go service makes — governed, audited, and optionally anchored to the blockchain. Stdlib-only client.

• Zero dependencies — pure stdlib, ships in your binary at ~50 kB
• Multi-modal — text, images, audio, documents, code
• Enterprise-grade — retry with exponential backoff, circuit breaker, typed errors
• On-prem ready — point to any Palveron gateway endpoint

Installation

go get github.com/palveron/sdk-go@v1.0.0

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    palveron "github.com/palveron/sdk-go"
)

func main() {
    client := palveron.NewClient(os.Getenv("PALVERON_API_KEY"))

    result, err := client.Verify(context.Background(), &palveron.VerifyRequest{
        Prompt: "Transfer $50,000 to account DE89370400440532013000",
    })
    if err != nil {
        log.Fatal(err)
    }

    if result.Decision == palveron.Blocked {
        log.Fatalf("Blocked by policy: %s", result.Reason)
    }

    // Always use result.Output instead of the raw prompt so downstream
    // LLMs never see PII / secrets the gateway redacted.
    fmt.Println(result.Output, result.TraceID)
}

Features

• Policy enforcement — every prompt routed through your active guardrails before it reaches an LLM
• Trace verification — every decision logged with an integrity hash for tamper detection
• Multi-modal attachments — file helpers with auto MIME detection
• Agentic / MCP context — pass RequestContext so the audit trail captures the tool chain
• Blockchain attestation — high-severity traces anchored to Flare for cryptographic audit trails

Requirements

• Go 1.21 or newer
• No third-party runtime dependencies

Links

• Documentation — docs.palveron.com/sdks
• Dashboard — palveron.com
• Support — hello@palveron.com
• GitHub — palveron/sdk-go
• GoDoc — pkg.go.dev/github.com/palveron/sdk-go
• Changelog — CHANGELOG.md

License

MIT — Copyright © 2026 Palveron.

Documentation

Overview

Package palveron provides the official Go SDK for the PALVERON AI Governance Platform.

Usage:

client := palveron.NewClient("pv_live_xxx")
result, err := client.Verify(ctx, &palveron.VerifyRequest{
    Prompt: "User input here",
})
if err != nil {
    log.Fatal(err)
}
if result.Decision == palveron.Blocked {
    log.Fatalf("Blocked: %s", result.Reason)
}

Index

• Constants
• func IsAuthError(err error) bool
• func IsRateLimited(err error) bool
• type Attachment
  • func AttachmentFromFile(path string) (*Attachment, error)
• type Client
  • func NewClient(apiKey string, opts ...Option) *Client
  • func (c *Client) Check(ctx context.Context, prompt string) (*VerifyResponse, error)
  • func (c *Client) Health(ctx context.Context) (*HealthResponse, error)
  • func (c *Client) Verify(ctx context.Context, req *VerifyRequest) (*VerifyResponse, error)
  • func (c *Client) VerifyFile(ctx context.Context, prompt, path string) (*VerifyResponse, error)
• type Decision
• type Finding
• type HealthResponse
• type Option
  • func WithBaseURL(url string) Option
  • func WithHTTPClient(hc *http.Client) Option
  • func WithHeaders(h map[string]string) Option
  • func WithMaxRetries(n int) Option
  • func WithTimeout(d time.Duration) Option
• type PalveronError
  • func (e *PalveronError) Error() string
• type RequestContext
• type VerifyRequest
• type VerifyResponse
  • func (r *VerifyResponse) IsAllowed() bool
  • func (r *VerifyResponse) IsBlocked() bool
  • func (r *VerifyResponse) IsPendingApproval() bool
  • func (r *VerifyResponse) IsRateLimited() bool

Constants

const (
	Version        = "1.1.0"
	DefaultBaseURL = "https://gateway.palveron.com"
	DefaultTimeout = 30 * time.Second
)

Functions

func IsAuthError

func IsAuthError(err error) bool

IsAuthError returns true if the error is an authentication failure.

func IsRateLimited

func IsRateLimited(err error) bool

IsRateLimited returns true if the error is a rate limit.

Types

type Attachment

type Attachment struct {
	ContentType string                 `json:"content_type"`
	Data        string                 `json:"data"` // Base64
	Filename    string                 `json:"filename,omitempty"`
	Metadata    map[string]interface{} `json:"metadata,omitempty"`
}

Attachment represents a multi-modal file attachment.

func AttachmentFromFile

func AttachmentFromFile(path string) (*Attachment, error)

AttachmentFromFile creates an Attachment from a local file path.

type Client

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

Client is the PALVERON API client.

func NewClient

func NewClient(apiKey string, opts ...Option) *Client

NewClient creates a new PALVERON client.

func (*Client) Check

func (c *Client) Check(ctx context.Context, prompt string) (*VerifyResponse, error)

Check is a convenience method for text-only verification.

func (*Client) Health

func (c *Client) Health(ctx context.Context) (*HealthResponse, error)

Health checks the gateway health.

func (*Client) Verify

func (c *Client) Verify(ctx context.Context, req *VerifyRequest) (*VerifyResponse, error)

Verify sends a governance verification request.

Sprint 87 — the gateway maps the Decision field onto an HTTP status (200 PASSED / 202 PENDING_APPROVAL / 403 BLOCKED / 429 RATE_LIMITED). Verify treats all four as legitimate governance outcomes and returns a *VerifyResponse for each; it does not error on 403 or 429. Only transport, auth, validation, and 5xx failures return an error.

func (*Client) VerifyFile

func (c *Client) VerifyFile(ctx context.Context, prompt, path string) (*VerifyResponse, error)

VerifyFile verifies a prompt with a file attachment.

type Decision

type Decision string

Decision represents a governance decision returned by /api/v1/verify.

Sprint 87 — the gateway maps each Decision onto a matching HTTP status:

PASSED / ALLOWED / MODIFIED / FLAGGED / POLICY_CHANGE → 200 OK
PENDING_APPROVAL                                      → 202 Accepted
BLOCKED                                               → 403 Forbidden
RATE_LIMITED                                          → 429 Too Many Requests
ERROR                                                 → transport/internal failure

RATE_LIMITED is synthesised client-side when the gateway returns 429 with the tier-rate-limit body shape (no decision field) so callers can branch on Decision uniformly instead of also checking for errors.

const (
	Passed          Decision = "PASSED"
	Allowed         Decision = "ALLOWED"
	Blocked         Decision = "BLOCKED"
	Modified        Decision = "MODIFIED"
	Flagged         Decision = "FLAGGED"
	PendingApproval Decision = "PENDING_APPROVAL"
	PolicyChange    Decision = "POLICY_CHANGE"
	RateLimited     Decision = "RATE_LIMITED"
	Error           Decision = "ERROR"
)

type Finding

type Finding struct {
	Risk        string  `json:"risk"`
	Category    string  `json:"category"`
	Description string  `json:"description"`
	Confidence  float64 `json:"confidence"`
}

Finding represents a security finding from content analysis.

type HealthResponse

type HealthResponse struct {
	Status  string  `json:"status"`
	Version string  `json:"version"`
	Uptime  float64 `json:"uptime"`
}

HealthResponse represents the gateway health status.

type Option

type Option func(*Client)

Option configures the Client.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL sets a custom gateway URL (e.g., for on-prem).

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets a custom http.Client (for proxies, TLS config, etc.).

func WithHeaders

func WithHeaders(h map[string]string) Option

WithHeaders adds custom headers to every request.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets max retry attempts.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the request timeout.

type PalveronError

type PalveronError struct {
	Code       string
	Message    string
	StatusCode int
	RequestID  string
	Retryable  bool
}

PalveronError is the base error type for all SDK errors.

func (*PalveronError) Error

func (e *PalveronError) Error() string

type RequestContext

type RequestContext struct {
	MCPServer    string `json:"mcp_server,omitempty"`
	ToolName     string `json:"tool_name,omitempty"`
	ChainDepth   int    `json:"chain_depth,omitempty"`
	SourceSystem string `json:"source_system,omitempty"`
	SessionID    string `json:"session_id,omitempty"`
}

RequestContext provides agentic context for MCP/tool chains.

type VerifyRequest

type VerifyRequest struct {
	Prompt        string                 `json:"prompt"`
	ExtractedText string                 `json:"extracted_text,omitempty"`
	Metadata      map[string]interface{} `json:"metadata,omitempty"`
	Attachments   []Attachment           `json:"attachments,omitempty"`
	Context       *RequestContext        `json:"context,omitempty"`
}

VerifyRequest is the input for a governance check.

type VerifyResponse

type VerifyResponse struct {
	Decision      Decision  `json:"decision"`
	Output        string    `json:"output"`
	Reason        string    `json:"reason"`
	TraceID       string    `json:"trace_id"`
	IntegrityHash string    `json:"integrity_hash"`
	ShouldAnchor  bool      `json:"should_anchor"`
	FlareStatus   string    `json:"flare_status"`
	FlareTxHash   *string   `json:"flare_tx_hash"`
	ContentType   string    `json:"content_type"`
	Findings      []Finding `json:"findings"`
	LatencyMs     float64   `json:"-"` // Client-measured

	// RetryAfterMs is populated when Decision == RateLimited. Honour
	// it before issuing the next request. Derived from the gateway's
	// Retry-After header (in milliseconds).
	RetryAfterMs int64 `json:"-"`

	// HTTPStatus is the HTTP status code that produced this response
	// (200, 202, 403, 429). Useful for observability.
	HTTPStatus int `json:"-"`
}

VerifyResponse is the output of a governance check.

func (*VerifyResponse) IsAllowed

func (r *VerifyResponse) IsAllowed() bool

IsAllowed returns true if the decision is ALLOWED or PASSED.

func (*VerifyResponse) IsBlocked

func (r *VerifyResponse) IsBlocked() bool

IsBlocked returns true if the decision is BLOCKED.

func (*VerifyResponse) IsPendingApproval

func (r *VerifyResponse) IsPendingApproval() bool

IsPendingApproval returns true if the request is queued for human approval.

func (*VerifyResponse) IsRateLimited

func (r *VerifyResponse) IsRateLimited() bool

IsRateLimited returns true if the request was rejected by the tier rate-limit.