brainclient

Documentation

Overview

Package brainclient — сервисный клиент read-контракта brain (P-9.5, docs/brain/read-contract.md): тонкая HTTP-обёртка над search/get/stats/ audit с typed-ответами internal/contract (JSON-схема P-9.4) и «гейтом facts» (gate.go) — клиент никогда не выдаёт не подтверждённый ответ как подтверждённый факт.

Клиент ходит ТОЛЬКО через read-контракт (HTTP :8630, bin/brain/serve.go) и никогда не открывает var/kb.lbug напрямую. Ответы проверяются контрактными валидаторами internal/contract (формат + contract_version); несовместимый/старый сервис → ошибка, а не молчаливая порча данных.

Пакет cgo-free и не зависит от Ladybug: gator/cv/агенты могут читать brain с любого хоста, где поднят сервис. Вынос типов контракта в публичный go-* модуль для кросс-репо импорта — P-9.6 (ADR).

Index

• func Gate(root, confidence string) bool
• func GateReason(root, confidence string) string
• type AuditGate
  • func GateAudit(a *contract.AuditResponse) AuditGate
  • func (g AuditGate) OK() bool
• type Client
  • func New(cfg Config) *Client
  • func (c *Client) Audit(ctx context.Context) (*contract.AuditResponse, error)
  • func (c *Client) Facts(ctx context.Context, query string, opt SearchOptions) (*Facts, error)
  • func (c *Client) Get(ctx context.Context, id string, opt GetOptions) (*contract.GetResponse, error)
  • func (c *Client) Search(ctx context.Context, query string, opt SearchOptions) (*contract.SearchResponse, error)
  • func (c *Client) Stats(ctx context.Context) (*contract.StatsResponse, error)
• type Config
• type Facts
  • func GateSearch(r *contract.SearchResponse) *Facts
• type GetOptions
• type NotFact
• type SearchOptions

Functions

func Gate

func Gate(root, confidence string) bool

Gate — вердикт гейта для одного листа/хита: true = ответ можно подавать как подтверждённый факт. Подтверждён только root=facts; пустой confidence (legacy-лист) трактуется как confirmed по read-contract.md.

func GateReason

func GateReason(root, confidence string) string

GateReason — пометка для не-факта (пустая, когда Gate вернул true). Клиент обязан показывать её рядом с ответом, чтобы агент не процитировал hypothesis/partial/info как факт.

Types

type AuditGate

type AuditGate struct {
	ConfirmedFacts    int `json:"confirmed_facts"`
	NotConfirmedFacts int `json:"not_confirmed_facts"`
	TotalFacts        int `json:"total_facts"`
}

AuditGate — гейт поверх audit-ответа (гистограмма root × confidence): сколько листов facts-корня подтверждено и сколько отклонено гейтом. NotConfirmedFacts > 0 значит: на facts-корне есть hypothesis/partial — такие листы не должны подаваться как факты (аудит: bin/facts/audit.go contradict / audit-card).

func GateAudit

func GateAudit(a *contract.AuditResponse) AuditGate

GateAudit применяет гейт к аудит-гистограмме (строки считаются по count).

func (AuditGate) OK

func (g AuditGate) OK() bool

OK — гейт чист: на facts-корне нет не подтверждённого confidence.

type Client

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

Client — один транспортный хендл к brain API. Методы синхронны и безопасны для параллельного использования (http.Client thread-safe).

func New

func New(cfg Config) *Client

New возвращает клиент с cfg. Пустой base не валиден — ошибка всплывёт на первом же вызове (клиент никуда не ходит до явного метода).

func (*Client) Audit

func (c *Client) Audit(ctx context.Context) (*contract.AuditResponse, error)

Audit — гистограмма root × confidence (GET /audit). Гейт по facts-корню — GateAudit.

func (*Client) Facts

func (c *Client) Facts(ctx context.Context, query string, opt SearchOptions) (*Facts, error)

Facts — поиск с root=facts + «гейт facts»: ответ разделяется на подтверждённые факты (Confirmed) и отклонённое (NotConfirmed, с причиной). Клиент не должен подавать NotConfirmed как факты.

func (*Client) Get

func (c *Client) Get(ctx context.Context, id string, opt GetOptions) (*contract.GetResponse, error)

Get — чтение листа по id (GET /get). Несуществующий id — ошибка с HTTP статусом и телом сервиса.

func (*Client) Search

func (c *Client) Search(ctx context.Context, query string, opt SearchOptions) (*contract.SearchResponse, error)

Search — поиск по read-контракту. Ответ проходит контрактную валидацию (internal/contract.ValidateSearchResponse): несовместимый сервис — ошибка. Для ответа с гейтом facts (--root facts) используйте Facts.

func (*Client) Stats

func (c *Client) Stats(ctx context.Context) (*contract.StatsResponse, error)

Stats — индексная статистика (GET /stats).

type Config

type Config struct {
	Base    string
	Token   string
	Timeout time.Duration
}

Config — параметры подключения. Base — обязательный base URL сервиса (http://host:port), например из internal/config (host/port). Token — опциональный Bearer-токен (сервер с SetToken). Timeout нулевой → 30s.

type Facts

type Facts struct {
	ContractVersion string               `json:"contract_version"`
	Query           string               `json:"query"`
	RootFilter      string               `json:"root_filter"` // "facts"
	AsOf            string               `json:"as_of,omitempty"`
	Count           int                  `json:"count"` // число подтверждённых фактов
	Confirmed       []contract.SearchHit `json:"confirmed"`
	NotConfirmed    []NotFact            `json:"not_confirmed,omitempty"`
	Web             *contract.WebBlock   `json:"web,omitempty"`
}

Facts — гейтнутый ответ поиска с root=facts: Confirmed содержит только подтверждённые факты, NotConfirmed — всё, что гейт отклонил, с причиной. Клиентская JSON-схема на базе search-ответа контракта: вместо results[] — confirmed[] / not_confirmed[] (поля хитов те же, P-9.4); сервер такой ответ не шлёт, это представление клиента.

func GateSearch

func GateSearch(r *contract.SearchResponse) *Facts

GateSearch применяет гейт к поисковому ответу (любого root_filter): возвращает разделение на подтверждённые факты и отклонённое.

type GetOptions

type GetOptions struct {
	Body bool // включить полный текст (text); иначе — только метаданные
}

GetOptions — опции чтения одного листа.

type NotFact

type NotFact struct {
	contract.SearchHit
	Reason string `json:"reason,omitempty"`
}

NotFact — хит, который гейт отклонил: плоские поля хита (JSON-схема P-9.4) + причина отклонения. Такие ответы клиент никогда не подаёт как подтверждённые факты.

type SearchOptions

type SearchOptions struct {
	Root  string // facts|info; пусто = все корни
	Limit int    // 1..100; 0 = серверный дефолт (10)
	AsOf  string // YYYY-MM-DD (D24): факты, активные на день
	NoWeb bool   // не подмешивать второй источник (noweb=1)
}

SearchOptions — опции поиска (зеркало query-параметров /search).