httpapi

Documentation

Overview

Package httpapi serves the 2dph brain over HTTP.

Async by design: every request runs on its own goroutine, and CPU-heavy searches are serialized through a bounded worker pool so N requests can't spawn N backends at once.

Used by bin/brain/serve.go. Tests inject a fake API (no exec, no ladybug).

Index

• Constants
• Variables
• func NewServer(api API, workers int) http.Handler
• func OpenAPI() map[string]any
• func Run(api API)
• func SkillMarkdown() string
• type API
• type ExecSearcher
  • func (ExecSearcher) Audit(context.Context) ([]byte, error)
  • func (ExecSearcher) Get(context.Context, string, bool) ([]byte, error)
  • func (b ExecSearcher) Ingest(ctx context.Context, body []byte) ([]byte, error)
  • func (b ExecSearcher) Search(ctx context.Context, query string, limit int, asOf string) ([]byte, error)
  • func (ExecSearcher) Stats(context.Context) ([]byte, error)
• type MCPTool
  • func MCPTools() []MCPTool
• type Op
• type Param
• type Server
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const (
	PathHealth  = "/health"
	PathSearch  = "/search"
	PathGet     = "/get"
	PathStats   = "/stats"
	PathAudit   = "/audit"
	PathIngest  = "/ingest"
	PathOpenAPI = "/openapi.json"
	PathMCP     = "/mcp"
)

Variables

var Ops = []Op{
	{Path: PathHealth, Method: "get", ID: "health", Summary: "liveness"},
	{
		Path: PathSearch, Method: "get", ID: "search", Summary: "deduction search (facts → info → web)",
		MCP: true,
		Params: []Param{
			{Name: "q", In: "query", Type: "string", Description: "search query", Required: true},
			{Name: "n", In: "query", Type: "integer", Description: "hit limit 1..100 (default 10)"},
			{Name: "as_of", In: "query", Type: "string", Description: "YYYY-MM-DD; keep facts active on that day (D24)"},
		},
	},
	{
		Path: PathGet, Method: "get", ID: "get", Summary: "read one leaf by id",
		MCP: true,
		Params: []Param{
			{Name: "id", In: "query", Type: "string", Description: "leaf id", Required: true},
			{Name: "body", In: "query", Type: "boolean", Description: "include full text"},
		},
	},
	{Path: PathStats, Method: "get", ID: "stats", Summary: "index health", MCP: true},
	{Path: PathAudit, Method: "get", ID: "audit", Summary: "facts confidence histogram", MCP: true},
	{
		Path: PathIngest, Method: "post", ID: "ingest", Summary: "add a leaf without rebuild",
		MCP: true,
		Params: []Param{
			{Name: "text", In: "query", Type: "string", Description: "leaf text (omit for CLI hint)"},
			{Name: "root", In: "query", Type: "string", Description: "facts or info (default info)"},
			{Name: "source", In: "query", Type: "string", Description: "evidence pointer; facts need two sources"},
			{Name: "valid_from", In: "query", Type: "string", Description: "fact interval start YYYY-MM-DD (D24)"},
			{Name: "valid_to", In: "query", Type: "string", Description: "fact interval end YYYY-MM-DD inclusive (D24)"},
		},
	},
	{Path: PathOpenAPI, Method: "get", ID: "openapi", Summary: "OpenAPI 3 document for this server"},
}

Functions

func NewServer

func NewServer(api API, workers int) http.Handler

func OpenAPI

func OpenAPI() map[string]any

func Run

func Run(api API)

Run starts the HTTP server with an injected API (in-process brain, or ExecSearcher).

func SkillMarkdown

func SkillMarkdown() string

SkillMarkdown is the Cursor skill fragment generated from Ops/MCPTools.

Types

type API

type API interface {
	Search(ctx context.Context, query string, limit int, asOf string) ([]byte, error)
	Get(ctx context.Context, id string, body bool) ([]byte, error)
	Stats(ctx context.Context) ([]byte, error)
	Audit(ctx context.Context) ([]byte, error)
	Ingest(ctx context.Context, body []byte) ([]byte, error)
}

API is the in-process brain surface. Production serve.go wires internal/brain.

type ExecSearcher

type ExecSearcher struct {
	CmdPath string
	Timeout time.Duration
}

ExecSearcher shells out to var/bin/brain-search. Fallback when the serve binary is built without ladybug cgo (CI / tags=brain_serve only).

func (ExecSearcher) Audit

func (ExecSearcher) Audit(context.Context) ([]byte, error)

func (ExecSearcher) Get

func (ExecSearcher) Get(context.Context, string, bool) ([]byte, error)

func (ExecSearcher) Ingest

func (b ExecSearcher) Ingest(ctx context.Context, body []byte) ([]byte, error)

func (ExecSearcher) Search

func (b ExecSearcher) Search(ctx context.Context, query string, limit int, asOf string) ([]byte, error)

func (ExecSearcher) Stats

func (ExecSearcher) Stats(context.Context) ([]byte, error)

type MCPTool

type MCPTool struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"inputSchema"`
}

func MCPTools

func MCPTools() []MCPTool

type Op

type Op struct {
	Path, Method, ID, Summary string
	Params                    []Param
	MCP                       bool
}

type Param

type Param struct {
	Name, In, Type, Description string
	Required                    bool
}

type Server

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

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)