praixis

README

praixis-go

Go SDK for PraixisEngine — a FastAPI backend for local LLM chat sessions and RAG (retrieval-augmented generation) over your own documents.

Zero external dependencies. Stdlib only.

---

Installation

go get github.com/mettjs/praixis-go

Requires Go 1.22+.

---

Quick start

import (
    praixis "github.com/mettjs/praixis-go"
    "github.com/mettjs/praixis-go/chat"
    "github.com/mettjs/praixis-go/rag"
)

client := praixis.New("http://localhost:8080", "praixis_your_key")

The client exposes two sub-clients:

Field	Package	Purpose
client.Chat	chat	Chat sessions, file summarization, session history
client.RAG	rag	Vector collections, document Q&A, upload, embed

---

Chat

Streaming chat

stream, err := client.Chat.Stream(ctx, chat.Request{
    Prompt: "Explain Go interfaces in two sentences.",
})
if err != nil { /* handle */ }
defer stream.Close()

fmt.Println(stream.SessionID()) // assigned by the server

for stream.Next() {
    fmt.Print(stream.Token())
}
if err := stream.Err(); err != nil { /* handle */ }

Continue an existing session by passing SessionID:

stream, err := client.Chat.Stream(ctx, chat.Request{
    Prompt:    "Follow-up question",
    SessionID: previousSessionID,
})

Summarize a file (streaming)

f, _ := os.Open("report.pdf")
defer f.Close()

stream, err := client.Chat.SummarizeFile(ctx, "report.pdf", f, nil)
// or with options:
stream, err := client.Chat.SummarizeFile(ctx, "report.pdf", f,
    &chat.FileSummaryOptions{Task: "Extract action items", Tone: "Bullet points"},
)
defer stream.Close()

fmt.Println(stream.Filename())  // "report.pdf"
fmt.Println(stream.Progress())  // e.g. "reducing 4 chunks"
for stream.Next() {
    fmt.Print(stream.Token())
}
if stream.BackendError() != "" {
    // server-side error (e.g. GPU busy) reported inside the stream
}

Session management

// Fetch message history
history, err := client.Chat.History(ctx, sessionID)
for _, msg := range history.History {
    fmt.Printf("[%s] %s\n", msg.Role, msg.Content)
}

// List all active sessions
sessions, err := client.Chat.ActiveSessions(ctx)

// Delete a session
err = client.Chat.DeleteSession(ctx, sessionID)

---

RAG

Ask a question (streaming)

stream, err := client.RAG.Ask(ctx, rag.QuestionRequest{
    CollectionName: "hr-docs",
    Question:       "How many vacation days do employees get?",
})
if err != nil { /* handle */ }
defer stream.Close()

fmt.Println(stream.SessionID())   // session for follow-up questions
fmt.Println(stream.SearchQuery()) // reformulated query used for retrieval

for stream.Next() {
    fmt.Print(stream.Token())
}
if err := stream.Err(); err != nil { /* handle */ }

fmt.Println(stream.Sources()) // []string{"policy.pdf", "hr-handbook.docx"}

Upload documents

f, _ := os.Open("policy.pdf")
defer f.Close()

resp, err := client.RAG.Upload(ctx,
    []rag.FileUpload{{Filename: "policy.pdf", Data: f}},
    &rag.UploadOptions{
        CollectionName:   "hr-docs",
        ChunkingStrategy: "semantic", // or "character" for fixed-size splits
        ChunkSize:        praixis.Ptr(2000),
        ChunkOverlap:     praixis.Ptr(150), // only used when ChunkingStrategy is "character"
        ImprovedSearch:   true,             // background hypothetical-question indexing for better natural-language search
    },
)
// resp.Succeeded, resp.Results[i].Status

Pass nil for UploadOptions to use server defaults (collection "main", semantic chunking, chunk size 2000).

ImprovedSearch enables hypothetical-question indexing: questions are generated in the background after the upload returns, so the document is searchable immediately and natural-language matching improves once generation finishes.

Collections

// List all collections
list, err := client.RAG.ListCollections(ctx)
// list.ActiveCollections []string, list.TotalDocuments int

// Files in a collection
files, err := client.RAG.ListFiles(ctx, "hr-docs")

// Delete a file from a collection
err = client.RAG.DeleteFile(ctx, "hr-docs", "old-policy.pdf")

// Delete an entire collection
err = client.RAG.DeleteCollection(ctx, "hr-docs")

Summarize / compare files

// 3-sentence LLM summary of a stored file
summary, err := client.RAG.Summarize(ctx, "hr-docs", "policy.pdf")
fmt.Println(summary.Summary)

// Bullet-point diff between two files
cmp, err := client.RAG.Compare(ctx, "hr-docs", "policy-v1.pdf", "policy-v2.pdf")
fmt.Println(cmp.Comparison)

Embedding

