Sense

// Judge: output → pass/fail with evidence
sense.Assert(t, output).
 Expect("covers all sections from the brief").
 Expect("includes actionable recommendations").
 Run()
// Extract: unstructured text → typed struct
s := sense.New()
var m MountError
s.Extract("device /dev/sdf already mounted with vol-0abc123", &m).Run()
fmt.Println(m.Device) // "/dev/sdf"
fmt.Println(m.VolumeID) // "vol-0abc123"

Why it exists

Install

go get github.com/itsHabib/sense

export ANTHROPIC_API_KEY=...

Surfaces

Extract — structure from chaos

type MountError struct {
 Device string `json:"device" sense:"The device path"`
 VolumeID string `json:"volume_id" sense:"The EBS volume ID"`
 Message string `json:"message"`
}
s := sense.New()
var m MountError
_, err := s.Extract("device /dev/sdf already mounted with vol-0abc123", &m).
 Context("AWS EC2 EBS error messages").
 Run()
fmt.Println(m.Device) // "/dev/sdf"
fmt.Println(m.VolumeID) // "vol-0abc123"

result, err := sense.Extract[MountError]("device /dev/sdf already mounted with vol-0abc123").Run()
fmt.Println(result.Data.Device) // "/dev/sdf"

ExtractSlice — multiple items from one text

type LineItem struct {
 Description string `json:"description" sense:"Item description"`
 Quantity int `json:"quantity" sense:"Number of units"`
 UnitPrice float64 `json:"unit_price" sense:"Price per unit in dollars"`
}
result, err := sense.ExtractSlice[LineItem](invoiceText).
 Context("Invoice line items").
 Run()
for _, item := range result.Data {
 fmt.Printf("%s x%d @ $%.2f\n", item.Description, item.Quantity, item.UnitPrice)
}

result, err := sense.ExtractSlice[LineItem](text).
 Validate(func(item LineItem) error {
 if item.Quantity <= 0 {
 return fmt.Errorf("invalid quantity: %d", item.Quantity)
 }
 return nil
 }).
 Run()

ExtractParallel — many extractions at once

var mount MountError
var ticket TicketInfo
res := s.ExtractParallel(ctx, []sense.ExtractJob{
 {Text: logLine, Dest: &mount, Context: "AWS EBS error"},
 {Text: emailBody, Dest: &ticket, Context: "support email"},
})
if res.Failed() {
 for i, err := range res.Errors {
 if err != nil {
 log.Printf("job %d failed: %v", i, err)
 }
 }
}

Validation

result, err := sense.Extract[Order](text).
 Validate(func(o Order) error {
 if o.Total < 0 {
 return fmt.Errorf("invalid total: %f", o.Total)
 }
 return nil
 }).
 Run()

type Order struct {
 Total float64 `json:"total"`
 Items []Item `json:"items"`
}
func (o *Order) Validate() error {
 if o.Total < 0 {
 return fmt.Errorf("invalid total: %f", o.Total)
 }
 return nil
}
// Validate() is called automatically after unmarshalling.
result, err := sense.Extract[Order](text).Run()

Fallback

result, err := sense.Extract[MountError](logLine).
 Fallback(func() (*MountError, error) {
 return regexParseMountError(logLine)
 }).
 Run()
if result.Fallback {
 log.Warn("used fallback parser")
}

Use cases

// Parse log lines into typed events
var event DeployEvent
s.Extract(logLine, &event).Context("Kubernetes deployment logs").Run()
// Classify support tickets
var ticket TicketInfo
s.Extract(emailBody, &ticket).Context("Customer support emails for a SaaS product").Run()
// Normalize inconsistent API responses
var order Order
s.Extract(thirdPartyJSON, &order).Context("Legacy vendor API, format varies by region").Run()

Judge — evaluate non-deterministic output

Assert — test assertion, continues on failure

func TestMyAgent(t *testing.T) {
 output := runMyAgent()
 sense.Assert(t, output).
 Expect("produces valid Go code").
 Expect("handles errors idiomatically").
 Context("task was to write a REST API server").
 Run()
}

--- FAIL: TestMyAgent (4.82s)
 agent_test.go:15: evaluation: 1/2 passed, score: 0.50
 ✓ produces valid Go code
 reason: The snippet is syntactically valid Go code for a simple addition function.
 evidence: func Add(a, b int) int { return a + b }
 confidence: 0.95
 ✗ handles errors idiomatically
 reason: The output is a trivial math function with no error handling whatsoever.
 It does not demonstrate idiomatic Go error handling (e.g., returning an error
 as a second value, using fmt.Errorf, etc.), nor does it relate to a REST API
 server where error handling would be expected.
 evidence: func Add(a, b int) int { return a + b } — no error return value,
 no error handling logic, no REST API context
 confidence: 0.99

