fix: hyperguild brain write requires wing/hall, not legacy type/slug (#79)
Removes brain_write legacy domain/type/knowledge-path params (ADR-0012) and migrates the previously-missed cmd/hyperguild CLI caller (hyperguild brain write) from <type> <slug> to <wing> <hall> <slug>, fixing a 100%% regression the first review round caught. Adds TestWrite_CLIPayloadRoundTrips exercising the real Handler.Write over HTTP to pin the wire contract. Closes #79. Co-authored-by: Mathias <mthbqv@gmail.com>
This commit was merged in pull request #131.
This commit is contained in:
@@ -1,182 +0,0 @@
|
||||
// internal/skills/brain/handlers.go
|
||||
package brain
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// Handle dispatches brain tool calls.
|
||||
func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (json.RawMessage, error) {
|
||||
switch tool {
|
||||
case "brain_query":
|
||||
return s.query(ctx, args)
|
||||
case "brain_write":
|
||||
return s.write(ctx, args)
|
||||
case "brain_ingest_raw":
|
||||
return s.ingestRaw(ctx, args)
|
||||
case "brain_ingest":
|
||||
return s.ingest(ctx, args)
|
||||
case "brain_search":
|
||||
return s.search(ctx, args)
|
||||
default:
|
||||
return nil, fmt.Errorf("unknown brain tool: %s", tool)
|
||||
}
|
||||
}
|
||||
|
||||
type queryArgs struct {
|
||||
Query string `json:"query"`
|
||||
Limit int `json:"limit,omitempty"`
|
||||
}
|
||||
|
||||
func (s *Skill) query(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
|
||||
var a queryArgs
|
||||
if err := json.Unmarshal(args, &a); err != nil {
|
||||
return nil, fmt.Errorf("parse args: %w", err)
|
||||
}
|
||||
if a.Query == "" {
|
||||
return nil, fmt.Errorf("query is required")
|
||||
}
|
||||
if a.Limit == 0 {
|
||||
a.Limit = 5
|
||||
}
|
||||
return s.post(ctx, "/query", a)
|
||||
}
|
||||
|
||||
type writeArgs struct {
|
||||
Content string `json:"content"`
|
||||
Type string `json:"type,omitempty"`
|
||||
Domain string `json:"domain,omitempty"`
|
||||
Filename string `json:"filename,omitempty"`
|
||||
}
|
||||
|
||||
func (s *Skill) write(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
|
||||
var a writeArgs
|
||||
if err := json.Unmarshal(args, &a); err != nil {
|
||||
return nil, fmt.Errorf("parse args: %w", err)
|
||||
}
|
||||
if a.Content == "" {
|
||||
return nil, fmt.Errorf("content is required")
|
||||
}
|
||||
return s.post(ctx, "/write", a)
|
||||
}
|
||||
|
||||
type ingestArgs struct {
|
||||
Content string `json:"content,omitempty"`
|
||||
Source string `json:"source,omitempty"`
|
||||
Path string `json:"path,omitempty"`
|
||||
DryRun bool `json:"dry_run,omitempty"`
|
||||
}
|
||||
|
||||
func (s *Skill) ingest(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
|
||||
var a ingestArgs
|
||||
if err := json.Unmarshal(args, &a); err != nil {
|
||||
return nil, fmt.Errorf("parse args: %w", err)
|
||||
}
|
||||
if s.cfg.IngestSvcURL == "" {
|
||||
return nil, fmt.Errorf("brain_ingest: INGEST_SVC_URL not configured")
|
||||
}
|
||||
if a.Path != "" && a.Content != "" {
|
||||
return nil, fmt.Errorf("path and content+source are mutually exclusive: provide one or the other")
|
||||
}
|
||||
if a.Path != "" {
|
||||
return s.postTo(ctx, s.cfg.IngestSvcURL+"/ingest-path", map[string]any{
|
||||
"path": a.Path,
|
||||
"source": a.Source,
|
||||
"dry_run": a.DryRun,
|
||||
})
|
||||
}
|
||||
if a.Content != "" && a.Source != "" {
|
||||
return s.postTo(ctx, s.cfg.IngestSvcURL+"/ingest", map[string]any{
|
||||
"content": a.Content,
|
||||
"source": a.Source,
|
||||
"dry_run": a.DryRun,
|
||||
})
|
||||
}
|
||||
return nil, fmt.Errorf("either content+source or path is required")
|
||||
}
|
||||
|
||||
type ingestRawArgs struct {
|
||||
Source string `json:"source"`
|
||||
Pages []any `json:"pages"`
|
||||
DryRun bool `json:"dry_run,omitempty"`
|
||||
}
|
||||
|
||||
func (s *Skill) ingestRaw(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
|
||||
var a ingestRawArgs
|
||||
if err := json.Unmarshal(args, &a); err != nil {
|
||||
return nil, fmt.Errorf("parse args: %w", err)
|
||||
}
|
||||
if s.cfg.IngestSvcURL == "" {
|
||||
return nil, fmt.Errorf("brain_ingest_raw: INGEST_SVC_URL not configured")
|
||||
}
|
||||
if a.Source == "" {
|
||||
return nil, fmt.Errorf("source is required")
|
||||
}
|
||||
if len(a.Pages) == 0 {
|
||||
return nil, fmt.Errorf("pages is required and must be non-empty")
|
||||
}
|
||||
return s.postTo(ctx, s.cfg.IngestSvcURL+"/ingest-raw", map[string]any{
|
||||
"source": a.Source,
|
||||
"pages": a.Pages,
|
||||
"dry_run": a.DryRun,
|
||||
})
|
||||
}
|
||||
|
||||
type searchArgs struct {
|
||||
Query string `json:"query"`
|
||||
Collection string `json:"collection,omitempty"`
|
||||
Limit int `json:"limit,omitempty"`
|
||||
}
|
||||
|
||||
func (s *Skill) search(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
|
||||
var a searchArgs
|
||||
if err := json.Unmarshal(args, &a); err != nil {
|
||||
return nil, fmt.Errorf("parse args: %w", err)
|
||||
}
|
||||
if a.Query == "" {
|
||||
return nil, fmt.Errorf("query is required")
|
||||
}
|
||||
if a.Limit == 0 {
|
||||
a.Limit = 5
|
||||
}
|
||||
if s.cfg.KBRetrievalURL == "" {
|
||||
return nil, fmt.Errorf("brain_search: KB_RETRIEVAL_URL not configured")
|
||||
}
|
||||
return s.postTo(ctx, s.cfg.KBRetrievalURL+"/api/v1/search", a)
|
||||
}
|
||||
|
||||
func (s *Skill) post(ctx context.Context, path string, body any) (json.RawMessage, error) {
|
||||
return s.postTo(ctx, s.cfg.IngestBaseURL+path, body)
|
||||
}
|
||||
|
||||
func (s *Skill) postTo(ctx context.Context, url string, body any) (json.RawMessage, error) {
|
||||
b, err := json.Marshal(body)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("marshal request: %w", err)
|
||||
}
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(b))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("build request: %w", err)
|
||||
}
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("call ingestion server: %w", err)
|
||||
}
|
||||
defer func() { _ = resp.Body.Close() }()
|
||||
|
||||
out, err := io.ReadAll(resp.Body)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read response: %w", err)
|
||||
}
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
return nil, fmt.Errorf("ingestion server returned %d: %s", resp.StatusCode, out)
|
||||
}
|
||||
return json.RawMessage(out), nil
|
||||
}
|
||||
@@ -1,122 +0,0 @@
|
||||
// internal/skills/brain/handlers_test.go
|
||||
package brain_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"git.d-ma.be/mathias/hyperguild/internal/skills/brain"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestHandle_BrainQuery_CallsIngestServer(t *testing.T) {
|
||||
called := false
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
assert.Equal(t, "/query", r.URL.Path)
|
||||
called = true
|
||||
_ = json.NewEncoder(w).Encode(map[string]any{
|
||||
"results": []map[string]any{
|
||||
{"path": "wiki/concepts/tdd.md", "title": "TDD", "excerpt": "Test-driven development.", "score": 3},
|
||||
},
|
||||
})
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
s := brain.New(brain.Config{IngestBaseURL: srv.URL})
|
||||
args, _ := json.Marshal(map[string]string{"query": "test driven development"})
|
||||
out, err := s.Handle(context.Background(), "brain_query", args)
|
||||
require.NoError(t, err)
|
||||
assert.True(t, called)
|
||||
|
||||
var result map[string]any
|
||||
require.NoError(t, json.Unmarshal(out, &result))
|
||||
results := result["results"].([]any)
|
||||
assert.Len(t, results, 1)
|
||||
}
|
||||
|
||||
func TestHandle_BrainWrite_CallsIngestServer(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
assert.Equal(t, "/write", r.URL.Path)
|
||||
var body map[string]string
|
||||
require.NoError(t, json.NewDecoder(r.Body).Decode(&body))
|
||||
assert.Equal(t, "concept", body["type"])
|
||||
assert.Equal(t, "# Test\n\nSome learning.", body["content"])
|
||||
_ = json.NewEncoder(w).Encode(map[string]string{"path": "raw/test.md"})
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
s := brain.New(brain.Config{IngestBaseURL: srv.URL})
|
||||
args, _ := json.Marshal(map[string]string{"content": "# Test\n\nSome learning.", "type": "concept"})
|
||||
out, err := s.Handle(context.Background(), "brain_write", args)
|
||||
require.NoError(t, err)
|
||||
var result map[string]string
|
||||
require.NoError(t, json.Unmarshal(out, &result))
|
||||
assert.Equal(t, "raw/test.md", result["path"])
|
||||
}
|
||||
|
||||
func TestHandle_UnknownTool_ReturnsError(t *testing.T) {
|
||||
s := brain.New(brain.Config{IngestBaseURL: "http://localhost:3300"})
|
||||
_, err := s.Handle(context.Background(), "brain_unknown", nil)
|
||||
assert.Error(t, err)
|
||||
}
|
||||
|
||||
func TestIngest_RoutesToIngestPath(t *testing.T) {
|
||||
var capturedPath string
|
||||
var capturedBody map[string]any
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
capturedPath = r.URL.Path
|
||||
require.NoError(t, json.NewDecoder(r.Body).Decode(&capturedBody))
|
||||
_ = json.NewEncoder(w).Encode(map[string]any{"pages": []string{"wiki/foo.md"}})
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
s := brain.New(brain.Config{IngestSvcURL: srv.URL})
|
||||
args, _ := json.Marshal(map[string]any{"path": "/tmp/some-file.md"})
|
||||
out, err := s.Handle(context.Background(), "brain_ingest", args)
|
||||
require.NoError(t, err)
|
||||
|
||||
assert.Equal(t, "/ingest-path", capturedPath)
|
||||
assert.Equal(t, "/tmp/some-file.md", capturedBody["path"])
|
||||
|
||||
var result map[string]any
|
||||
require.NoError(t, json.Unmarshal(out, &result))
|
||||
pages := result["pages"].([]any)
|
||||
assert.Len(t, pages, 1)
|
||||
}
|
||||
|
||||
func TestIngest_RoutesToIngest(t *testing.T) {
|
||||
var capturedPath string
|
||||
var capturedBody map[string]any
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
capturedPath = r.URL.Path
|
||||
require.NoError(t, json.NewDecoder(r.Body).Decode(&capturedBody))
|
||||
_ = json.NewEncoder(w).Encode(map[string]any{"pages": []string{"wiki/bar.md"}})
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
s := brain.New(brain.Config{IngestSvcURL: srv.URL})
|
||||
args, _ := json.Marshal(map[string]any{"content": "some content", "source": "my-source.md"})
|
||||
out, err := s.Handle(context.Background(), "brain_ingest", args)
|
||||
require.NoError(t, err)
|
||||
|
||||
assert.Equal(t, "/ingest", capturedPath)
|
||||
assert.Equal(t, "some content", capturedBody["content"])
|
||||
assert.Equal(t, "my-source.md", capturedBody["source"])
|
||||
|
||||
var result map[string]any
|
||||
require.NoError(t, json.Unmarshal(out, &result))
|
||||
pages := result["pages"].([]any)
|
||||
assert.Len(t, pages, 1)
|
||||
}
|
||||
|
||||
func TestIngest_MissingRequiredFields(t *testing.T) {
|
||||
s := brain.New(brain.Config{IngestSvcURL: "http://localhost:3300"})
|
||||
args, _ := json.Marshal(map[string]any{})
|
||||
_, err := s.Handle(context.Background(), "brain_ingest", args)
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "either content+source or path is required")
|
||||
}
|
||||
@@ -1,111 +0,0 @@
|
||||
// internal/skills/brain/skill.go
|
||||
package brain
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
|
||||
"git.d-ma.be/mathias/hyperguild/internal/registry"
|
||||
)
|
||||
|
||||
// Config holds brain skill configuration.
|
||||
type Config struct {
|
||||
IngestBaseURL string // base URL of the ingestion HTTP server (brain_query, brain_write)
|
||||
IngestSvcURL string // base URL of the ingestion-svc HTTP server (brain_ingest)
|
||||
KBRetrievalURL string // base URL of the kb-retrieval server (brain_search)
|
||||
}
|
||||
|
||||
// Skill implements registry.Skill for brain_query and brain_write.
|
||||
type Skill struct {
|
||||
cfg Config
|
||||
}
|
||||
|
||||
// New constructs a brain Skill.
|
||||
func New(cfg Config) *Skill { return &Skill{cfg: cfg} }
|
||||
|
||||
// Name returns the skill name used for routing.
|
||||
func (s *Skill) Name() string { return "brain" }
|
||||
|
||||
// Tools returns the MCP tool definitions for brain_query and brain_write.
|
||||
func (s *Skill) Tools() []registry.ToolDef {
|
||||
schema := func(required []string, props map[string]any) json.RawMessage {
|
||||
b, _ := json.Marshal(map[string]any{"type": "object", "required": required, "properties": props})
|
||||
return b
|
||||
}
|
||||
str := map[string]any{"type": "string"}
|
||||
num := map[string]any{"type": "integer"}
|
||||
|
||||
tools := []registry.ToolDef{
|
||||
{
|
||||
Name: "brain_query",
|
||||
Description: "BM25 full-text search across brain/knowledge/ and brain/wiki/ markdown files. Fast, no embeddings needed. Call before any significant task.",
|
||||
InputSchema: schema([]string{"query"}, map[string]any{
|
||||
"query": str,
|
||||
"limit": num,
|
||||
}),
|
||||
},
|
||||
{
|
||||
Name: "brain_write",
|
||||
Description: "Write a raw knowledge note to brain/knowledge/ for later ingestion.",
|
||||
InputSchema: schema([]string{"content"}, map[string]any{
|
||||
"content": str,
|
||||
"type": str,
|
||||
"domain": str,
|
||||
"filename": str,
|
||||
}),
|
||||
},
|
||||
}
|
||||
if s.cfg.IngestSvcURL != "" {
|
||||
tools = append(tools, registry.ToolDef{
|
||||
Name: "brain_ingest_raw",
|
||||
Description: "Ingest pre-structured pages into the brain wiki, bypassing the LLM extraction step. " +
|
||||
"Use when you (the calling agent) have already extracted entities, concepts, and content from a source. " +
|
||||
"Provide source (human-readable name) and pages (array of {title, type, subtype, domain, content} objects). " +
|
||||
"The pipeline computes slugs, paths, frontmatter, wikilink canonicalization, and source back-references. " +
|
||||
"Returns the list of wiki pages written.",
|
||||
InputSchema: schema([]string{"source", "pages"}, map[string]any{
|
||||
"source": map[string]any{"type": "string", "description": "human-readable name for the source, e.g. 'shape-up-book'"},
|
||||
"pages": map[string]any{
|
||||
"type": "array",
|
||||
"items": map[string]any{
|
||||
"type": "object",
|
||||
"required": []string{"title", "type", "content"},
|
||||
"properties": map[string]any{
|
||||
"title": map[string]any{"type": "string", "description": "page title, e.g. 'Hash Encoding'"},
|
||||
"type": map[string]any{"type": "string", "enum": []string{"source", "concept", "entity"}, "description": "page type"},
|
||||
"subtype": map[string]any{"type": "string", "description": "entity: person|company|tool|model|framework|technology; source: article|pdf|book|video|note|project"},
|
||||
"domain": map[string]any{"type": "string", "description": "knowledge domain, e.g. 'Machine Learning'"},
|
||||
"content": map[string]any{"type": "string", "description": "markdown body — no frontmatter, use [[Display Name]] for wikilinks"},
|
||||
},
|
||||
},
|
||||
},
|
||||
"dry_run": map[string]any{"type": "boolean"},
|
||||
}),
|
||||
})
|
||||
tools = append(tools, registry.ToolDef{
|
||||
Name: "brain_ingest",
|
||||
Description: "Ingest content into the brain wiki (brain/wiki/). Calls an LLM to produce structured wiki pages. " +
|
||||
"Use for substantial documents, articles, or knowledge worth structuring. " +
|
||||
"Provide EITHER (a) path — absolute path to a file or directory, " +
|
||||
"OR (b) content + source — raw text and a human-readable name. " +
|
||||
"Providing both is an error. Returns the list of wiki pages written.",
|
||||
InputSchema: schema([]string{}, map[string]any{
|
||||
"content": map[string]any{"type": "string", "description": "raw text to ingest; required when path is not set"},
|
||||
"source": map[string]any{"type": "string", "description": "human-readable name for the content, e.g. 'shape-up-book'; required when path is not set"},
|
||||
"path": map[string]any{"type": "string", "description": "absolute path to a file or directory to ingest; mutually exclusive with content+source"},
|
||||
"dry_run": map[string]any{"type": "boolean"},
|
||||
}),
|
||||
})
|
||||
}
|
||||
if s.cfg.KBRetrievalURL != "" {
|
||||
tools = append(tools, registry.ToolDef{
|
||||
Name: "brain_search",
|
||||
Description: "Semantic vector search across the brain wiki using embeddings. Use when brain_query returns no results or you need conceptually-related results rather than keyword matches.",
|
||||
InputSchema: schema([]string{"query"}, map[string]any{
|
||||
"query": str,
|
||||
"collection": str,
|
||||
"limit": num,
|
||||
}),
|
||||
})
|
||||
}
|
||||
return tools
|
||||
}
|
||||
Reference in New Issue
Block a user