Documentation
¶
Overview ¶
Package dto defines the wire contracts for MCP tool responses.
Every type in this package is a deliberate copy of the response shape — decoupled from internal engine types so that renaming an internal struct or changing its json tags can no longer silently break MCP clients. Handlers map engine results into these DTOs; the json tags here are the frozen contract, locked by golden-file tests in testdata/.
Every top-level response embeds Contract, which stamps schema_version so clients can feature-detect contract changes.
Index ¶
- Constants
- type BulkIngestDoc
- type Chunk
- type ChunkConfig
- type ChunkResult
- type Collection
- type ContextGet
- type ContextHistory
- type ContextHistoryEntry
- type ContextList
- type ContextMerge
- type ContextSet
- type Contract
- type ConversationAppend
- type ConversationHistory
- type ConversationSearch
- type ConversationSummarize
- type Entity
- type EntityList
- type EntityMention
- type EntityMerge
- type EntityQuery
- type EntityRelationship
- type EntityRelationships
- type EntityResult
- type EntitySearch
- type EntityUpdate
- type KnowledgeBulkIngest
- type KnowledgeCollectionCreated
- type KnowledgeCollectionDeleted
- type KnowledgeCollectionList
- type KnowledgeIngest
- type KnowledgeSearch
- type Message
- type MessageResult
Constants ¶
const SchemaVersion = 1
SchemaVersion is the current response contract version. Bump when a breaking change is made to any DTO's wire shape; clients can branch on schema_version to migrate.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BulkIngestDoc ¶
type BulkIngestDoc struct {
Index int `json:"index"`
DocumentID string `json:"document_id,omitempty"`
Title string `json:"title,omitempty"`
ChunksCreated int `json:"chunks_created"`
Success bool `json:"success"`
Error string `json:"error,omitempty"`
}
BulkIngestDoc mirrors knowledge.BulkIngestDocResult.
type Chunk ¶
type Chunk struct {
ID string `json:"id"`
DocumentID string `json:"document_id"`
Namespace string `json:"namespace"`
CollectionID string `json:"collection_id"`
Content string `json:"content"`
Index int `json:"index"`
TokenCount int `json:"token_count,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
Chunk is the read shape of types.Chunk. It deliberately omits the Embedding field: chunks in search results carry ~dimension-count floats each (1536 by default), so serializing them into a top_k:20 response emits tens of thousands of float noise, bloating token usage for LLM clients. Clients never need the stored vectors — only the server does for similarity computation.
type ChunkConfig ¶
type ChunkConfig struct {
Strategy string `json:"strategy"`
MaxTokens int `json:"max_tokens"`
Overlap int `json:"overlap"`
Separator string `json:"separator,omitempty"`
}
ChunkConfig mirrors types.ChunkConfig.
type ChunkResult ¶
type ChunkResult struct {
Chunk *Chunk `json:"chunk"`
Score float64 `json:"score"`
Rank int `json:"rank,omitempty"`
DocumentTitle string `json:"document_title"`
Source string `json:"source"`
DocMetadata map[string]string `json:"doc_metadata,omitempty"`
ContextBefore string `json:"context_before,omitempty"`
ContextAfter string `json:"context_after,omitempty"`
}
ChunkResult mirrors types.ChunkResult.
type Collection ¶
type Collection struct {
ID string `json:"id"`
Namespace string `json:"namespace"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
ChunkConfig ChunkConfig `json:"chunk_config"`
CreatedAt time.Time `json:"created_at"`
}
Collection mirrors types.Collection.
type ContextGet ¶
type ContextGet struct {
Contract
Key string `json:"key"`
Value any `json:"value"`
Version int64 `json:"version"`
UpdatedAt time.Time `json:"updated_at"`
Exists bool `json:"exists"`
}
ContextGet is the context_get response.
func NewContextGet ¶
func NewContextGet(r *ctxengine.GetResult) ContextGet
NewContextGet maps an engine get result.
type ContextHistory ¶
type ContextHistory struct {
Contract
Key string `json:"key"`
History []ContextHistoryEntry `json:"history"`
NextCursor string `json:"next_cursor,omitempty"`
}
ContextHistory is the context_history response.
func NewContextHistory ¶
func NewContextHistory(r *ctxengine.HistoryResult) ContextHistory
NewContextHistory maps an engine history result.
type ContextHistoryEntry ¶
type ContextHistoryEntry struct {
Version int64 `json:"version"`
Value any `json:"value"`
Operation string `json:"operation"`
UpdatedAt time.Time `json:"updated_at"`
UpdatedBy string `json:"updated_by,omitempty"`
}
ContextHistoryEntry mirrors types.ContextHistoryEntry.
type ContextList ¶
type ContextList struct {
Contract
Keys []string `json:"keys"`
Count int `json:"count"`
NextCursor string `json:"next_cursor,omitempty"`
}
ContextList is the context_list response.
func NewContextList ¶
func NewContextList(r *ctxengine.ListResult) ContextList
NewContextList maps an engine list result.
type ContextMerge ¶
type ContextMerge struct {
Contract
Key string `json:"key"`
Version int64 `json:"version"`
MergedValue any `json:"merged_value"`
}
ContextMerge is the context_merge response.
func NewContextMerge ¶
func NewContextMerge(r *ctxengine.MergeResult) ContextMerge
NewContextMerge maps an engine merge result.
type ContextSet ¶
type ContextSet struct {
Contract
Key string `json:"key"`
Version int64 `json:"version"`
PreviousVersion int64 `json:"previous_version"`
}
ContextSet is the context_set response.
func NewContextSet ¶
func NewContextSet(r *ctxengine.SetResult) ContextSet
NewContextSet maps an engine set result.
type Contract ¶
type Contract struct {
SchemaVersion int `json:"schema_version"`
}
Contract is embedded in every top-level response DTO and flattens to a top-level schema_version field in the marshaled JSON.
type ConversationAppend ¶
ConversationAppend is the conversation_append response.
func NewConversationAppend ¶
func NewConversationAppend(m *types.Message) ConversationAppend
NewConversationAppend maps an engine append result.
type ConversationHistory ¶
type ConversationHistory struct {
Contract
Messages []Message `json:"messages"`
Summary string `json:"summary,omitempty"`
NextCursor string `json:"next_cursor,omitempty"`
ThreadID string `json:"thread_id"`
}
ConversationHistory is the conversation_history response.
func NewConversationHistory ¶
func NewConversationHistory(r *conversation.HistoryResult) ConversationHistory
NewConversationHistory maps an engine history result.
type ConversationSearch ¶
type ConversationSearch struct {
Contract
Results []MessageResult `json:"results"`
Query string `json:"query"`
}
ConversationSearch is the conversation_search response.
func NewConversationSearch ¶
func NewConversationSearch(r *conversation.SearchResult) ConversationSearch
NewConversationSearch maps an engine search result.
type ConversationSummarize ¶
type ConversationSummarize struct {
Contract
Summary string `json:"summary"`
MessagesSummarized int `json:"messages_summarized"`
MessagesKept int `json:"messages_kept"`
ThreadID string `json:"thread_id"`
}
ConversationSummarize is the conversation_summarize response.
func NewConversationSummarize ¶
func NewConversationSummarize(r *conversation.SummarizeResult) ConversationSummarize
NewConversationSummarize maps an engine summarize result.
type Entity ¶
type Entity struct {
ID string `json:"id"`
Namespace string `json:"namespace"`
Name string `json:"name"`
Type string `json:"type"`
Aliases []string `json:"aliases"`
Summary string `json:"summary"`
Attributes map[string]string `json:"attributes"`
Metadata map[string]string `json:"metadata,omitempty"`
MentionCount int64 `json:"mention_count"`
FirstSeenAt time.Time `json:"first_seen_at"`
LastSeenAt time.Time `json:"last_seen_at"`
}
Entity mirrors types.Entity.
type EntityList ¶
type EntityList struct {
Contract
Entities []Entity `json:"entities"`
NextCursor string `json:"next_cursor,omitempty"`
Count int `json:"count"`
}
EntityList is the entity_list response.
func NewEntityList ¶
func NewEntityList(r *entity.ListResult) EntityList
NewEntityList maps an engine list result.
type EntityMention ¶
type EntityMention struct {
ID string `json:"id"`
EntityID string `json:"entity_id"`
Namespace string `json:"namespace"`
SourceType string `json:"source_type"`
SourceID string `json:"source_id"`
Context string `json:"context"`
Snippet string `json:"snippet"`
CreatedAt time.Time `json:"created_at"`
}
EntityMention mirrors types.EntityMention.
type EntityMerge ¶
type EntityMerge struct {
Contract
KeptEntity *Entity `json:"kept_entity"`
MergedMentions int `json:"merged_mentions"`
MergedRelationships int `json:"merged_relationships"`
}
EntityMerge is the entity_merge response.
func NewEntityMerge ¶
func NewEntityMerge(r *entity.MergeResult) EntityMerge
NewEntityMerge maps an engine merge result.
type EntityQuery ¶
type EntityQuery struct {
Contract
Entity *Entity `json:"entity,omitempty"`
Relationships []EntityRelationship `json:"relationships,omitempty"`
Mentions []EntityMention `json:"mentions,omitempty"`
Found bool `json:"found"`
}
EntityQuery is the entity_query response.
func NewEntityQuery ¶
func NewEntityQuery(r *types.EntityQueryResponse) EntityQuery
NewEntityQuery maps an engine query result.
type EntityRelationship ¶
type EntityRelationship struct {
ID string `json:"id"`
Namespace string `json:"namespace"`
SourceEntityID string `json:"source_entity_id"`
TargetEntityID string `json:"target_entity_id"`
RelationType string `json:"relation_type"`
Description string `json:"description"`
Confidence float64 `json:"confidence"`
MentionCount int64 `json:"mention_count"`
FirstSeenAt time.Time `json:"first_seen_at"`
LastSeenAt time.Time `json:"last_seen_at"`
}
EntityRelationship mirrors types.EntityRelationship.
type EntityRelationships ¶
type EntityRelationships struct {
Contract
Relationships []EntityRelationship `json:"relationships"`
}
EntityRelationships is the entity_relationships response. It wraps the relationship list in an object (with schema_version) so the tool can declare an object-rooted output schema per the MCP spec.
func NewEntityRelationships ¶
func NewEntityRelationships(rels []*types.EntityRelationship) EntityRelationships
NewEntityRelationships maps a relationships result.
type EntityResult ¶
type EntityResult struct {
Entity *Entity `json:"entity"`
Score float64 `json:"score"`
Rank int `json:"rank,omitempty"`
}
EntityResult mirrors types.EntityResult.
type EntitySearch ¶
type EntitySearch struct {
Contract
Results []EntityResult `json:"results"`
Query string `json:"query"`
TotalFound int `json:"total_found"`
}
EntitySearch is the entity_search response.
func NewEntitySearch ¶
func NewEntitySearch(r *entity.SearchResult) EntitySearch
NewEntitySearch maps an engine search result.
type EntityUpdate ¶
EntityUpdate is the entity_update response.
func NewEntityUpdate ¶
func NewEntityUpdate(e *types.Entity) EntityUpdate
NewEntityUpdate maps an updated entity.
type KnowledgeBulkIngest ¶
type KnowledgeBulkIngest struct {
Contract
CollectionID string `json:"collection_id"`
TotalDocuments int `json:"total_documents"`
Succeeded int `json:"succeeded"`
Failed int `json:"failed"`
TotalChunks int `json:"total_chunks"`
Documents []BulkIngestDoc `json:"documents"`
}
KnowledgeBulkIngest is the knowledge_bulk_ingest response.
func NewKnowledgeBulkIngest ¶
func NewKnowledgeBulkIngest(r *knowledge.BulkIngestResult) KnowledgeBulkIngest
NewKnowledgeBulkIngest maps an engine bulk ingest result.
type KnowledgeCollectionCreated ¶
type KnowledgeCollectionCreated struct {
Contract
Collection
}
KnowledgeCollectionCreated is the knowledge_collections create response.
func NewKnowledgeCollectionCreated ¶
func NewKnowledgeCollectionCreated(c *types.Collection) KnowledgeCollectionCreated
NewKnowledgeCollectionCreated maps a created collection.
type KnowledgeCollectionDeleted ¶
KnowledgeCollectionDeleted is the knowledge_collections delete response.
func NewKnowledgeCollectionDeleted ¶
func NewKnowledgeCollectionDeleted() KnowledgeCollectionDeleted
NewKnowledgeCollectionDeleted maps a deleted collection response.
type KnowledgeCollectionList ¶
type KnowledgeCollectionList struct {
Contract
Collections []Collection `json:"collections"`
NextCursor string `json:"next_cursor"`
}
KnowledgeCollectionList is the knowledge_collections list response.
func NewKnowledgeCollectionList ¶
func NewKnowledgeCollectionList(cols []*types.Collection, nextCursor string) KnowledgeCollectionList
NewKnowledgeCollectionList maps a collections list result.
type KnowledgeIngest ¶
type KnowledgeIngest struct {
Contract
DocumentID string `json:"document_id"`
ChunksCreated int `json:"chunks_created"`
CollectionID string `json:"collection_id"`
}
KnowledgeIngest is the knowledge_ingest response.
func NewKnowledgeIngest ¶
func NewKnowledgeIngest(r *knowledge.IngestResult) KnowledgeIngest
NewKnowledgeIngest maps an engine ingest result.
type KnowledgeSearch ¶
type KnowledgeSearch struct {
Contract
Results []ChunkResult `json:"results"`
Query string `json:"query"`
TotalFound int `json:"total_found"`
}
KnowledgeSearch is the knowledge_search response.
func NewKnowledgeSearch ¶
func NewKnowledgeSearch(r *knowledge.SearchResult) KnowledgeSearch
NewKnowledgeSearch maps an engine search result.
type Message ¶
type Message struct {
ID string `json:"id"`
Namespace string `json:"namespace"`
ThreadID string `json:"thread_id"`
Role string `json:"role"`
Content string `json:"content"`
Metadata map[string]string `json:"metadata,omitempty"`
SourceUser string `json:"source_user,omitempty"`
TenantID string `json:"tenant_id,omitempty"`
Summarized bool `json:"summarized,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
Message mirrors the wire shape of types.Message.
Source Files