Conflict management

Conflict review in improve() stores one FactConflict per disputed attribute of an entity. When the review cannot decide which fact holds, for example because two sources disagree on something that never changes, the conflict stays unresolved. These functions let you inspect the stored conflicts and settle one yourself. Both are async, take the dataset id rather than its name, and are available since Cognee 1.6.6.

import cognee

conflicts = await cognee.list_conflicts(dataset_id, status="unresolved")
await cognee.resolve_conflict(
    conflicts[0].id,
    dataset_id=dataset_id,
    selected_fact_id=conflicts[0].facts[0].id,
)

For a walkthrough, see Resolve Conflicting Facts.

Methods

list_conflicts()

await cognee.list_conflicts(
    dataset_id: UUID,
    *,
    status: Literal["resolved", "unresolved"] | None = None,
    user: Optional[User] = None,
) -> list[ConflictDetail]

Returns a dataset’s conflicts sorted by id, each with its competing facts (their ids, text, status, and source evidence) and any earlier decision. Returns an empty list when nothing matches. Raises PermissionDeniedError (403) if you lack read access to the dataset or it does not exist, and CogneeValidationError (422) for any other status value.

Parameter	Type	Default	Notes
`dataset_id`	`UUID`	required	The dataset whose conflicts to list. Requires read permission.
`status`	`"resolved" \| "unresolved" \| None`	`None`	Return only conflicts with this status. `None` returns all of them.
`user`	`Optional[User]`	`None`	If omitted, Cognee resolves the default user. Not used in remote mode.

Remote mode (`serve()`)

After cognee.serve(), the call runs on the connected instance through GET /api/v1/conflicts. The API key identifies the caller, so user is ignored, and an HTTP error is raised as RuntimeError carrying the status code.

resolve_conflict()

await cognee.resolve_conflict(
    conflict_id: UUID,
    *,
    dataset_id: UUID,
    selected_fact_id: UUID,
    reason: Optional[str] = None,
    user: Optional[User] = None,
) -> ConflictDetail

Accepts one of a conflict’s facts and returns the updated conflict. The conflict becomes resolved with resolution_source="user", the selected fact is marked current, and the others are marked superseded. Rejected facts are not deleted: they stay in the graph as evidence, while graph-completion and hybrid search leave them out of their context and state the accepted fact instead. A later automatic review keeps your decision for as long as the selected fact exists. Repeating the same choice changes nothing. If a review has since added a fact to the conflict, the repeated choice rejects that fact as well. Choosing a different fact replaces the earlier decision. Raises PermissionDeniedError (403) if you lack write access to the dataset or it does not exist, EntityNotFoundError (404) if the dataset holds no conflict with this id, and CogneeValidationError (422) if selected_fact_id is not one of the conflict’s facts.

Parameter	Type	Default	Notes
`conflict_id`	`UUID`	required	The conflict to settle, from `ConflictDetail.id`.
`dataset_id`	`UUID`	required	The dataset that holds the conflict. Requires write permission.
`selected_fact_id`	`UUID`	required	The fact to accept: the `id` of one of the conflict’s `facts`.
`reason`	`Optional[str]`	`None`	An optional explanation, stored as `resolution_reason`.
`user`	`Optional[User]`	`None`	If omitted, Cognee resolves the default user. Recorded as `resolved_by`. Not used in remote mode.

Remote mode (`serve()`)

After cognee.serve(), the call runs on the connected instance through POST /api/v1/conflicts/{conflict_id}/resolve. The API key identifies the caller, so user is ignored, and an HTTP error is raised as RuntimeError carrying the status code.

Return types

Both models are exported from cognee. Over HTTP their keys are camelCase (datasetId, selectedFactId, …).

ConflictDetail

Field	Type	Notes
`id`	`UUID`	The conflict id to pass to `resolve_conflict()`.
`dataset_id`	`UUID`	The dataset that holds the conflict.
`about_id`	`str`	The entity the conflict is about.
`attribute`	`str`	The disputed attribute.
`kind`	`"time_varying" \| "fixed"`	Whether the answer can change over time.
`status`	`"resolved" \| "unresolved"`	Whether a fact has been accepted.
`text`	`str`	A one-sentence summary of the conflict.
`facts`	`list[ConflictFact]`	The competing facts.
`resolution_source`	`"review" \| "user"`	Who settled it: the automatic review or a `resolve_conflict()` call.
`selected_fact_id`, `selected_fact`	`Optional[UUID]`, `Optional[str]`	The accepted fact, after a user decision.
`resolved_by`, `resolved_at`	`Optional[UUID]`, `Optional[str]`	Who made the user decision, and when (ISO 8601).
`resolution_reason`	`Optional[str]`	The `reason` passed to `resolve_conflict()`.
`write_pending`	`bool`	`True` while a decision is still being finalized.

ConflictFact

Field	Type	Notes
`id`	`UUID`	The fact id to pass as `selected_fact_id`.
`text`	`str`	The fact as a sentence.
`source_id`, `target_id`, `relationship`	`str`	The graph edge that states the fact.
`status`	`str`	The fact’s status within this conflict: `current`, `superseded`, or `conflicting`.
`sources`	`list[dict]`	The source evidence that states the fact.

HTTP API

The same operations are available over HTTP. Request bodies accept camelCase or snake_case keys.

Method	Path	Body or query
`GET`	`/api/v1/conflicts`	Query: `dataset_id` (required), `status` (optional). Requires read permission.
`POST`	`/api/v1/conflicts/{conflict_id}/resolve`	Body: `dataset_id`, `selected_fact_id`, optional `reason`. Requires write permission.

​Conflict management

​Methods

​list_conflicts()

​Remote mode (serve())

​resolve_conflict()

​Remote mode (serve())

​Return types

​ConflictDetail

​ConflictFact

​HTTP API

Conflict management

Methods

list_conflicts()

Remote mode (`serve()`)

resolve_conflict()

Remote mode (`serve()`)

Return types

ConflictDetail

ConflictFact

HTTP API