Skip to content

feat: add composio/cognee types and proto schema #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Patel230 merged 2 commits into from
Jul 29, 2026
Merged

feat: add composio/cognee types and proto schema #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b61af35
feat: add composio/cognee types and proto schema
Patel230 Jul 29, 2026
ec4f593
fix: correct proto enum prefix and gofumpt formatting
Patel230 Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 158 additions & 0 deletions proto/hawk/contracts/v1/composio_cognee.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
syntax = "proto3";

package hawk.contracts.v1;

import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option go_package = "github.com/GrayCodeAI/hawk-core-contracts/gen/go/hawk/contracts/v1;contractsv1";

// ComposioToolScope defines the scope at which a composio tool operates.
enum ComposioToolScope {
COMPOSIO_TOOL_SCOPE_UNSPECIFIED = 0;
COMPOSIO_TOOL_SCOPE_READ = 1;
COMPOSIO_TOOL_SCOPE_WRITE = 2;
COMPOSIO_TOOL_SCOPE_ACTION = 3;
}

// ComposioTool mirrors types.ComposioTool — a tool available from the
// composio platform. Params is arbitrary JSON (google.protobuf.Struct).
message ComposioTool {
string name = 1;
string description = 2;
ComposioToolScope scope = 3;
bool auth_required = 4;
google.protobuf.Struct params = 5;
repeated string tags = 6;
string category = 7;
}

// ComposioToolResult mirrors types.ComposioToolResult — the result of
// executing a composio tool.
message ComposioToolResult {
bool success = 1;
google.protobuf.Struct data = 2;
string error = 3;
}

// ComposioCredential mirrors types.ComposioCredential — an API credential
// for a connected service. Value is never serialized in the proto.
message ComposioCredential {
string id = 1;
string service_name = 2;
string type = 3;
string scope = 4;
google.protobuf.Timestamp expires_at = 5;
map<string, string> metadata = 6;
}

// CogneeEntryType identifies a structured memory entry kind.
enum CogneeEntryType {
COGNEE_ENTRY_TYPE_UNSPECIFIED = 0;
COGNEE_ENTRY_TYPE_QA = 1;
COGNEE_ENTRY_TYPE_TRACE = 2;
COGNEE_ENTRY_TYPE_FEEDBACK = 3;
COGNEE_ENTRY_TYPE_SKILL_RUN = 4;
}

// CogneeQAEntry mirrors types.CogneeQAEntry — a Q&A conversation turn
// with optional feedback.
message CogneeQAEntry {
CogneeEntryType type = 1;
string question = 2;
string answer = 3;
string context = 4;
string feedback_text = 5;
int32 feedback_score = 6;
repeated string used_graph_ids = 7;
string session_id = 8;
string project = 9;
string source_agent = 10;
google.protobuf.Timestamp timestamp = 11;
}

// CogneeTraceEntry mirrors types.CogneeTraceEntry — a single step in an
// agent's execution trace.
message CogneeTraceEntry {
CogneeEntryType type = 1;
string origin_function = 2;
string status = 3;
string method_params = 4;
string method_return_value = 5;
string memory_query = 6;
string memory_context = 7;
string error_message = 8;
bool generate_feedback = 9;
string session_id = 10;
string project = 11;
string source_agent = 12;
google.protobuf.Timestamp timestamp = 13;
}

// CogneeFeedbackEntry mirrors types.CogneeFeedbackEntry — feedback
// attached to an existing QA entry.
message CogneeFeedbackEntry {
CogneeEntryType type = 1;
string target_node_id = 2;
string feedback_text = 3;
int32 feedback_score = 4;
string project = 5;
string session_id = 6;
string source_agent = 7;
google.protobuf.Timestamp timestamp = 8;
}

// CogneeSkillRunEntry mirrors types.CogneeSkillRunEntry — an execution
// record for a skill.
message CogneeSkillRunEntry {
CogneeEntryType type = 1;
string skill_name = 2;
string skill_version = 3;
string params = 4;
string result = 5;
string status = 6;
int64 duration_ms = 7;
string error = 8;
string project = 9;
string session_id = 10;
string source_agent = 11;
google.protobuf.Timestamp timestamp = 12;
}

// AgentSkillCategory defines the category of an agent skill.
enum AgentSkillCategory {
AGENT_SKILL_CATEGORY_UNSPECIFIED = 0;
AGENT_SKILL_CATEGORY_ENGINEERING = 1;
AGENT_SKILL_CATEGORY_OPS = 2;
AGENT_SKILL_CATEGORY_TESTING = 3;
AGENT_SKILL_CATEGORY_SECURITY = 4;
AGENT_SKILL_CATEGORY_DEVTOOLS = 5;
AGENT_SKILL_CATEGORY_WORKFLOW = 6;
}

// AgentSkillChain mirrors types.AgentSkillChain — declares relationships
// between skills.
message AgentSkillChain {
repeated string after = 1;
repeated string before = 2;
repeated string conflicts = 3;
repeated string enhances = 4;
}

