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 



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

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 ─────────────────────────────────────────────



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
184
185
186
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 149

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").'

    params 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 



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
222
223
224
 
# File 'app/services/assistant/sales_management/employee_tools.rb', line 188

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.'

    params 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) 


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

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 



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

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 



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

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 ──────────────────────────────────────────────



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

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 



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

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 ──────────────────────────────────────



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

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 



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

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 



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

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