Require — test assertion, stops on failure

sense.Require(t, output).
 Expect("produces valid Go code").
 Run()

Eval — inspect results programmatically

result, err := sense.Eval(output).
 Expect("is a complete sentence").
 Expect("mentions an animal").
 Expect("contains a number").
 Judge()
fmt.Println(result.Pass) // false
fmt.Println(result.Score) // 0.67
for _, c := range result.FailedChecks() {
 fmt.Println(c.Expect, "—", c.Reason)
}

Confidence threshold

// Per call
sense.Eval(output).Expect("is factually accurate").MinConfidence(0.8).Judge()
// Or session-wide
s := sense.New(sense.WithMinConfidence(0.8))

Compare — A/B test two outputs

cmp, err := sense.Compare(outputV1, outputV2).
 Criteria("completeness").
 Criteria("clarity").
 Criteria("professionalism").
 Judge()
fmt.Println(cmp.Winner) // "A"
fmt.Println(cmp.ScoreA) // 0.85
fmt.Println(cmp.ScoreB) // 0.10
fmt.Println(cmp.Reasoning) // "Output A is significantly better..."

Session

// Zero config — just works
sense.Assert(t, output).Expect("covers all sections").Run()
// Test suite — auto-cleanup, usage tracking
s := sense.ForTest(t)
s.Assert(t, output).Expect("covers all sections").Run()
// Custom config
s := sense.New(sense.WithModel("claude-haiku-4-5-20251001"))
s.Assert(t, output).Expect("covers all sections").Run()

s := sense.New()
var m MountError
s.Extract("device /dev/sdf already mounted", &m).Run()
// Generic version (uses default session)
result, err := sense.Extract[MountError](logLine).Run()

Functional options

s := sense.New(
 sense.WithModel("claude-haiku-4-5-20251001"),
 sense.WithTimeout(10 * time.Second), // -1 or 0 disables the timeout
 sense.WithRetries(5), // -1 disables retries
 sense.WithAPIKey("sk-..."),
 sense.WithMemoryCache(), // in-memory response cache, lives with the session
 sense.WithMinConfidence(0.8), // demote low-confidence passes to failures
 sense.WithContext("you are reviewing API docs"), // prepended to every call
 sense.WithLogger(slog.Default()), // log calls, latencies, tokens, errors
 sense.WithHook(func(e sense.Event) { /* per-call callback */ }),
)

ForTest — auto-cleanup for test suites

s := sense.ForTest(t) // defaults
s := sense.ForTest(t, sense.WithModel("claude-haiku-4-5-20251001")) // custom
// t.Cleanup handles Close and prints usage summary

Usage tracking

s := sense.New()
// ... run evaluations ...
fmt.Println(s.Usage())
// sense: 15 calls, 18420 input tokens, 4210 output tokens (~0ドル.0612)

Batching

s := sense.New(sense.WithBatch(50, 2*time.Second))
defer s.Close() // required — flushes pending batch requests

Interfaces

// For code that judges output
func AnalyzeReport(s sense.Evaluator, doc string) (bool, error) {
 result, err := s.Eval(doc).
 Expect("has executive summary").
 Judge()
 if err != nil {
 return false, err
 }
 return result.Pass, nil
}
// For code that extracts structure
func ParseTicket(s sense.Extractor, raw string) (*Ticket, error) {
 var t Ticket
 _, err := s.Extract(raw, &t).Run()
 return &t, err
}

Architecture

 Extract[T] / ExtractSlice[T] / ExtractParallel Assert / Require / Eval / Compare
 (extract builders) (judge builders)
 \ /
 \ /
 ▼ ▼
 ┌─────────────────────────────────────────┐
 │ Session — model, timeout, retries, │
 │ usage counters, optional cache/batcher │
 └─────────────────────────────────────────┘
 │
 caller.call(...) ← the one seam
 │
 ┌──────────────┬──────────────┴───────┬───────────────┐
 ▼ ▼ ▼ ▼
 claudeClient batchCaller cachedCaller nopCaller
 (real API, (Anthropic Batch (decorator, (Nop(): {})
 retries, API, 50% cost) memory cache)
 forced tool,
 prompt cache)

How it works

Develop

go test ./... # unit tests — mock caller, no API, no key needed
go test -tags=e2e -v ./... # e2e — hits the real API, COSTS money (~0ドル.10–0.15/run)
SENSE_SKIP=1 go test ./... # offline — every sense call becomes a passing no-op
go tool golangci-lint run # lint (golangci-lint v2 pinned as a go.mod tool dependency)
go build ./...

Offline development

SENSE_SKIP=1 go test ./...

s := sense.Nop(sense.WithModel("claude-haiku-4-5-20251001"), sense.WithLogger(logger))

Environment variables

Docs

What's next