Reference Guides

Reference Guides

Introduction

Locusive uses an AI-powered autonomous agent to answer your users' questions, analyze data, and perform actions within your product. For this, Locusive may need access to your various tools and data sources, such as databases or Salesforce, through integrations. While these integrations provide Locusive with a foundational understanding of your data, sometimes it requires additional context to understand how to navigate your data structures effectively. This is where Reference Guides come in.

Reference guides allow you to supplement the AI's knowledge about your tools and data sources, offering detailed insights that the system can use to provide more accurate responses to users' queries.

How Reference Guides Work

Whenever Locusive needs to handle a user's request, it reviews the available integrations in your account to identify the appropriate actions and data sources for fulfilling that request. If an integration has an associated reference guide, Locusive uses that guide to better understand the context and relationships within your data. This helps the AI to:

  1. Make Accurate Queries: Use the right data sources, relationships, and tables to form accurate database queries.
  2. Understand Complex Structures: Navigate intricate data structures, such as foreign key relationships or unique constraints, that would otherwise require manual intervention.
  3. Perform Context-Aware Actions: Ensure any actions taken in your product are relevant and correctly aligned with the users' needs and your business context.

Supported Integrations for Reference Guides

Currently, reference guides are available for Salesforce and Database integrations. You can create a reference guide by navigating to the Integrations page, selecting the relevant integration, and clicking on the Reference Guide tab.

When and Why to Use a Reference Guide

1. When Your Data Structure is Complex

If your database has intricate relationships between tables, multiple foreign keys, or special rules around data usage, a reference guide helps Locusive understand these nuances. For example, if your system has a hierarchy of entities like accounts, workspaces, and programs, and Locusive needs to navigate through these relationships to find user information, a guide can provide the AI with a blueprint for constructing accurate queries.

Best Practice: Map out the hierarchy, including foreign key relationships, and detail any rules for querying. For instance, always filter certain tables (like accounts) unless explicitly instructed not to.

2. When Certain Data Should Be Treated Differently

In some cases, particular data in your system may have unique requirements for how it should be handled. For example, if certain columns or tables should never be aggregated or should always be treated as unique, this information is crucial for Locusive to understand. In a scenario where goals are recorded as free-form text and should not be aggregated, your reference guide should clearly specify these rules.

Best Practice: Identify special data types or columns that need unique treatment (e.g., free-form text, unique identifiers) and specify how they should be queried or not queried.

3. When You Have Defined Lists or Categories

If your system includes a set of defined items—such as skills, product categories, or geographic regions—it's important to include these in your reference guide. For instance, providing the complete list of skills in a skills table or all the time zones within a database helps the AI understand the scope of each category. It can also guide the AI on how to group or filter data based on these categories.

Best Practice: Include complete lists for any standardized categories or classifications in your data, such as skills, time zones, or product types. These lists help Locusive provide context-aware suggestions and analyses.

4. When You Have Special Context or Restrictions on Certain Tables

If certain tables in your database should be joined selectively or avoided in certain contexts, these rules should be part of your guide. For example, you might have data that should only be accessed under specific circumstances, such as internal-use tables or ones that require filtering by user permissions.

Best Practice: List tables that require special consideration when joined or queried. Provide examples or rules for when and how to join them appropriately.

5. When Context is Needed for User Responses

In some cases, data stored in your system might not be immediately clear to users. For example, survey responses stored as text arrays (e.g., {Agree}) need context to be meaningful. Your reference guide can help by providing background information on how to interpret these responses, ensuring that Locusive provides complete and comprehensible answers to users.

Best Practice: Document how different data types should be presented in responses, especially if they involve complex structures like text arrays, JSON objects, or encoded data.

What to Include in Your Reference Guide

