microsoft / microsoft/typeagent-py
Draft: rename modules for clearer naming (interfaces_* split, _index family, import/ingest)
@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 and the discussion started there: shreejaykurhade picked up "[P3, medium] Change inconsistent module names" and audited import-style inconsistencies (which became #298 / #299-#306). @gvanrossum's request in that thread was specific:
I think we must make a plan for what renames we want, rather than letting Claude pick them... @shreejaykurhade Would you like to start with a draft list of modules to rename and propose new names? I can then review the list and we can quickly come to an agreement that way.
That draft never landed. This issue is a first attempt at it, scoped to two concrete, defensible cases rather than an exhaustive rename of everything — explicitly a draft for discussion, not a decision. Per gvanrossum's stated preference, the actual choice of names should be made by the team, not by an LLM; this is meant to give that discussion a concrete starting point, backed by an actual read of each module's contents.
1. The interfaces_*.py split: names don't match contents
knowpro/interfaces.py re-exports five submodules. I read what's actually defined in each. Two of them contain zero Protocol/interface definitions — they're pure data-type modules mislabeled as "interfaces":
| Current name | What's actually inside | Contains any Protocol? |
|---|---|---|
interfaces_core.py |
IMessage, IKnowledgeSource (protocols) + Term, TextLocation, TextRange, SemanticRef, DateRange, ordinal type aliases (plain data types) |
Yes, mixed |
interfaces_indexes.py |
IPropertyToSemanticRefIndex, ITimestampToTextRangeIndex, ITermToRelatedTermsIndex, IConversationSecondaryIndexes, etc. |
Yes, mostly |
interfaces_search.py |
SearchTerm, PropertySearchTerm, SearchTermGroup, WhenFilter, SemanticRefSearchResult |
No — none |
interfaces_serialization.py |
ThreadData, TermData, ConversationData, and ~10 other TypedDicts |
No — none |
interfaces_storage.py |
IStorageProvider, IConversation, ICollection, IMessageCollection, plus ConversationMetadata, ChunkFailure |
Yes, mostly |
interfaces_search.py and interfaces_serialization.py are pure data/schema modules with no interfaces in them at all — the "interfaces_" prefix actively misleads about their content. interfaces_serialization.py is especially confusing sitting next to serialization.py (the actual serialize/deserialize logic module) — same near-identical name, very different purpose (one is wire-format TypedDict shapes, the other is the code that uses them).
Draft proposal:
| Current | Proposed | Rationale |
|---|---|---|
interfaces_core.py |
core_types.py (or keep as-is) |
Mixed content; "core" is accurate, "interfaces" only half is |
interfaces_indexes.py |
index_protocols.py |
Predominantly actual Protocols — name should say so |
interfaces_search.py |
search_terms.py |
Zero protocols; it's the search-term/query data vocabulary |
interfaces_serialization.py |
serialization_data.py |
Zero protocols; disambiguates from serialization.py (the logic module) |
interfaces_storage.py |
storage_protocols.py |
Predominantly actual Protocols |
interfaces.py (aggregator) |
keep as-is | Still the right name for the public re-export surface |
2. Module naming consistency: the _index family
The original P3 TODO ("Change inconsistent module names") is most visible here. messageindex.py and timestampindex.py spell their subject out in full; five siblings abbreviate it, each differently:
| Module | Class it defines | Consistent with messageindex/timestampindex? |
|---|---|---|
secindex.py |
ConversationSecondaryIndexes |
No — "sec" is ambiguous (secondary? security? seconds?) |
propindex.py |
PropertyIndex |
No |
reltermsindex.py |
RelatedTermsIndex |
No |
semrefindex.py |
TermToSemanticRefIndex |
No |
textlocindex.py |
TextToTextLocationIndex |
No |
messageindex.py |
MessageTextIndex |
(reference point) |
timestampindex.py |
TimestampToTextRangeIndex |
(reference point) |
Draft proposal (matching each module's own class name, in the same fused-no-underscore style as the two reference modules):
secindex.py→secondaryindex.pypropindex.py→propertyindex.pyreltermsindex.py→relatedtermsindex.pysemrefindex.py→semanticrefindex.pytextlocindex.py→textlocationindex.py
Open question for the team: fused (relatedtermsindex.py, matching existing messageindex.py/timestampindex.py) vs. underscored (related_terms_index.py, matching most other multi-word modules like email_message.py, universal_message.py). Both conventions currently coexist in the codebase; this rename is a chance to pick one for the _index family specifically.
3. Smaller, easy case: import vs. ingest
Three modules do the same job (parse a source format, produce ConversationMessages) but disagree on the verb:
emails/email_import.py— functionimport_emails_from_dirpodcasts/podcast_ingest.py— functioningest_podcasttranscripts/transcript_ingest.py— functioningest_vtt_transcript
Draft proposal: standardize on ingest (2-of-3 majority) — rename email_import.py → email_ingest.py, import_emails_from_dir → ingest_emails_from_dir.
Non-goals
This is a starting draft, not a complete audit of every module name in the tree — it covers the two clearest, most defensible cases. No renames have been implemented; this issue exists purely to give the team something concrete to react to, 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.