microsoft / microsoft/typeagent-py
Standardize import style (module-qualified vs direct-symbol) across the codebase
@bmerkle is already working on this.
Since Aug 1, 2026.
- Dominant language
- Python
- Stars
- 884
- Forks
- 75
- Avg merge
- 3h 2m
- Merged PRs (30d)
- 2
Description
Context
Follow-up to #112, specifically the discussion started in this comment (import/naming inconsistency slows down both humans and LLM-assisted contributors trying to understand the codebase) and the detailed per-module audit in this comment (module-qualified vs. direct-symbol import style is mixed across knowledge_schema/kplib, secindex, convknowledge, propindex, reltermsindex, semrefindex, textlocindex).
AGENTS.md now documents the decision rule (added in this effort):
Default to Module-Qualified Imports: Prefer importing whole modules and using qualified calls to prevent namespace pollution, avoid name clashes, and provide immediate context for where functions or objects originate.
Use Direct Symbol Imports Cautiously: Restrict direct imports to specific scenarios: classes/exceptions/constants, avoiding severe repetitive clutter, or standard-library patterns.
Prohibit Wildcard Imports.
This issue tracks applying that rule consistently, based on an AST-based census of actual import sites across src/typeagent, tests/, and tools/.
Current state (as audited)
| Module | Exports | Target style | Compliance today |
|---|---|---|---|
knowledge_schema (kplib) |
7 classes only | direct-symbol | ❌ split: 20 sites alias it as kplib (10 in src, 10 in tests/tools), 32 sites already direct |
secindex |
1 class + 2 functions | module-qualified | ✅ already 100% qualified in src (6/6); tests use direct-symbol (separate, idiomatic convention) |
convknowledge |
1 class only | either (already consistent) | ✅ already 100% qualified everywhere (4/4) |
textlocindex |
2 classes only | direct-symbol | ✅ already 100% direct everywhere (5/5) |
propindex (memory variant) |
1 enum + 10 functions + 1 class | module-qualified | ❌ opposite of target: 23/25 sites are direct-symbol today |
reltermsindex (memory variant) |
4 classes + 3 functions | module-qualified | ❌ 100% direct-symbol today (14/14) |
semrefindex (memory variant) |
18 functions + 1 class | module-qualified | ❌ only 1/22 sites qualified (conversation_base.py); everything else (incl. add_messages.py, mcp/server.py, storage/memory/provider.py) is direct-symbol |
propindex/reltermsindex/semrefindex (sqlite variants) |
1 class each | direct-symbol | ✅ already 100% direct everywhere |
Plan
Phase 0: Land the AGENTS.md rule itself (docs-only).
Phase 1 — knowledge_schema/kplib cleanup (bounded, low-risk, directly matches the issue's original complaint):
- Convert the 20
from . import knowledge_schema as kplib+kplib.Xsites tofrom .knowledge_schema import X, Y, Z, insrc/typeagent(10 files) and in tests/tools (10 files, same mechanical fix). - One PR.
Phase 1b: No code changes needed — secindex, convknowledge, textlocindex are already compliant/internally consistent.
Phase 2 (deferred, separate sign-off after Phase 1 lands): reltermsindex → propindex → semrefindex, each its own PR, in that order (ascending size/centrality — semrefindex touches add_messages.py and conversation_base.py, the highest-churn files in the repo per the code-health hotspot data, so it goes last after the mechanical pattern is validated on the smaller modules).
Scope decision: test/tool files get the mechanical kplib-alias fix (Phase 1) since it's zero-risk, but Phase 2's function-import style is not forced onto test files — importing a function directly to call it in an assertion is idiomatic pytest style and is being treated as its own justified exception, independent of what src/typeagent does.
Non-goals
This issue is about import style consistency only. Actually renaming modules (the original ask in #112, e.g. secindex → something more descriptive) is separate and still awaiting a draft rename list, per gvanrossum's request in #112.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.