resp, err := client.RAG.Embed(ctx, "some text to embed")
// resp.Embedding []float64 (384 dimensions), resp.Dimensions int

---

Error handling

_, err := client.Chat.Stream(ctx, chat.Request{Prompt: "hi"})

switch {
case praixis.IsGPUBusy(err):
    // 503 — server is processing another request; retry after a moment
case praixis.IsRateLimit(err):
    // 429 — slow down
case praixis.IsUnauthorized(err):
    // 401/403 — check your API key
case praixis.IsNotFound(err):
    // 404 — collection, file, or session does not exist
}

The helpers live on the top-level praixis package. For full detail, extract the typed error with errors.As:

var apiErr *praixis.APIError
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.StatusCode, apiErr.Message)
}

---

Configuration

client := praixis.New(baseURL, apiKey,
    praixis.WithTimeout(60*time.Second), // default 30s; does not affect streams
)

Streams are not subject to the HTTP timeout — cancel them via context.Context:

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
stream, err := client.Chat.Stream(ctx, ...)

---

Examples

Runnable examples are in _examples/:

Directory	Description
_examples/chat_stream	Stream a single chat turn
_examples/rag_ask	Ask a question over a collection
_examples/rag_upload	Upload a file into a collection

PRAIXIS_URL=http://localhost:8080 PRAIXIS_API_KEY=praixis_xxx go run ./_examples/chat_stream

---

Package layout

praixis-go/
├── praixis.go          # New(), Ptr(), error helpers (APIError, IsGPUBusy, …), Option types
├── chat/
│   ├── types.go        # Request, History, FileSummaryOptions, …
│   ├── stream.go       # ChatStream, FileSummaryStream
│   └── client.go       # Stream, SummarizeFile, History, ActiveSessions, DeleteSession
├── rag/
│   ├── types.go        # QuestionRequest, FileUpload, UploadOptions, …
│   ├── stream.go       # AskStream
│   └── client.go       # Ask, Upload, Embed, ListCollections, …
└── internal/
    ├── httpclient.go   # DoJSON, DoStream, DoMultipart, APIError, …
    └── stream.go       # StreamReader (metadata + token iterator)

---

License

MIT — see LICENSE.

Documentation

Overview

Package praixis is the top-level entry point for the Praixis Go SDK.

Create a client with your server URL and API key, then access the Chat and RAG sub-clients directly:

client := praixis.New("http://localhost:8080", "praixis_your_key")

// streaming chat
stream, err := client.Chat.Stream(ctx, chat.Request{Prompt: "Hello"})

// RAG question
stream, err := client.RAG.Ask(ctx, rag.QuestionRequest{
    CollectionName: "docs",
    Question:       "What is the refund policy?",
})

Index

• Constants
• func IsGPUBusy(err error) bool
• func IsNotFound(err error) bool
• func IsRateLimit(err error) bool
• func IsUnauthorized(err error) bool
• func Ptr[T any](v T) *T
• type APIError
• type Client
  • func New(baseURL, apiKey string, opts ...Option) *Client
• type Option
  • func WithTimeout(d time.Duration) Option

Constants

const DefaultTimeout = 30 * time.Second

DefaultTimeout is the HTTP request timeout applied to non-streaming requests. Streaming endpoints are not subject to this timeout; use context.Context instead.

Functions

func IsGPUBusy

func IsGPUBusy(err error) bool

IsGPUBusy reports whether err is a 503 response, meaning the server's GPU slots are exhausted. Retry after a short delay.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err is a 404 response — a collection, file, or session that does not exist (or belongs to another app).

func IsRateLimit

func IsRateLimit(err error) bool

IsRateLimit reports whether err is a 429 Too Many Requests response.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized reports whether err is a 401 or 403 response, usually meaning the API key is missing or invalid.

func Ptr

func Ptr[T any](v T) *T

Ptr returns a pointer to v. It is a convenience for setting optional pointer fields such as rag.UploadOptions.ChunkSize, since Go does not allow taking the address of a literal (e.g. &800 is invalid).

opts := &rag.UploadOptions{ChunkSize: praixis.Ptr(800)}

Types

type APIError

type APIError = internal.APIError

APIError is returned for any non-2xx HTTP response. It carries the HTTP status code and the server's error message. Use errors.As to extract it, or the IsGPUBusy / IsRateLimit / IsUnauthorized / IsNotFound helpers to test for common cases.

type Client

type Client struct {
	Chat *chat.Client
	RAG  *rag.Client
}

Client is the root Praixis SDK client. Access capabilities through the Chat and RAG fields.

func New

func New(baseURL, apiKey string, opts ...Option) *Client

New creates a Client pointed at baseURL, authenticating with apiKey. baseURL should not have a trailing slash (e.g. "http://localhost:8080").

type Option

type Option func(*options)

Option configures the Client.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout overrides the default HTTP request timeout (30 s). Streaming endpoints ignore this timeout — use context.Context for cancellation on streams.