Here's a checklist of key elements to consider when building a reference guide for your integration:

  1. Database Structure and Relationships
    Describe the hierarchy of tables, primary and foreign keys, and relationships between entities. For instance, specify how to navigate from an account to a user by detailing the joins required between tables like accounts, workspaces, programs, and users.

  2. Query Rules and Constraints
    Provide rules for filtering, aggregating, or joining tables. Highlight any constraints such as "always filter by account unless specified otherwise" or "never aggregate goals."

  3. Standardized Lists and Classifications
    Include all predefined categories, such as skills, time zones, product types, or other standard lists that may be used in queries. This helps Locusive understand the full range of possible values and how to apply them in responses.

  4. Special Table Context
    Detail any tables that have specific use cases or access restrictions, and how they should be queried. For example, highlight tables that are only for internal use or that require special conditions for access.

  5. Contextual Explanations for Users
    Include explanations for complex data types or structures that Locusive should incorporate into user-facing responses. Ensure that any derived or processed data (like survey responses) is accompanied by an explanation of how to interpret it.

Reference Guide Concepts

If you're not sure what to put in your reference guide, here are some categories to consider:

  • Entity Relationships: How different entities in your database relate to each other and the foreign keys that link them.
  • Unique Constraints and Handling: Specific data columns or tables that need special consideration (e.g., free-form text, unique rows).
  • Predefined Values: Lists of skills, categories, regions, or other predefined values stored in your database.
  • Access Control Rules: Any conditions or restrictions on when certain data can be accessed or how it should be queried.
  • Interpretation Guidelines: Guidance on how to interpret complex data types, particularly those that might not be intuitive for users.

By taking the time to craft a detailed reference guide, you can significantly improve Locusive's ability to understand your data and perform accurate, context-aware queries and actions, providing a seamless experience for both your team and your customers.

Example Reference Guide

