Tools Organization Structure

Tools Organization Structure

This document describes the organization of the 20 graph query tools for AI agent access.

Organization Principles

1. Shared Parameters: Common filter structures are defined once in internal/models/tools/common.go
2. Category-based Files: Tools are organized into 8 category files
3. Consistent Naming: All requests end with Request, responses with Response
4. Composable Filters: Tools embed common filter structs for consistency
5. Embedded Defaults: Each request has a SetDefaults() method

File Structure

internal/models/tools/
├── common.go           # Shared parameter structures
├── user_context.go     # User Context Tools (5 tools)
├── products.go         # Product Discovery Tools (3 tools)
├── temporal.go         # Temporal Tools (2 tools)
├── offers.go           # Offer Tools (3 tools)
├── brands.go           # Brand Tools (3 tools)
├── retailers.go        # Retailer Tools (2 tools)
├── collaborative.go    # Collaborative Tools (2 tools)
└── composition.go      # Composition Tool (1 tool)

Shared Parameter Structures

Defined in internal/models/tools/common.go:

Structure	Fields	Used By
UserFilter	user_id	ALL 20 tools (required)
TimeFilter	lookback_days, as_of	12 tools
CategoryFilter	category, categories	13 tools
BrandFilter	brand, brands	9 tools
ProductFilter	Embeds Category + Brand + name_pattern	3 tools
RetailerFilter	retailer_id	3 tools
PaginationParams	limit, offset	18 tools
SimilarityParams	min_similarity, max_similar	3 tools
OfferFilter	min_points, search_term	1 tool
RepurchaseParams	min_intervals, prediction_window, min_days	1 tool
CollaborativeParams	same_zip_only, min_shared_products	1 tool

Tool Categories

1. User Context Tools (5 tools)

File: user_context.go

Understand user behavior and preferences.

Tool	Request Type	Response Type	Key Features
get_user_purchase_history	PurchaseHistoryRequest	PurchaseHistoryResponse	Recent purchases with details
get_user_categories	UserCategoriesRequest	UserCategoriesResponse	Category-level aggregations
get_user_brands	UserBrandsRequest	UserBrandsResponse	Brand preferences and loyalty
get_purchase_patterns	PurchasePatternsRequest	PurchasePatternsResponse	Repurchase patterns
get_category_brand_affinity	CategoryBrandAffinityRequest	CategoryBrandAffinityResponse	Brand preference within category

Embedded Filters: UserFilter, TimeFilter, PaginationParams

2. Product Discovery Tools (3 tools)

File: products.go

Find and explore products.

Tool	Request Type	Response Type	Key Features
search_products	SearchProductsRequest	SearchProductsResponse	Search with category/brand/name filters
find_similar_products	SimilarProductsRequest	SimilarProductsResponse	Similarity-based recommendations
find_alternatives_in_category	AlternativesRequest	AlternativesResponse	Untried products in category

Embedded Filters: UserFilter, ProductFilter, SimilarityParams, PaginationParams

3. Temporal Tools (2 tools)

File: temporal.go

Time-based queries and predictions.

Tool	Request Type	Response Type	Key Features
predict_repurchases	RepurchasePredictionRequest	RepurchasePredictionResponse	When user needs products again
get_purchase_timeline	PurchaseTimelineRequest	PurchaseTimelineResponse	Historical purchase timeline

Embedded Filters: UserFilter, TimeFilter, RepurchaseParams, CategoryFilter, BrandFilter, PaginationParams

4. Offer Tools (3 tools)

File: offers.go

Rewards and promotion discovery.

Tool	Request Type	Response Type	Key Features
get_active_offers	ActiveOffersRequest	ActiveOffersResponse	User’s eligible offers
match_products_to_offers	MatchProductsToOffersRequest	MatchProductsToOffersResponse	Check which products have offers
search_offers	SearchOffersRequest	SearchOffersResponse	Advanced offer search

Embedded Filters: UserFilter, CategoryFilter, BrandFilter, RetailerFilter, OfferFilter, PaginationParams

5. Brand Tools (3 tools)

File: brands.go

Brand exploration and comparison.

