Module: Assistant::SalesManagement::EmployeeTools

Defined in:
app/services/assistant/sales_management/employee_tools.rb

Overview

Tools that resolve the team itself — find_employee for name/role
lookups and get_team_availability for who's working / off / on PTO
for a given date or range.

Constant Summary collapse

MAX_RESULTS = 
50

Class Method Summary collapse

Class Method Details

.build_employee_day_entry(emp, day) ⇒ Object 



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 126

def build_employee_day_entry(emp, day)
  status = emp.work_status_on_day(day)
  working = emp.working_on_day?(day)
  capacity = emp.capacity_ratio(day)
  hours = emp.working_hours_on_date(day)

  entry = {
    id: emp.id,
    name: emp.full_name,
    status: status.to_s,
    working: working,
    capacity: capacity,
    scheduled_hours: hours
  }

  entry[:phone_presence] = emp.presence.to_s if day == Date.current && emp.employee_phone_status
  entry.compact
end

.build_find_employee_tool ⇒ Object

─── Tool factories ─────────────────────────────────────────────



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 146

def build_find_employee_tool
  klass = Class.new(RubyLLM::Tool) do
    description 'Find employees by name or role. Returns employee details ' \
                'including ID, name, job title, manager, sales rep flags, ' \
                'and current work status. Use this to look up any team member — ' \
                'supports partial name matching (e.g. "Pedro", "Smith").'

    parameters type: 'object',
           properties: {
             name: {
               type: 'string',
               description: 'Full or partial name to search (e.g. "Pedro", "John Smith")'
             },
             role: {
               type: 'string',
               description: 'Filter by role: "sales_rep", "primary_sales_rep", "secondary_sales_rep", ' \
                            '"local_sales_rep", "engineer", "technical_support_rep", or any role name',
               enum: %w[sales_rep primary_sales_rep secondary_sales_rep local_sales_rep engineer technical_support_rep]
             },
             active_only: {
               type: 'boolean',
               description: 'Only return active employees (default: true)'
             },
             include_schedule: {
               type: 'boolean',
               description: 'Include today\'s work status and schedule info (default: true)'
             }
           }

    define_method(:name) { 'find_employee' }
    define_method(:execute) do |name: nil, role: nil, active_only: true, include_schedule: true, **_|
      Assistant::SalesManagement::EmployeeTools.find_employee(
        name: name, role: role, active_only: active_only, include_schedule: include_schedule
      )
    end
  end
  klass.new
end

.build_team_schedule_tool ⇒ Object 



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 185

def build_team_schedule_tool
  klass = Class.new(RubyLLM::Tool) do
    description 'Get team availability and work schedules for a specific date or date range. ' \
                'Shows who is working, who is off (PTO, holiday, etc.), work hours, and capacity. ' \
                'Great for planning coverage and knowing who is available on a given day. ' \
                'Can filter by role (e.g. only sales reps) or specific employee IDs.'

    parameters type: 'object',
           properties: {
             date: {
               type: 'string',
               description: 'Date to check (YYYY-MM-DD format, default: today)'
             },
             end_date: {
               type: 'string',
               description: 'Optional end date for a range (YYYY-MM-DD). Shows each day in range.'
             },
             role: {
               type: 'string',
               description: 'Filter by role: "sales_rep", "primary_sales_rep", etc.'
             },
             employee_ids: {
               type: 'array',
               items: { type: 'integer' },
               description: 'Specific employee IDs to check (overrides role filter)'
             }
           }

    define_method(:name) { 'get_team_availability' }
    define_method(:execute) do |date: nil, end_date: nil, role: nil, employee_ids: nil, **_|
      Assistant::SalesManagement::EmployeeTools.team_availability(
        date: date, end_date: end_date, role: role, employee_ids: employee_ids
      )
    end
  end
  klass.new
end

.employee_is_sales_rep?(emp) ⇒ Boolean

Returns:

  • (Boolean) 


48
49
50
51
52
53
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 48

def employee_is_sales_rep?(emp)
  record = emp.employee_record
  return false unless record

  record.primary_sales_rep || record.secondary_sales_rep || record.local_sales_rep || false
end

.employee_sales_rep_types(emp) ⇒ Object 



55
56
57
58
59
60
61
62
63
64
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 55

def employee_sales_rep_types(emp)
  record = emp.employee_record
  return [] unless record

  [
    ('primary' if record.primary_sales_rep),
    ('secondary' if record.secondary_sales_rep),
    ('local' if record.local_sales_rep)
  ].compact
