---
url: /handbook/architecture/how-dutygraph-uses-ai.md
description: >-
  Every place DutyGraph calls an AI model, every place code decides instead,
  which key each call uses, and the rules all of them follow.
---

# How DutyGraph uses AI

DutyGraph uses AI to draft, read and suggest. It never uses AI to decide. Every AI output is a proposal that waits for a person, and everything that grants, refuses or records authority is code.

## Where AI is called

The **Key** column says which connection pays for and receives the call:

* **Company**: the company's approved Claude connection first, then its approved OpenAI connection, else no call.
* **Company (OpenAI)**: the company's approved OpenAI connection only.
* **Firm (OpenAI)**: the OpenAI key in **Settings › Research & AI keys**. A person with shared access to one company uses that company's approved OpenAI connection instead.
* **Platform**: a key DutyGraph holds on the server.

| Where | What the AI does | Key | What a person does |
| --- | --- | --- | --- |
| [Company research](../discovery/company-research.md) | Reads public pages from the research provider and extracts field values. Each quote is checked against the page. | Company (OpenAI) | Findings stay **Inferred** until a client person confirms them |
| Research evidence checks (Jev) | Answers typed questions about evidence and outreach text, as probabilities. Code sets every threshold and can only make a result stricter. | OpenAI, or TypeSafe on a platform key if the firm opts in | Optional. Without it, rules decide. |
| **Here's what we heard** on the [sponsor packet](../discovery/sponsor-packet.md) and [team asks](../discovery/team-asks.md) | Tidies each answer for meaning and adds at most one suggested improvement | Company | The person confirms or corrects it before sending |
| Companion phone app | Transcribes a voice answer and drafts the understanding of it | Platform (xAI) | The person checks it before sending |
| Voice transcription in the browser | Turns a recording into editable text | Firm (OpenAI) | The person edits the text before sending |
| Voice interviews | Runs a live spoken interview and drafts a summary | Company (OpenAI) | The advisor reviews the transcript. The summary is a labelled draft. |
| [Executive kickoff](../discovery/executive-kickoff.md) | **Prepare meeting guide** drafts an 8-topic guide. **Prepare team review** reads the pasted notes or transcript and drafts people, roles, managers and duties. | Firm (OpenAI) | The advisor reviews every proposed person and duty |
| Kickoff corrections | **Generate AI correction proposals** turns the sponsor's comments into proposed changes | Firm (OpenAI) | The advisor accepts or rejects each one |
| [Team asks](../discovery/team-asks.md) | **Create question sets** writes a tailored set of questions for each person from their recorded duties | Firm (OpenAI) | The advisor edits and sends them |
| [Task Cards](../discovery/task-cards.md) | **Draft task cards** turns accepted answers into Task Cards | Firm (OpenAI) | Each card is **Proposed** and **Inferred** until accepted |
| Repo fill loop | Reads answers and meeting notes into field readings and proposed duties, Task Cards, handoffs and workflows | Company | Each reading waits in **Repo › To review** |
| Continuing checks | Reads a reply to a follow-up question and proposes work updates | Firm (OpenAI) | Proposals never overwrite reviewed or confirmed work |
| [Work Map](../discovery/work-map.md) | **Connect existing work with AI** proposes stage links for older work | Firm (OpenAI) | Links stay dashed until a person accepts them |
| Team analysis | **Analyze team work** suggests cross-team hypotheses with exact citations | Firm (OpenAI) | The advisor decides on each one |
| [DutyGraph Agent](../advisors/repo-copilot.md) | Answers, reviews, proposes edits and drafts asks. On the Strategy pages it runs in Ask mode. | Company | The advisor accepts or rejects each edit. Asks queue unsent. |
| [Outcomes and Strategy](../opportunities/outcomes-and-strategy.md) | **Find possible constraints** and the RACI, Theory of Constraints and SWOT / TOWS framework runs | Company | The advisor accepts or rejects each result. Code sets the evidence words. |
| [Route](../opportunities/route.md) **Refresh** | Starts a research run for the AI patterns that fit the company | As company research | Each option waits in review |
| **Agents › Business review** | An optional AI draft of a manifest for an older request | Firm (OpenAI) | Requested scopes remain proposals |

