feat: add composio/cognee SDK methods

composio_cognee.go

@@ -0,0 +1,255 @@
+package hawksdk
+
+// This file adds composio and cognee integration methods to the hawk SDK client.
+// These methods allow SDK consumers to:
+//   - Search composio tools
+//   - Execute composio tools
+//   - List composio credentials
+//   - Store and recall cognee structured memory entries (QA, trace, feedback, skill run)
+//   - Improve memories (re-process for quality)
+//   - Sync session memories to permanent graph
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+// --- Composio Tool Search ---
+
+// ComposioTool represents a tool available from the composio platform.
+type ComposioTool struct {
+	Name         string                 `json:"name"`
+	Description  string                 `json:"description"`
+	Scope        string                 `json:"scope"`
+	AuthRequired bool                   `json:"auth_required"`
+	Params       map[string]interface{} `json:"params"`
+	Tags         []string               `json:"tags"`
+	Category     string                 `json:"category"`
+}
+
+// ComposioToolSearchResult is the response from searching composio tools.
+type ComposioToolSearchResult struct {
+	Tools []ComposioTool `json:"tools"`
+	Count int            `json:"count"`
+}
+
+// SearchComposioTools searches the composio tool catalog.
+func (c *Client) SearchComposioTools(ctx context.Context, query string) (*ComposioToolSearchResult, error) {
+	var result ComposioToolSearchResult
+	err := c.post(ctx, "/composio/search", map[string]string{"query": query}, &result)
+	if err != nil {
+		return nil, fmt.Errorf("search composio tools: %w", err)
+	}
+	return &result, nil
+}
+
+// --- Composio Tool Execution ---
+
+// ComposioToolResult is the result of executing a composio tool.
+type ComposioToolResult struct {
+	Success bool                   `json:"success"`
+	Data    map[string]interface{} `json:"data,omitempty"`
+	Error   string                 `json:"error,omitempty"`
+}
+
+// ExecuteComposioTool executes a composio tool by name with the given parameters.
+func (c *Client) ExecuteComposioTool(ctx context.Context, name string, params map[string]interface{}) (*ComposioToolResult, error) {
+	var result ComposioToolResult
+	err := c.post(ctx, "/composio/execute", map[string]interface{}{
+		"name":   name,
+		"params": params,
+	}, &result)
+	if err != nil {
+		return nil, fmt.Errorf("execute composio tool: %w", err)
+	}
+	return &result, nil
+}
+
+// --- Composio Credentials ---
+
+// ComposioCredential represents a credential for a connected service.
+type ComposioCredential struct {
+	ID          string            `json:"id"`
+	ServiceName string            `json:"service_name"`
+	Type        string            `json:"type"`
+	Scope       string            `json:"scope,omitempty"`
+	ExpiresAt   time.Time         `json:"expires_at,omitempty"`
+	Metadata    map[string]string `json:"metadata,omitempty"`
+}
+
+// ListComposioCredentials lists all composio credentials.
+func (c *Client) ListComposioCredentials(ctx context.Context) ([]ComposioCredential, error) {
+	var creds []ComposioCredential
+	err := c.get(ctx, "/composio/credentials", nil, &creds)
+	if err != nil {
+		return nil, fmt.Errorf("list composio credentials: %w", err)
+	}
+	return creds, nil
+}
+
+// --- Cognee Structured Memory Entries ---
+
+// CogneeQAEntry captures a Q&A conversation turn.
+type CogneeQAEntry struct {
+	Question      string   `json:"question"`
+	Answer        string   `json:"answer"`
+	Context       string   `json:"context,omitempty"`
+	FeedbackText  string   `json:"feedback_text,omitempty"`
+	FeedbackScore *int     `json:"feedback_score,omitempty"`
+	UsedGraphIDs  []string `json:"used_graph_element_ids,omitempty"`
+	SessionID     string   `json:"session_id,omitempty"`
+	Project       string   `json:"project"`
+	SourceAgent   string   `json:"source_agent,omitempty"`
+}
+
+// RememberQA stores a Q&A entry as a structured memory node.
+func (c *Client) RememberQA(ctx context.Context, qa CogneeQAEntry) (string, error) {
+	var result struct {
+		ID string `json:"id"`
+	}
+	err := c.post(ctx, "/cognee/qa", qa, &result)
+	if err != nil {
+		return "", fmt.Errorf("remember QA: %w", err)
+	}
+	return result.ID, nil
+}
+
+// CogneeTraceEntry captures a single step in an agent's execution trace.
+type CogneeTraceEntry struct {
+	OriginFunction    string `json:"origin_function"`
+	Status            string `json:"status"`
+	MethodParams      string `json:"method_params,omitempty"`
+	MethodReturnValue string `json:"method_return_value,omitempty"`
+	MemoryQuery       string `json:"memory_query,omitempty"`
+	MemoryContext     string `json:"memory_context,omitempty"`
+	ErrorMessage      string `json:"error_message,omitempty"`
+	SessionID         string `json:"session_id"`
+	Project           string `json:"project"`
+	SourceAgent       string `json:"source_agent,omitempty"`
+}
+
+// RememberTrace stores a trace entry as a structured memory node.
+func (c *Client) RememberTrace(ctx context.Context, te CogneeTraceEntry) (string, error) {
+	var result struct {
+		ID string `json:"id"`
+	}
+	err := c.post(ctx, "/cognee/trace", te, &result)
+	if err != nil {
+		return "", fmt.Errorf("remember trace: %w", err)
+	}
+	return result.ID, nil
+}
+
+// CogneeFeedbackEntry attaches feedback to an existing QA entry.
+type CogneeFeedbackEntry struct {
+	TargetNodeID string `json:"target_node_id"`
+	FeedbackText string `json:"feedback_text"`
+	Score        *int   `json:"feedback_score,omitempty"`
+	Project      string `json:"project"`
+	SessionID    string `json:"session_id,omitempty"`
+	SourceAgent  string `json:"source_agent,omitempty"`
+}
+
+// RememberFeedback stores feedback on an existing QA entry.
+func (c *Client) RememberFeedback(ctx context.Context, fe CogneeFeedbackEntry) (string, error) {
+	var result struct {
+		ID string `json:"id"`
+	}
+	err := c.post(ctx, "/cognee/feedback", fe, &result)
+	if err != nil {
+		return "", fmt.Errorf("remember feedback: %w", err)
+	}
+	return result.ID, nil
+}
+
+// CogneeSkillRunEntry persists an execution record for a skill.
+type CogneeSkillRunEntry struct {
+	SkillName    string `json:"skill_name"`
+	SkillVersion string `json:"skill_version,omitempty"`
+	Params       string `json:"params,omitempty"`
+	Result       string `json:"result,omitempty"`
+	Status       string `json:"status"`
+	DurationMs   int64  `json:"duration_ms,omitempty"`
+	Error        string `json:"error,omitempty"`
+	Project      string `json:"project"`
+	SessionID    string `json:"session_id,omitempty"`
+	SourceAgent  string `json:"source_agent,omitempty"`
+}
+
+// RememberSkillRun stores a skill run entry as a structured memory node.
+func (c *Client) RememberSkillRun(ctx context.Context, sr CogneeSkillRunEntry) (string, error) {
+	var result struct {
+		ID string `json:"id"`
+	}
+	err := c.post(ctx, "/cognee/skill_run", sr, &result)
+	if err != nil {
+		return "", fmt.Errorf("remember skill run: %w", err)
+	}
+	return result.ID, nil
+}
+
+// --- Cognee Improve ---
+
+// CogneeImproveResult reports what the improve pass did.
+type CogneeImproveResult struct {
+	NodesProcessed      int           `json:"nodes_processed"`
+	NodesImproved       int           `json:"nodes_improved"`
+	SummariesGenerated  int           `json:"summaries_generated"`
+	EmbeddingsRefreshed int           `json:"embeddings_refreshed"`
+	DuplicatesMerged    int           `json:"duplicates_merged"`
+	Errors              int           `json:"errors"`
+	Duration            time.Duration `json:"duration_ms"`
+}
+
+// ImproveOpts configures a cognee improve pass.
+type ImproveOpts struct {
+	Project               string  `json:"project,omitempty"`
+	MinConfidence         float64 `json:"min_confidence,omitempty"`
+	MinAccessCount        int     `json:"min_access_count,omitempty"`
+	ConsolidateDuplicates bool    `json:"consolidate_duplicates"`
+	RegenerateSummaries   bool    `json:"regenerate_summaries"`
+	RefreshEmbeddings     bool    `json:"refresh_embeddings"`
+	Limit                 int     `json:"limit,omitempty"`
+}
+
+// Improve re-processes memories to enhance their quality.
+func (c *Client) Improve(ctx context.Context, opts ImproveOpts) (*CogneeImproveResult, error) {
+	var result CogneeImproveResult
+	err := c.post(ctx, "/cognee/improve", opts, &result)
+	if err != nil {
+		return nil, fmt.Errorf("improve: %w", err)
+	}
+	return &result, nil
+}
+
+// --- Cognee Session Management ---
+
+// SyncSessionToPermanent promotes session-scoped memories to permanent status.
+func (c *Client) SyncSessionToPermanent(ctx context.Context, sessionID string) (int, error) {
+	var result struct {
+		Promoted int `json:"promoted"`
+	}
+	err := c.post(ctx, "/cognee/sync_session", map[string]string{"session_id": sessionID}, &result)
+	if err != nil {
+		return 0, fmt.Errorf("sync session: %w", err)
+	}
+	return result.Promoted, nil
+}
+
+// RecallWithSession performs session-aware recall.
+func (c *Client) RecallWithSession(ctx context.Context, query, sessionID, project string, limit int) (string, error) {
+	var result struct {
+		Context string `json:"context"`
+	}
+	err := c.post(ctx, "/cognee/recall_session", map[string]interface{}{
+		"query":      query,
+		"session_id": sessionID,
+		"project":    project,
+		"limit":      limit,
+	}, &result)
+	if err != nil {
+		return "", fmt.Errorf("recall session: %w", err)
+	}
+	return result.Context, nil
+}