// AgentSkill mirrors types.AgentSkill — a skill conforming to the
// agentskills.io specification.
message AgentSkill {
string name = 1;
string description = 2;
string version = 3;
string author = 4;
string license = 5;
AgentSkillCategory category = 6;
bool auto_invoke = 7;
string compatibility = 8;
string allowed_tools = 9;
repeated string agents = 10;
string invoke = 11;
repeated string refs = 12;
AgentSkillChain chain = 13;
}
168 changes: 168 additions & 0 deletions types/composio_cognee.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
// Package types provides shared cross-repo contracts for the hawk-eco
// platform. This file adds types for composio and cognee integration,
// enabling SDKs and engines to share a common vocabulary for:
// - Composio tool metadata (discovery, search, execution)
// - Cognee structured memory entries (QA, trace, feedback, skill run)
// - Composio credential management
package types

import "time"

// --- Composio Types ---

// ComposioToolScope defines the scope at which a composio tool operates.
type ComposioToolScope string

const (
ComposioScopeReadOnly ComposioToolScope = "read"
ComposioScopeWrite ComposioToolScope = "write"
ComposioScopeAction ComposioToolScope = "action"
)

// ComposioTool represents a tool available from the composio platform.
type ComposioTool struct {
Name string `json:"name"`
Description string `json:"description"`
Scope ComposioToolScope `json:"scope"`
AuthRequired bool `json:"auth_required"`
Params map[string]interface{} `json:"params"`
Tags []string `json:"tags"`
Category string `json:"category"`
}

// 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"`
}

// ComposioCredential holds an API credential for a connected service.
type ComposioCredential struct {
ID string `json:"id"`
ServiceName string `json:"service_name"`
Type string `json:"type"` // "oauth", "api_key", "password"
Value string `json:"-"` // never serialize
Scope string `json:"scope,omitempty"`
ExpiresAt time.Time `json:"expires_at,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}

// IsExpired reports whether the credential has expired.
func (c ComposioCredential) IsExpired() bool {
if c.ExpiresAt.IsZero() {
return false
}
return time.Now().After(c.ExpiresAt)
}

// --- Cognee Structured Entry Types ---

// CogneeEntryType identifies a structured memory entry kind.
type CogneeEntryType string

const (
CogneeEntryQA CogneeEntryType = "qa"
CogneeEntryTrace CogneeEntryType = "trace"
CogneeEntryFeedback CogneeEntryType = "feedback"
CogneeEntrySkillRun CogneeEntryType = "skill_run"
)

// CogneeQAEntry captures a Q&A conversation turn with optional feedback.
type CogneeQAEntry struct {
Type CogneeEntryType `json:"type"`
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"`
Timestamp time.Time `json:"timestamp"`
}

// CogneeTraceEntry captures a single step in an agent's execution trace.
type CogneeTraceEntry struct {
Type CogneeEntryType `json:"type"`
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"`
GenerateFeedback bool `json:"generate_feedback_with_llm"`
SessionID string `json:"session_id"`
Project string `json:"project"`
SourceAgent string `json:"source_agent,omitempty"`
Timestamp time.Time `json:"timestamp"`
}

// CogneeFeedbackEntry attaches feedback to an existing QA entry.
type CogneeFeedbackEntry struct {
Type CogneeEntryType `json:"type"`
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"`
Timestamp time.Time `json:"timestamp"`
}

// CogneeSkillRunEntry persists an execution record for a skill.
type CogneeSkillRunEntry struct {
Type CogneeEntryType `json:"type"`
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"`
Timestamp time.Time `json:"timestamp"`
}

// --- Agent Skills Spec (agentskills.io) ---

// AgentSkillCategory defines the category of an agent skill.
type AgentSkillCategory string

const (
SkillCategoryEngineering AgentSkillCategory = "engineering"
SkillCategoryOps AgentSkillCategory = "ops"
SkillCategoryTesting AgentSkillCategory = "testing"
SkillCategorySecurity AgentSkillCategory = "security"
SkillCategoryDevtools AgentSkillCategory = "devtools"
SkillCategoryWorkflow AgentSkillCategory = "workflow"
)

// AgentSkillChain declares relationships between skills.
type AgentSkillChain struct {
After []string `json:"after,omitempty"`
Before []string `json:"before,omitempty"`
Conflicts []string `json:"conflicts,omitempty"`
Enhances []string `json:"enhances,omitempty"`
}

// AgentSkill represents a skill conforming to the agentskills.io specification.
type AgentSkill struct {
Name string `json:"name"`
Description string `json:"description"`
Version string `json:"version"`
Author string `json:"author"`
License string `json:"license"`
Category AgentSkillCategory `json:"category,omitempty"`
AutoInvoke bool `json:"auto_invoke,omitempty"`
Compatibility string `json:"compatibility,omitempty"`
AllowedTools string `json:"allowed_tools,omitempty"`
Agents []string `json:"agents,omitempty"`
Invoke string `json:"invoke,omitempty"`
Refs []string `json:"refs,omitempty"`
Chain AgentSkillChain `json:"chain,omitempty"`
}
Loading