AI and Agent Orchestration

Five specialized roles

Your Solar Guy plans five focused roles:

Document Extraction Agent, AI: reads manual pages and produces structured evidence.
Calendar Agent, deterministic: calculates dates, applies eligibility rules, and creates calendar output.
Email Evaluator Agent, AI: interprets verified email language and proposes allowed conversation actions.
RAG Q&A Agent, AI: answers questions from retrieved manual evidence.
QA/QC Agent, AI-assisted: reviews extraction, results, email, and calendar artifacts under deterministic release rules.

The model interprets language and documents. Application services retain authority over access, calculations, workflow transitions, approvals, and external actions.

Document extraction and calendar handoff

Documents are divided into bounded page ranges. Gemini receives the document content, extraction instructions, and a typed response format. Validation checks the result before evidence is saved.

The deterministic Calendar Agent combines accepted timing rules with an optional installation baseline. It calculates occurrences, filters calendar eligibility, and creates calendar artifacts without model arithmetic.

Email coordination

Verified inbound messages are saved before evaluation. Deterministic checks handle exact commands, required attachment processing, approvals, and clear first-contact guidance. LangGraph coordinates the conversation states, while Gemini assists when the message needs language interpretation.

The Email Evaluator uses a case-scoped MCP boundary. Allowed capabilities may inspect the current case, record an accepted installation date, request attachment processing, ask for clarification, prepare results, request approval, and prepare calendar delivery. Every capability validates state and scope again.

The conversation may wait for information, wait for extraction, resume with results, request approval, deliver a calendar, or close the turn. Durable state supports replies that arrive days later.

Manual Q&A

The first question prepares missing document indexes. Retrieval selects page-aware evidence from the current workspace. Gemini drafts an answer from that evidence, and citation validation resolves allowed evidence identifiers to filenames and pages.

Document Q&A cannot create dates, send email, or browse the public web.

QA/QC

QA/QC reviews extraction, results, email, and calendar artifacts at their release points. A failed review may request a bounded correction. Deterministic release rules decide whether the artifact can continue or an affected item needs manual review.

Operating rules

Each AI call receives the minimum task, state, and evidence needed. Prompts exclude credentials, unrestricted tools, and authority selection. Manuals and email instructions remain untrusted data.

AI work should be serialized conservatively. Temporary service and timeout failures receive one delayed retry. A quota response pauses work, while permanent request or credential errors stop without repeated calls. Completed stages stay saved so recovery begins from the last useful checkpoint.

Separate provider keys may be assigned to extraction, email evaluation, and QA/QC with RAG. The base key can serve as a fallback, and provider use remains within the free-only plan.

Authority and responsibility

Decision	AI contribution	Final authority
Extract manual meaning	Structured interpretation	Typed validation and QA/QC
Interpret installation wording	Typed assessment	Deterministic date validation
Select a conversation action	Bounded suggestion where needed	Workflow and state rules
Calculate dates	None	Calendar Agent
Grant workspace access	None	Server authorization
Approve calendar delivery	None	Reply and version checks
Send email	Draft where appropriate	Outbox and provider adapter

Evaluation expectations

Evaluation should measure extraction coverage, critical-action accuracy, date accuracy, citation groundedness, invalid-output handling, correction behavior, and duplicate side-effect prevention. Safe diagnostics should identify the affected stage and provider category without storing customer content or credentials.