Code Quality & Cleanup (from TODO.md)

[bmerkle]

In this issue we track possible Code Quality & Cleanup Items from TODO.md

Code Quality & Cleanup

P1 - High Priority

• [P1, large] Make coding style more uniform (e.g. docstrings)
• [P1, large] Reduce code size

P2 - Medium Priority

• [P2, small] Avoid most inline imports
• [P2, medium] Break cycles by moving things to their own file if necessary
• [P2, medium] Unify or align or refactor VectorBase and EmbeddingIndex
• [P2, medium] Address TODO comments (too numerous)
• [P2, medium] Address raise NotImplementedError("TODO") (five found) -- implement it

P3 - Low Priority

• [P3, medium] Change inconsistent module names (Claude uses different naming style)
• [P3, medium] Rewrite podcast parsing without regexes
• [P3, medium] Switch from Protocol to ABC
• [P3, medium] Reduce duplication between ingest_vtt.py and typeagent/transcripts/
• [P3, small] Rename kplib.py to something ending in _schema.py

[bmerkle]

If you want to try your hand at some items from TODO.md, maybe these make decent starter issues:

Code Quality & Cleanup

P2 - Medium Priority

• [P2, small] Avoid most inline imports
• [P2, medium] Break cycles by moving things to their own file if necessary

I'd start with the former but back out whenever moving an inline import reveals a circular dependency -- for those we often need to do the latter, which is much more subtle and requires a deep understanding of the architecture in order to move the right things into separate files.

I'm not in a hurry with the development infra items (all P3s anyways). Feel free to document the test/build process. The release process I'd rather document myself because I think there are actually some improvements needed for that.

Originally posted by @gvanrossum in #45

[bmerkle]

For moving inline imports to the top of the file, I'd try one file at a time under typechat. There are some traps where these are needed to avoid circular imports, but many are undoubtedly due to Claude's preference for that style, which is not mine.

For the tests I think you should be able to move all imports out, since there are no circular imports between tests and everything else ought to be importable in any order.

...

I think I understand what you mean about "lost meta information", but it's not typeagent's fault -- it's that email tools (because they predate the Internet) work using conventions that are easy for humans to understand but less so for simplistic software. An LLM would have no problem figuring out who said what, but that's yet another LLM roundtrip.

...

You can use whatever tools you like, including LLMs, but for those I'd like to know about it (and ideally which one and version), and I urge you to review their output carefully before submitting the PR. (You can also make it a Draft PR so I'll know you're still working on it.)

Originally posted by @gvanrossum in #45

[bmerkle]

I will focus on

P2 - Medium Priority

• [P2, small] Avoid most inline imports
• [P2, medium] Break cycles by moving things to their own file if necessary

[gvanrossum]

Thanks for the reorg!

[bmerkle]

okay, i worked with VSCode and GPT-5-Codex on the refactoring, pushed all modifications to a branch.
all tests are running (except the mcp server where i have some communications problem)

• all inline imports are removed
  (I am embarrassed, I didn't know anything about inline imports. I come from C++ and always imported “at the top.”)

• formatted imports and from imports
  (sorted, arranged etc, via ruff tool) ruff check --select I --fix .

• circular dependecies are removed, a new types.py file was introduced

• searchlib.py improved handling of pydantic classes

• note that the patch set is quite large (99 files) but i looked through to assert that nothing broke.

• unit tests ran fine. (except mcp server)