SDK Go (floopy-go)

Visao Geral

O floopy-go e o SDK Go oficial do Floopy. Ele encapsula o pacote oficial openai-go e o aponta para o gateway do Floopy, entao Chat, Embeddings e Models continuam sendo um substituto direto 1:1, enquanto os recursos exclusivos do Floopy (auditoria, experimentos, constraints, exportacao de decisoes, feedback, roteamento em dry-run, sessoes) ganham metodos tipados de primeira classe.

Prefere a abordagem sem SDK? A pagina Go mostra como usar o cliente go-openai puro com os headers do Floopy. Use o floopy-go quando voce tambem quiser os recursos tipados do Floopy e um unico cliente para ambos.

Um unico *floopy.Client e seguro para uso concorrente e compartilhado entre goroutines; toda chamada recebe um context.Context. Nao existe um cliente assincrono separado (Go usa goroutines). Requer Go >= 1.23.

Instalacao

go get github.com/FloopyAI/floopy-go@latest

Inicio rapido

package main

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

  "github.com/FloopyAI/floopy-go"
  "github.com/openai/openai-go/v3"
)

func main() {
  client, err := floopy.NewClient(os.Getenv("FLOOPY_API_KEY"))
  if err != nil {
    log.Fatal(err)
  }

  resp, err := client.OpenAI().Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
    Model: openai.ChatModelGPT4o,
    Messages: []openai.ChatCompletionMessageParamUnion{
      openai.UserMessage("Ola do Floopy!"),
    },
  })
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Choices[0].Message.Content)
}

Defina FLOOPY_API_KEY no seu ambiente. Voce pode criar uma no dashboard.

Migrando do `openai-go`

import "github.com/openai/openai-go/v3"
import "github.com/openai/openai-go/v3/option"
client := openai.NewClient(option.WithAPIKey(os.Getenv("OPENAI_API_KEY")))
import "github.com/FloopyAI/floopy-go"
fl, _ := floopy.NewClient(os.Getenv("FLOOPY_API_KEY"))
client := fl.OpenAI()

resp, err := client.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{ /* ... */ })

client.OpenAI() retorna um *openai.Client construido sob demanda e ja apontado para o gateway, entao os tipos e o comportamento em runtime sao identicos. Atualizacoes de seguranca do SDK OpenAI chegam ate voce com go get -u, sem forks ou divergencia de versao.

Opcoes do Floopy

As floopy.Options mapeiam para headers Floopy-* e sao enviadas em todas as requisicoes (chamadas compativeis com OpenAI e tambem as exclusivas do Floopy). Sobrescritas por chamada estao disponiveis via um ...floopy.RequestOption no final de todo metodo de recurso.

client, _ := floopy.NewClient(os.Getenv("FLOOPY_API_KEY"),
  floopy.WithOptions(floopy.Options{
    Cache:              &floopy.CacheOptions{Enabled: floopy.Ptr(true), BucketMaxSize: floopy.Ptr(3)},
    PromptID:           "cd4249d5-44d5-46c8-8961-9eb3861e1f7e",
    PromptVersion:      "1",
    LLMSecurityEnabled: floopy.Ptr(true),
  }),
)

Opcao	Header	Proposito
`Cache.Enabled`	`Floopy-Cache-Enabled`	Liga cache exato + semantico
`Cache.BucketMaxSize`	`Floopy-Cache-Bucket-Max-Size`	Max. de entradas por bucket semantico
`PromptID`	`Floopy-Prompt-Id`	Prompt armazenado a resolver
`PromptVersion`	`Floopy-Prompt-Version`	Versao fixada para `PromptID`
`LLMSecurityEnabled`	`floopy-llm-security-enabled`	Pre-checagem do firewall LLM

Veja a Referencia de Headers para a lista completa.

Recursos exclusivos do Floopy

Cada recurso mapeia para um endpoint publico /v1/* do gateway e e tipado de ponta a ponta. Pages e Iterate sao iteradores range-over-func do Go 1.23 que retornam (valor, erro).

ctx := context.Background()

// Feedback
client.Feedback.Submit(ctx, floopy.FeedbackSubmitParams{Score: 9, Useful: true, SessionID: resp.ID})

// Decisoes (iteradores paginados)
d, _ := client.Decisions.Get(ctx, requestID)
for d, err := range client.Decisions.Iterate(ctx, floopy.DecisionListParams{From: since, Limit: 50}) {
  _ = d; _ = err
}

// Experimentos (header X-Floopy-Confirm: experiments automatico)
exp, _ := client.Experiments.Create(ctx, floopy.ExperimentCreateParams{
  Name:                  "cost-vs-quality",
  VariantARoutingRuleID: ruleA,
  VariantBRoutingRuleID: ruleB,
})
client.Experiments.Rollback(ctx, exp.ID)

// Constraints (PUT full-replace)
client.Constraints.Put(ctx, floopy.OrgConstraints{CostLimitMonthlyUSD: floopy.Ptr(100.0)})

// Exportacao (JSONL em streaming + trailer)
stream := client.Export.DecisionsWithTrailer(ctx, floopy.ExportDecisionsParams{From: start, To: end})
for row, err := range stream.Rows {
  _ = row; _ = err
}
fmt.Println(stream.Trailer())

// Avaliacoes
run, _ := client.Evaluations.Create(ctx, floopy.EvaluationCreateParams{DatasetID: dsID, Model: "gpt-4o"})
results, _ := client.Evaluations.Results(ctx, run.ID, 100, "")

// Roteamento em dry-run (plano Pro)
explain, _ := client.Routing.Explain(ctx, floopy.RoutingExplainParams{Model: "gpt-4o", Messages: messages})

// Sessoes — restaura uma conversa armazenada
session, _ := client.Sessions.Get(ctx, sessionID)
client.OpenAI().Chat.Completions.New(ctx, openai.ChatCompletionNewParams{
  Model: openai.ChatModelGPT4o, Messages: session.Messages,
})

Tratamento de Erros

Toda chamada exclusiva do Floopy retorna um subtipo de *floopy.FloopyError; ramifique com errors.As:

import "errors"

_, err := client.Export.Decisions(ctx, floopy.ExportDecisionsParams{From: start, To: end})
var rl *floopy.RateLimitError
var plan *floopy.PlanError
switch {
case errors.As(err, &rl):
  time.Sleep(time.Duration(max(rl.RetryAfterSeconds, 1)) * time.Second)
case errors.As(err, &plan):
  log.Printf("faca upgrade: recurso %s fora do plano atual", plan.Feature)
}

floopy.AsError(err) recupera o *floopy.FloopyError base de qualquer erro do Floopy. Erros de Chat / Embeddings sao emitidos pelo openai-go (*openai.Error), nao por este pacote.

Seguranca

A chave de API so e enviada no header Authorization; o SDK nunca registra corpos de requisicao ou resposta.
A verificacao de certificado TLS fica ativa por padrao (net/http).
As releases sao tags Git imutaveis verificadas pelo banco de checksums do Go (sum.golang.org) — nao ha conta de registry nem token de longa duracao no caminho de publicacao.

Veja o guia de Seguranca para controles do lado do gateway.