Python API

care-voice is usable as a library. The main entry points are the service, the session, the extractors, and the rule engine. This page is generated from the docstrings.

Service

care_voice.service.CareVoice dataclass

The assembled application: script, extractor, rules, store, and notifiers.

process(result)

Store result, evaluate the rules, store and deliver the alerts.

Configuration

care_voice.config.load_config(path)

Load path, or return the defaults when path is None.

care_voice.config.Config dataclass

resolve(path)

Resolve path relative to the config file's directory.

Conversation

care_voice.engine.CheckinSession

One check-in conversation.

Call :meth:start for the opening line, then pass each reply to :meth:respond until :attr:done is true. :meth:result returns the structured outcome.

start()

Return the greeting and the first question.

hang_up()

Record that the person ended the call before the script finished.

respond(utterance)

Process one reply and return the agent's next line.

None or an empty string means silence. Returns None once the session is over.

result()

Return the structured outcome. Safe to call before the session ends.

care_voice.engine.Channel

Bases: Protocol

A synchronous, turn-by-turn connection to the person.

connect()

Try to reach the person. Return False if nobody answers.

say(text)

Speak or print one agent line.

listen()

Return the next reply, "" for silence, or None if the person hung up.

close()

Release the connection.

care_voice.engine.run_checkin(make_session, channel, retry=None, sleep=time.sleep)

Run a full check-in over channel, retrying when nobody answers.

Scripts

care_voice.script.load_script(path=None)

Load a script from path, or the bundled default when path is None.

care_voice.script.CheckinScript dataclass

A parsed check-in script.

iter_all()

Yield every question, including follow-ups, depth first.

care_voice.script.Question dataclass

One question in a check-in script.

is_problem_question property

True when a "yes" answer reports a problem (for example, "Are you in pain?").

Extractors

care_voice.extractors.base.Extractor

Bases: Protocol

Maps one utterance, in reply to one question, to a structured answer.

Implementations must never raise on odd input. When they cannot map the utterance to a value they return an :class:Answer with understood=False so that the engine can re-ask.

extract(question, utterance, context)

Return the structured answer for utterance.

care_voice.extractors.rules.RuleBasedExtractor

Offline extractor. No network, no API key, fully deterministic.

care_voice.extractors.llm.LLMExtractor

Extractor that asks an OpenAI-compatible model, with a rule-based safety net.

Rules

care_voice.risk.RiskEngine

Evaluates rules against a check-in and returns alerts, most severe first.

evaluate(result, history=())

Return alerts for result.

history holds earlier check-ins for the same person, newest first.

care_voice.risk.RiskConfig dataclass

Thresholds for the built-in rules.

Models

care_voice.models.CheckinResult dataclass

Everything the risk engine and the store need about one check-in.

care_voice.models.Answer dataclass

A structured answer extracted from one utterance.

value holds the normalized answer: bool for yes/no questions, int for scale questions, a weekday name for day-of-week questions, and the raw text for free-text questions. understood is False when the extractor could not map the utterance to a value.

care_voice.models.Alert dataclass

A caregiver-facing alert produced by the risk engine.

care_voice.models.Severity

Bases: IntEnum

Alert severity, ordered so that comparisons work (HIGH > LOW).

Storage

care_voice.store.Store

A thin wrapper around a SQLite database file (or :memory:).

save_checkin(result)

Insert result and set its id.

history(person, before=None, limit=30)

Return up to limit check-ins for person, newest first.