## Where code decides, with no AI

| Area | What code does |
| --- | --- |
| Hours a week | Reads the tapped range, such as "5–10 hours" |
| AI-fit pass | Proposes an AI mode, owner and performer for each Task Card, with a plain reason |
| Proposed agents | Groups Task Cards into agents for one named person, inside that person's access |
| Route | Every verdict, fit, value and option order |
| Constraint signals | Rules that point to Repo files |
| Company Repo, Work Map and reports | Compiled from records. The same records give the same output. |
| Kickoff agenda and **Ask the person responsible** | Built from fixed templates and open fields |
| Agent builder | Markers, the AI mode cap, tool policies and the five export formats |
| Agent plan page | Built from the saved manifest |
| [The key join](../governance/the-key-join.md) | The governance evaluator gives each requested scope one state with a rule citation |
| [Approval chain](../governance/approval-chain.md) | Records each person's decision. No call from an AI chat can decide. |
| [Ledger](../governance/ledger.md) | Hash-links each decision |
| [Gateway](../governance/agent-gateway.md) | Allows or blocks each agent call routed through it |

## The rules

1. **AI only proposes.** AI can save a draft or a proposal. It never becomes an accepted fact, a confirmed record or a permission until a person accepts it.
2. **An approved connection, never a borrowed one.** A company's AI calls go through a key the firm saved or the company approved. On the hosted service, the only AI keys DutyGraph holds itself are the platform keys marked above. Saved keys are encrypted and never sent to the browser.
3. **Sample companies.** Features on the **Company** key, company research and Route **Refresh** never call a provider for a sample company. They show **Sample output · no AI call** or simulated research.
4. **Accepted values in, raw words out.** DutyGraph Agent and Strategy read compiled Repo files: accepted values only, with email addresses masked. A person's raw words never reach a DutyGraph Agent edit or a drafted ask. Holdings never reach any AI.
5. **No stored prompts.** Usage rows keep counts, sizes, the model and the cost, not the message. Text calls to OpenAI and xAI set `store: false`.
6. **AI input retention.** A job that runs at most once an hour removes quotes from stored Strategy runs when the quoted file changes or leaves the Repo. It also removes evidence text from older framework runs and team analyses. See [Security and data handling](../trust/security-and-data.md#what-reaches-an-ai-provider).
7. **Started on purpose.** Most AI actions start when a person selects them, after a consent note where the page shows one. The fill loop and continuing checks run as background jobs when an answer arrives. A replay of the same command never makes a second call.

## Four meanings that stay apart

AI proposals, participant confirmation, advisor approval and external authority mean different things:

| Kind | Who | What it means |
| --- | --- | --- |
| **AI proposal** | A model | A draft. It changes nothing. |
| **Participant confirmation** | The person who answered | "This is what I meant." It does not make it company practice. |
| **Advisor approval** | The advisor | The advisor accepted it into the company's record, or approved a report for an audience. |
| **External authority** | People in the company who already approve access | A decision in the approval chain about a governed agent |

One never stands in for another. A confirmed answer is not an approval. An AI reading stays a proposal until the right person validates it. An approval in DutyGraph does not change a business system: the company's IAM provisions access. See [Approval, provisioning and revalidation](../governance/approval-provisioning-and-revalidation.md). See [Evidence and provenance](../trust/evidence-and-provenance.md).

## Limits

* Several older features marked **Firm (OpenAI)** do not check for a sample company on the server. On a sample company they can call OpenAI if the firm saved an OpenAI key.
* No live AI provider is called in the automated tests. They use fake providers.

::: info
**Status.** **Built**: every AI call in the first table, each through the key shown, and every code-only step in the second table. **Simulated**: research for sample companies uses labelled fixtures. **Planned**: an optional, labelled AI summary paragraph on reports.
:::