Tool	Request Type	Response Type	Key Features
get_brand_products	BrandProductsRequest	BrandProductsResponse	All products from a brand
compare_brands	CompareBrandsRequest	CompareBrandsResponse	Side-by-side brand comparison
discover_brands_in_category	DiscoverBrandsRequest	DiscoverBrandsResponse	All brands in category

Embedded Filters: UserFilter, CategoryFilter, BrandFilter, PaginationParams

6. Retailer Tools (2 tools)

File: retailers.go

Store preferences and retailer-specific offers.

Tool	Request Type	Response Type	Key Features
get_user_retailers	UserRetailersRequest	UserRetailersResponse	Where user shops
get_retailer_offers	RetailerOffersRequest	RetailerOffersResponse	Offers at specific retailer

Embedded Filters: UserFilter, TimeFilter, RetailerFilter, CategoryFilter, PaginationParams

7. Collaborative Tools (2 tools)

File: collaborative.go

Social recommendations and local trends.

Tool	Request Type	Response Type	Key Features
get_collaborative_recommendations	CollaborativeRecommendationsRequest	CollaborativeRecommendationsResponse	”People like me” recommendations
get_local_trending_products	LocalTrendingRequest	LocalTrendingResponse	Popular in user’s zip code

Embedded Filters: UserFilter, CategoryFilter, CollaborativeParams, TimeFilter, PaginationParams

8. Composition Tool (1 tool)

File: composition.go

Deep context aggregation.

Tool	Request Type	Response Type	Key Features
get_product_context	ProductContextRequest	ProductContextResponse	Comprehensive product context

Embedded Filters: UserFilter, SimilarityParams

Naming Conventions

Request Structs

• Pattern: {ToolName}Request
• Example: PurchaseHistoryRequest, SearchProductsRequest
• All embed UserFilter (user_id is always required)
• All have SetDefaults() method

Response Structs

• Pattern: {ToolName}Response
• Example: PurchaseHistoryResponse, SearchProductsResponse
• All include: UserID, data field(s), Count, GeneratedAt

Item Structs

• Pattern: Descriptive noun (e.g., PurchaseHistoryItem, BrandStats, TrendingProduct)
• Represent individual items in response arrays

Default Values Summary

Parameter	Default	Max	Applied By
lookback_days	Varies by tool	N/A	12 tools
limit	Varies by tool	Varies	18 tools
min_similarity	0.6	1.0	3 tools
max_similar	5	50	2 tools
min_intervals	2	N/A	2 tools
prediction_window	14 days	N/A	1 tool
min_shared_products	2	N/A	1 tool
same_zip_only	false	N/A	1 tool

Usage Example

import "internal/models/tools"

// Create a request with embedded filters
req := &tools.PurchaseHistoryRequest{
    UserFilter: tools.UserFilter{
        UserID: "USER123",
    },
    TimeFilter: tools.TimeFilter{
        LookbackDays: 90, // Override default 180
    },
    PaginationParams: tools.PaginationParams{
        Limit: 20, // Override default 50
    },
}

// Apply defaults
req.SetDefaults()

// Make request
response, err := repo.GetPurchaseHistory(ctx, req)

Benefits of This Organization

1. DRY (Don’t Repeat Yourself): Common parameters defined once
2. Type Safety: Strong typing with Go structs
3. Discoverability: Related tools grouped together
4. Maintainability: Easy to update shared parameters
5. Consistency: All tools follow same patterns
6. Documentation: Clear structure makes code self-documenting
7. Testability: Consistent interfaces easy to mock
8. Extensibility: Easy to add new tools or parameters

Next Steps

1. Implement Repository Methods: Create methods in internal/graph/repository/ for each tool
2. Create Service Layer: Add business logic and caching in service layer
3. Add HTTP Handlers: Expose tools as REST endpoints
4. Agent Integration: Register tools with LLM function calling
5. Add Tests: Unit tests for each tool
6. Add Caching: Tool-specific caching strategies

Migration from Old Structure

The old recommendation.go models can be gradually migrated:

Old Model	New Location
RecommendationRequest	Keep in recommendation.go (existing endpoint)
RepurchaseRequest	Keep in recommendation.go (existing endpoint)
PurchaseHistoryRequest	tools/user_context.go (moved)

This allows gradual migration without breaking existing endpoints.