To make the process of creating reference guides easier, here's a fictional reference guide for a database belonging to a company called FitnessPro, which provides personalized fitness training and wellness coaching to clients through an online platform.

  1. # Reference Guide: FitnessPro Database

  3. ## Database Structure

  5. ### 1. Clients and Personal Trainers
  6. - Clients are stored in the `clients` table, with a unique `client_id` and fields such as `name`, `email`, `registration_date`, and `membership_type`.
  7. - Personal trainers are stored in the `trainers` table, with a unique `trainer_id`. Each trainer has fields like `name`, `specializations`, and `availability`.

  9. **Rules for Queries:**
  10. - Always filter results by `client_id` or `trainer_id` unless explicitly requested not to.
  11. - Use `trainers.specializations` to match a client with the appropriate trainer based on their fitness goals.
  12.   
  13. **Joining Relationships:**
  14. - A client can have multiple trainers over time, and a trainer can work with multiple clients.
  15. - To find all trainers for a specific client, join `client_trainers` (many-to-many linking table) on `client_trainers.client_id = clients.client_id` and `client_trainers.trainer_id = trainers.trainer_id`.

  17. ---

  19. ### 2. Fitness Programs and Sessions
  20. - Fitness programs are stored in the `programs` table, which includes details like `program_name`, `program_type`, and `difficulty_level`.
  21. - A program can have multiple sessions stored in the `sessions` table, with fields `session_id`, `session_date`, `duration`, and `notes`.

  23. **Joining Programs and Sessions:**
  24. - Each session is part of a program and linked through `sessions.program_id = programs.program_id`.
  25. - To find all sessions for a specific program, join `sessions` on `sessions.program_id = programs.program_id`.

  27. ---

  29. ### 3. Goals and Progress Tracking
  30. - Each client has fitness goals stored in the `goals` table. A goal can be weight loss, muscle gain, or wellness, and is stored with fields like `goal_description`, `target_date`, and `goal_status`.
  31. - Progress is tracked through the `progress` table, with fields such as `progress_date`, `current_weight`, `current_fitness_level`, and `progress_notes`.

  33. **Rules for Goals and Progress:**
  34. - Each goal is unique to a client and should not be aggregated or averaged.
  35. - Join `goals` to `progress` via `goals.client_id = progress.client_id`.

  37. **Special Instructions:**
  38. - When returning progress for a client, always provide context around their goal and how far they've come since setting the goal.

  40. ---

  42. ### 4. Workout Plans and Exercises
  43. - Workout plans are stored in the `workout_plans` table and contain a `plan_name`, `plan_duration`, and `goal_type` (which indicates if it’s for weight loss, strength training, etc.).
  44. - Each workout plan consists of multiple exercises found in the `exercises` table, with fields like `exercise_name`, `repetitions`, `sets`, `exercise_type`, and `equipment_required`.

  46. **Linking Workout Plans to Exercises:**
  47. - Join `workout_plan_exercises` on `workout_plan_exercises.plan_id = workout_plans.plan_id` and `workout_plan_exercises.exercise_id = exercises.exercise_id` to get all exercises in a workout plan.
  48. - The `goal_type` of a workout plan should align with the client’s `goals.goal_description` when making recommendations.

  50. ---

  52. ### 5. Nutrition Plans and Meals
  53. - Nutrition plans are stored in the `nutrition_plans` table and include fields such as `plan_name`, `calorie_limit`, `diet_type` (e.g., vegan, keto, balanced), and `goal_type`.
  54. - Each nutrition plan includes meals, which are stored in the `meals` table with fields `meal_name`, `meal_time` (breakfast, lunch, dinner, snack), and `calories`.

  56. **Linking Nutrition Plans to Meals:**
  57. - To find meals within a nutrition plan, join `nutrition_plan_meals` on `nutrition_plan_meals.plan_id = nutrition_plans.plan_id` and `nutrition_plan_meals.meal_id = meals.meal_id`.

  59. **Guidelines for Queries:**
  60. - Align the `nutrition_plans.goal_type` with the client’s `goals.goal_description` to ensure meal recommendations are relevant to their fitness journey.
  61. - When presenting a nutrition plan, always provide the `plan_name`, `diet_type`, and a breakdown of meals by `meal_time`.

  63. ---

  65. ## Special Context for Queries

  67. ### Unique Constraints
  68. - `goal_description` is free-form text and should not be aggregated.
  69. - `specializations` in the `trainers` table can contain multiple specialties (e.g., strength training, yoga) as an array of values.

  71. ### Data Handling Rules
  72. - **Progress Tracking**: When displaying progress, provide both qualitative (`progress_notes`) and quantitative (`current_weight`, `current_fitness_level`) insights.
  73. - **Time Zones**: Sessions and progress entries are stored in UTC. Convert times to the client’s preferred time zone, found in the `clients.timezone` field, when returning results.

  75. ### Predefined Categories
  76. - `program_type` in the `programs` table can be one of:  
  77.   - **Strength Training**
  78.   - **Cardio**
  79.   - **Yoga/Pilates**
  80.   - **HIIT (High-Intensity Interval Training)**
  81.   - **Mixed Fitness**
  82.   
  83. - `diet_type` in `nutrition_plans` includes:  
  84.   - **Balanced**
  85.   - **Vegan**
  86.   - **Keto**
  87.   - **Low-Carb**
  88.   - **High-Protein**

  90. ### Common User Scenarios
  91. - **Finding a Client’s Trainer(s)**: Join `clients`, `client_trainers`, and `trainers` to find the trainers associated with a client.
  92. - **Generating a Client’s Progress Report**: Retrieve all `progress` entries linked to the client's `goals`, and compare with initial values when the goal was set.
  93. - **Recommending a Workout/Nutrition Plan**: Filter `workout_plans` and `nutrition_plans` based on the client’s active `goals` and `goal_type`.

This example guide provides clear details on relationships, constraints, best practices for querying, and contextual guidance that can significantly improve how Locusive handles complex requests for the fictional FitnessPro database.



    • Related Articles

    • Google Drive Integration

      Locusive's system allows you to select the Google Drive folders you'd like to add to your knowledge base. By connecting your Google Drive integration, you'll be able to select the folders from your Drive account that you'd like our system to monitor ...

    • Salesforce Integration

      Our chatbot and API allow you to integrate your Salesforce account via the Salesforce API. This article covers the basics of how it works and what you can expect. Integrating With Salesforce Locusive allows you to connect to your Salesforce account ...

    • Google Sheets Integration

      Our chatbot and API allow you to integrate your Google Sheets data by pre-authorizing your Google Sheets account, and then allowing you to select the Google Sheets that you want to use for your knowledge base. Authorizing Access To get started, ...

    • Database Integration

      Our chatbot and API allow you to integrate your relational databases by providing connection information that we can use to run read-only queries on your system. Introduction When you send a request to the system, it will figure out where to get the ...

    • Example Queries

      What are Example Queries? Example queries in Locusive serve as predefined questions and SQL queries that help guide the system to access and interact with your database efficiently. They are one of the most powerful tools you can use to ensure that ...