Deterministic Code–Documentation Synchronization for AI-Assisted Python Development
PyDocSync deterministically detects when Python implementation changes may require corresponding documentation updates or an explicit documentation review.
PyDocSync is designed for AI-assisted / agentic coding workflows. It does not attempt to prove that natural-language documentation is semantically correct.
An AI coding agent can modify working Python code, pass tests, and still leave documentation describing the previous implementation.
For example:
def parse_config(path, timeout=30):
"""Parse configuration using the configured timeout."""An AI agent changes the implementation to:
def parse_config(path, timeout=60):
"""Parse configuration using the configured timeout."""The code may be valid. Tests may pass. Type checking may pass.
But the documentation may now be stale.
PyDocSync adds a deterministic check to catch this maintenance gap:
KNOWN INITIAL STATE
│
▼
pydocsync init
│
▼
BASELINE
│
│
│ AI agent / developer modifies code
▼
pydocsync check
│
▼
Implementation representation changed
while related documentation did not
│
▼
PYDOCSYNC001
│
▼
Documentation must be updated
OR the change must be explicitly reviewed
│
▼
PASS
The goal is not simply to detect that code changed.
The goal is to deterministically identify changes that may create a documentation-review obligation.
PyDocSync complements established Python quality tools:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Layer A — Missing Information │
│ │
│ Missing docstrings, missing type annotations, missing Args/Returns, etc. │
│ │
│ Typical tools: Ruff / pydocstyle / pydoclint │
├─────────────────────────────────────────────────────────────────────────────┤
│ Layer B — Contract / Signature Drift │
│ │
│ Function signatures, parameter names, types, Returns, Raises, etc. │
│ no longer agree with documentation. │
│ │
│ Typical tools: Mypy / Pyright / pydoclint │
├─────────────────────────────────────────────────────────────────────────────┤
│ Layer C — Implementation ↔ Documentation Drift │
│ │
│ Implementation changes while related documentation remains unchanged, │
│ even when the API/type signature may still appear valid. │
│ │
│ PyDocSync's focus ✓ │
└─────────────────────────────────────────────────────────────────────────────┘
PyDocSync does not replace Ruff, Mypy, Pyright, pydoclint, or pytest.
It adds a deterministic synchronization signal for Layer C.
PyDocSync analyzes Python source using the AST and creates separate deterministic SHA-256 fingerprints for different representations of the same function/class.
PYTHON SOURCE
│
▼
┌─────────────────┐
│ AST Analysis │
└────────┬────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
CODE / API TYPE / DOC RAISE / EXAMPLE
│ │ │
└───────────────────┼───────────────────┘
▼
SHA-256 fingerprints
│
▼
Versioned baseline state
│
AI modifies Python code
│
▼
pydocsync check
│
┌────────────┴────────────┐
▼ ▼
PASS PYDOCSYNC001
│
Documentation review
│
┌─────────────────┴─────────────────┐
▼ ▼
Update documentation Existing documentation
│ is still accurate
│ │
│ pydocsync accept
│ │
└─────────────────┬─────────────────┘
▼
pydocsync check
│
▼
PASS
The current implementation maintains independent fingerprints for:
CODE
API
TYPE
DOC
RAISE_TYPE
RAISE_DETAIL
EXAMPLE
For example, if an AI agent changes a default value and adds a new exception:
BEFORE AFTER
CODE AAAAA CODE XXXXX ← changed
API BBBBB API YYYYY ← changed
TYPE CCCCC TYPE CCCCC ← unchanged
DOC DDDDD DOC DDDDD ← unchanged
RAISE_TYPE EEEEE RAISE_TYPE ZZZZZ ← changed
PyDocSync can therefore provide evidence about what changed and what related representation did not change, rather than relying on one opaque whole-function hash.
A fingerprint can deterministically establish that a representation changed.
It cannot prove that a natural-language statement is true.
For example, a hash cannot prove whether:
"Retries three times before raising an error."
is semantically correct.
Therefore PyDocSync treats a mismatch as a documentation-review obligation rather than automatically declaring the documentation incorrect.
When deterministic static analysis cannot safely establish the impact of a change, PyDocSync routes the case to:
UNKNOWN
review_required = True
This is intentional: PyDocSync prefers an explicit review over silently allowing potentially stale documentation.
PyDocSync 0.2.0 is an experimental release.
Install directly from GitHub:
python -m pip install git+https://github.com/mpcoder1111/PyDocSync.gitFor the v0.2.0 release tag:
python -m pip install git+https://github.com/mpcoder1111/PyDocSync.git@v0.2.0A release wheel is also available:
python -m pip install pydocsync-0.2.0-py3-none-any.whl- Python 3.10 or newer
- Zero external runtime dependencies (pure standard library)
- Explicitly exercised on Python 3.10, 3.11, 3.12, and 3.13
Run the commands from your Python project root.
pydocsync initThis creates local baseline state under .project/pydocsync/.
The baseline represents the known code/documentation state before future modifications are checked.
Important
Do not run pydocsync init after every AI modification. The purpose of the baseline is to preserve the state against which subsequent modifications are detected.
pydocsync checkIf the monitored representations are synchronized, it exits with 0 (PASS).
Suppose an AI agent changes:
def parse_config(path, timeout=30):
"""Parse configuration using the configured timeout."""to:
def parse_config(path, timeout=60):
"""Parse configuration using the configured timeout."""The AI agent has modified the code, but has not modified the documentation.
pydocsync checkPyDocSync emits a structured diagnostic:
======================================================================
PYDOCSYNC001: 1 symbol(s) require documentation review.
======================================================================
Symbol: parse_config
File: src/parser.py:3
Impact: HIGH_IMPACT
Rule ID: RULE_DEFAULT_VALUE_CHANGE
Changed: api, code
Evidence: defaults changed: ['30'] -> ['60']
Reason: Default parameter value altered in function signature.
Action: Update docstring for 'parse_config', or if documentation
remains 100% accurate, acknowledge via:
pydocsync accept --symbol parse_config --reason "<audit reason>"
----------------------------------------------------------------------
The command returns exit code 1.
If the implementation change affects documented behavior, update the docstring/documentation and run pydocsync check again to return to PASS.
Sometimes an implementation change is intentional but the existing documentation remains completely accurate (e.g. an internal refactoring or performance optimization).
After reviewing the documentation:
pydocsync accept --symbol parse_config --reason "Increased default timeout to 60s for high-latency connections; public doc remains accurate."Then pydocsync check returns to the clean PASS state (exit code 0).
Note
Trust and Authorization Model:
pydocsync accept does not prove documentation correctness. It serves as an audit record that a human developer or AI agent has reviewed the change and determined the existing doc remains accurate. Non-empty, descriptive audit reasons are strictly required.
PyDocSync does not need to be part of the AI model itself. It serves as a deterministic verification step in the AI agent's coding workflow:
AI CODING AGENT
│
│ modifies code
▼
┌────────────────────────┐
│ Tests / Lint / Types │
└────────────┬───────────┘
│
▼
┌────────────────────────┐
│ pydocsync check │
└────────────┬───────────┘
│
┌─────────┴─────────┐
▼ ▼
PASS PYDOCSYNC001
│
AI reviews signal
│
┌───────────────┴──────────────┐
▼ ▼
Update documentation Documentation still
│ accurate
│ │
│ pydocsync accept
│ │
└──────────────┬───────────────┘
▼
pydocsync check
│
▼
PASS
PyDocSync provides a minimal, typed Python API for tool builders and IDE extensions:
from pydocsync import check, init, accept, SyncResult, SyncFailure
# Scan working tree
result = check(root_dir=".")
if not result.is_synchronized:
print(f"Detected {result.failure_count} review obligations:")
for failure in result.failures:
print(f" - {failure.symbol.qualname}: {failure.rule_result.reason}")
# Programmatically acknowledge a reviewed symbol
accept(
symbol_qualname="mypkg.func",
reason="Refactored internal algorithm; verified documentation remains accurate.",
root_dir=".",
)The stable public interface for 0.2.0 consists strictly of:
check(root_dir=".") -> SyncResultinit(root_dir=".") -> intaccept(symbol_qualname, reason, root_dir=".") -> boolSyncResultSyncFailure__version__ = "0.2.0"
Internal implementation modules (ast_extract, fingerprint, classifier, baseline, report) are private and subject to change.
By default, PyDocSync monitors:
- Public Callables: Top-level functions and class methods not prefixed with
_. - Public Classes: Top-level classes not prefixed with
_.
Common non-source/build directories are excluded by default:
tests/
.venv/
__pycache__/
dist/
build/
PyDocSync stores versioned synchronization state under .project/pydocsync/:
{
"schema_version": 1,
"pydocsync_version": "0.2.0",
"fingerprint_algorithm": "sha256",
"symbols": { ... }
}The baseline is not a replacement for Git. Git provides source history and commits; PyDocSync provides normalized representation fingerprints, change classification, and audit records.
PyDocSync was evaluated against three unrelated open-source Python projects:
- Dulwich — Git engine / protocol and binary parsing code.
- Janome — Morphological NLP / tokenizer and dictionary trie code.
- python-sdb — Binary serialization and bitwise structure parsing code.
Note
These projects were used only as external evaluation corpora. They are not dependencies, are not bundled in PyDocSync, and received zero project-specific classifier rules.
The following are observed benchmark metrics, not claims of universal accuracy:
- 16 adversarial attack cases under dual execution.
- Addressed evaluation-order and dictionary-key-order blind spots; cataloged heap aliasing as an AST boundary.
- Evaluated against production code with dual blind human reviewer consensus (Reviewer A & B).
- Observed review-trigger recall: 100.0% (11/11).
- Observed review-trigger precision: 78.6%.
- Unnecessary documentation churn: 0.0%.
- Full-package scan time: 49.97 ms.
- Evaluated across Dulwich, Janome, and python-sdb with frozen Classifier v0.2.
- Two independent blind reviewers with 100% agreement.
- Observed review-trigger recall: 100.0% (13/13).
- Observed review-trigger precision: 100.0% (13/13) for applicable benchmark cases.
- Unnecessary documentation churn: 0.0%.
- UNKNOWN / escalation rate: 15.0% (3/20).
0 Clean / synchronized
1 Synchronization review required or operation failed
2 Invalid command usage / missing required arguments
PyDocSync is designed ground-up for AI-assisted development (Claude Code, Google Antigravity, Cursor, GitHub Copilot, Codex).
To equip your AI coding agent with native PyDocSync workflows in your own project, copy the bundled consumer skill:
- Source:
.agents/skills/pydocsync/SKILL.md - Target:
<your-repo>/.agents/skills/pydocsync/SKILL.mdor.claude/skills/pydocsync.md
When installed, the AI agent will automatically:
- Run
pydocsync checkafter editing Python functions or classes. - Read the structured
PYDOCSYNC001diagnostic output. - Update docstrings / contracts when behavior changes, or run
pydocsync acceptwith a clear audit reason if the documentation remains accurate.
PyDocSync is open-source software licensed under the Apache-2.0 License.