pinecallDocs
Ruby / The voice app

The voice app

What goes around the agents in Ruby: app.rb with its lines, rules, teams and flows, the tasks a tool asks for, and the caller's screen.

What a project adds around its agents: the numbers it answers and who answers each (the voice app), what a tool asks the caller for in the middle of it (tasks), and what the caller sees on a page of yours (the screen). Each is optional. The TypeScript and Python packages have the same three.

A tool that asks: tasks#

Ruby
class FrontDesk < Pinecall::Agent
  tasks Pinecall::GetEmail

  # Book a time, once the caller said yes to it.
  tool
  def book(slot:)
    email = ask(Pinecall::GetEmail)
    Clinic.book(slot, email)
  end
end

A task is one thing a tool needs from the caller before it can finish. ask(Pinecall::GetEmail) stops the tool there, on its own thread: the model is told what is missing and how to ask, asks the caller, and gives the answer with a tool of the task's own (give_email), the only tool open meanwhile. The task checks what it was given, and one that does not pass is asked for again. Then ask returns the value, and what the tool returns is what the model reads, as { finished: "book", result: … }. One question at a time.

Three come with the gem: Pinecall::GetEmail, Pinecall::GetPhone and Pinecall::GetName. One of your own:

Ruby
GetPlate = Pinecall.task("plate", asks: "the plate of the car", how: "Read it back letter by letter.",
                                  fields: { plate: "The plate, letters and digits, no spaces." }) do |given|
  plate = given["plate"]
  raise ArgumentError, "\"#{plate}\" is not a plate. Ask for it again." unless plate.match?(/\A[A-Z0-9]{5,8}\z/i)

  plate.upcase
end

fields is what the model gives, each a string with what it is; the block returns what your tool is handed, and what it raises is told to the model. A class names the tasks its tools ask for with tasks; a call that ends with a question open makes ask raise, so the tool does not go on.

The voice app: the project's lines#

Ruby
# app.rb
APP = Pinecall.voice_app("brightside", timezone: "America/Los_Angeles")
APP.line("+1 415 555 0134", FrontDesk, greeting: "Brightside Dental. How can I help?")
APP.silence(after: "8s", say: "Are you still there?", times: 2)

A project may have an app.rb beside agents/. pinecall start loads the agents first and then the app, so it names their classes as they are; the file makes one Pinecall.voice_app(…). The greeting is that agent's greeting, declared by the app, and silence is its idle; a class that declares either itself and gets one from the app too is refused when the app loads. timezone is the zone every agent of the app reads its day and clock in, the same setting as a class's timezone.

APP.page("ui/dist") gives the app a page, sent with pinecall deploy and served at https://<app>--<org>.app.pinecall.io; pinecall start serves the same folder on http://localhost:4747 (PINECALL_PAGE_PORT names another port) with your key and no captcha, its ticket, its code and its dictation asked at /pinecall/token, /pinecall/code and /pinecall/dictation. APP.page("site", only: "sandbox") keeps the page to one environment ("sandbox" or "production"): a deploy to the other sends the app alone, with no page.

What the app hears#

Ruby
APP.on("visit.booked") { |call, visit| Reminders.schedule(visit) }
APP.on("call.ended") { |call, ended| DB.calls.insert(call: call.id, reason: ended[:reason]) }

The name is an entry of the call's log by its type (call.ended, call.score, handoff, routed), or a line an agent logs by its own name (log("visit.booked", visit)). A block that raises is said in the terminal, and the others run.

A flow: what outlives a call#

Ruby
RemindVisit = Pinecall.flow("remind-visit") do |visit, step|
  step.sleep_until(visit[:at], before: "24h")
  called = step.call(visit[:phone], Reminder, instruction: "Remind #{visit[:patient]} of the visit.")
  step.run { DB.visits.update(visit[:id], reminded: called.answered) }
end
RemindVisit.cancel_on("visit.cancelled") { |gone, visit| gone[:id] == visit[:id] }
APP.on("visit.booked", RemindVisit)

A flow is a name and a block of what started it and its steps. The gateway keeps each run's journal, so a run outlives a deploy; each time it is woken the block runs again from the top and every step already in the journal answers what it came to. What must happen once goes inside step.run.

step what it does
step.sleep("2h") the run sleeps: a number and s, m, h or d
step.sleep_until(at, before: "24h") until a Time or an ISO string, or that long before it
step.call(to, Agent, state:, metadata:, greeting:, instruction:, from:) the agent calls the number; a Flow::Called says how it ended, or why nothing rang
step.text(to, Agent, words, from:) the agent sends the contact one SMS first; a Flow::Texted says the call it was said on, or why nothing was sent
step.wait_for(event, match:, within:) an event sent to the app whose data has what match names; nil once within passed
step.run { … } your own code, once; what it returned is kept
step.emit(name, data) sends an event to the app

Rules, a team, and a line that chooses#

Ruby
APP.rule("Never quote a price that is not in the price list.")

class Billing < Pinecall::Agent
  takes "a question about a charge, an invoice or a refund"
end

APP.line("+1 415 555 0135", ->(call) { Clinic.closed?(call.today) ? AfterHours : nil },
         fallback: FrontDesk, team: [AfterHours, Billing])

A rule is read into every agent's prompt and judged (app-rule-1, …), by a judge that reads the call and its evidence (the documents searched, the tools' answers, the state). A teammate that takes something is offered as a tool named by its class (transfer_to_billing); a tool can pass the call itself with call.handoff(Billing, invoice:), and the teammate reads call.handed; call.shared is what the agents of one call share. A line's lambda chooses who answers; the fallback answers when it returns nil, raises, takes more than a second or names an agent outside the team.

The caller's page: screen#

Ruby
Agenda = Pinecall.part("agenda")

class FrontDesk < Pinecall::Agent
  scenes agenda: "the open times you last read"

  # Reads the open times of a day.
  tool shows: :agenda
  def free_slots(day:) = Clinic.free(day)

  def screen
    return Form.(**call.asking.to_h) unless call.asking.nil?

    Agenda.(day: "lunes") if call.scene == "agenda"
  end
end

screen is what the caller's page shows now: parts (Agenda.(slots:), which nest), words, arrays of them. It travels in the call's state as the public field screen. A tool with shows: puts its scene up once it ran; a turn of the caller that showed nothing takes it away. The model is given show_screen to keep a scene, put another up or take it away with none. call.show(part) puts a part over the screen from a tool or a hook. A page that shows a task's form gives the answer with the event task.give, in the model's place.