end

.employee_schedule_fields(emp) ⇒ Object 



66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 66

def employee_schedule_fields(emp)
  today = Date.current
  fields = {
    today_status: emp.work_status_on_day(today).to_s,
    working_today: emp.working_on_day?(today),
    capacity_today: emp.capacity_ratio(today)
  }
  if emp.employee_phone_status
    fields[:phone_presence] = emp.presence.to_s
    fields[:phone_sub_presence] = emp.sub_presence&.to_s
  end
  fields
end

.find_employee(name: nil, role: nil, active_only: true, include_schedule: true) ⇒ Object

─── find_employee ──────────────────────────────────────────────



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 18

def find_employee(name: nil, role: nil, active_only: true, include_schedule: true)
  scope = (active_only ? Employee.active_employees : Employee.all)
          .includes(:employee_record, :employee_phone_status, :contact_points)
  scope = scope.where('parties.full_name ILIKE ?', "%#{name.strip}%") if name.present?
  scope = Helpers.apply_role_scope(scope, role) if role.present?

  employees = scope.sorted.limit(MAX_RESULTS).to_a
  results = employees.map { |emp| serialize_employee_summary(emp, include_schedule: include_schedule) }

  Helpers.truncate_json(
    { query: { name: name, role: role, active_only: active_only }.compact,
      total_results: results.size, employees: results }.to_json
  )
rescue StandardError => e
  { error: e.message }.to_json
end

.serialize_employee_summary(emp, include_schedule:) ⇒ Object 



35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 35

def serialize_employee_summary(emp, include_schedule:)
  base = {
    id: emp.id, name: emp.full_name, job_title: emp.job_title,
    email: emp.email, phone: emp.phone, extension: emp.pbx_extension,
    manager: emp.manager&.full_name, manager_id: emp.parent_id, inactive: emp.inactive?,
    is_sales_rep: employee_is_sales_rep?(emp),
    sales_rep_types: employee_sales_rep_types(emp),
    crm_url: "#{CRM_URL}/employees/#{emp.id}"
  }
  base.merge!(employee_schedule_fields(emp)) if include_schedule
  base.compact
end

.team_availability(date: nil, end_date: nil, role: nil, employee_ids: nil) ⇒ Object

─── get_team_availability ──────────────────────────────────────



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 81

def team_availability(date: nil, end_date: nil, role: nil, employee_ids: nil)
  check_date = date.present? ? Date.parse(date) : Date.current
  range_end  = end_date.present? ? Date.parse(end_date) : check_date
  range_end  = [range_end, check_date + 14].min

  employees = team_availability_employees(role: role, employee_ids: employee_ids)
  employees.each do |emp|
    emp.preload_time_off_events(check_date, range_end)
    emp.preload_working_hours(check_date, range_end)
  end

  days = (check_date..range_end).map { |day| team_availability_day(employees, day) }
  Helpers.truncate_json(
    { date_range: { from: check_date.iso8601, to: range_end.iso8601 },
      total_employees: employees.size, days: days }.to_json
  )
rescue Date::Error => e
  { error: "Invalid date format: #{e.message}. Use YYYY-MM-DD." }.to_json
rescue StandardError => e
  { error: e.message }.to_json
end

.team_availability_day(employees, day) ⇒ Object 



115
116
117
118
119
120
121
122
123
124
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 115

def team_availability_day(employees, day)
  entries = employees.map { |emp| build_employee_day_entry(emp, day) }
  {
    date: day.iso8601,
    day_name: day.strftime('%A'),
    employees: entries,
    working_count: entries.count { |emp| emp[:working] },
    off_count: entries.count { |emp| !emp[:working] }
  }
end

.team_availability_employees(role:, employee_ids:) ⇒ Object 



103
104
105
106
107
108
109
110
111
112
113
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 103

def team_availability_employees(role:, employee_ids:)
  scope = Employee.active_employees.includes(:employee_record, :employee_phone_status, :work_schedules)
  scope = if employee_ids.present?
            scope.where(id: Array(employee_ids))
          elsif role.present?
            Helpers.apply_role_scope(scope, role)
          else
            scope
          end
  scope.sorted.to_a
end

.tools ⇒ Object 



13
14
15
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 13

def tools
  [build_find_employee_tool, build_team_schedule_tool]
end