microsoft / microsoft/typeagent-py

Draft: rename modules for clearer naming (interfaces_* split, _index family, import/ingest)

Open
#307 2 comments 0 reactions 1 assignee View on GitHub

@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.pysecondaryindex.py
  • propindex.pypropertyindex.py
  • reltermsindex.pyrelatedtermsindex.py
  • semrefindex.pysemanticrefindex.py
  • textlocindex.pytextlocationindex.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 — function import_emails_from_dir
  • podcasts/podcast_ingest.py — function ingest_podcast
  • transcripts/transcript_ingest.py — function ingest_vtt_transcript

Draft proposal: standardize on ingest (2-of-3 majority) — rename email_import.pyemail_ingest.py, import_emails_from_diringest_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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.