Design backend for API documentation infrastructure

[philwinder]

Description

This PR introduces a design document outlining the backend infrastructure for a new MCP tool that provides contextual API documentation. It details how to enhance the slicer to extract public API methods with hierarchical context (package, class), identify related methods, and dynamically assemble "live views" of the API. The design proposes extending the existing SnippetV2 model and integrating a new api_documentation() MCP tool.

Related Issue

N/A

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update (This PR adds a new design document)
• Other (please describe)

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

Additional Notes

This PR introduces a design document for the api_documentation MCP tool. It does not include any code implementation. The document details the proposed architecture, including enhancements to the slicer for API extraction, extension of the SnippetV2 model, and the approach for dynamic API view generation.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/kodit
_version.py	18	4	75%	15–19
app.py	71	71	0%	3–168
cli.py	51	17	67%	57–84, 99–101, 107
cli_utils.py	25	25	0%	3–67
config.py	109	28	69%	24, 163, 166–169, 182, 191–193, 197–199, 206–209, 229–233, 239–247
database.py	42	26	35%	25–62, 71, 76–84, 88–89, 93
log.py	121	24	74%	56, 70, 133–137, 147–>151, 196–>189, 198–199, 204–214, 233, 235–244, 250–>249, 254–257, 267
mcp.py	51	20	58%	51–55, 157–198, 203, 222
middleware.py	35	35	0%	3–75
src/kodit/application/factories
reporting_factory.py	21	11	48%	20–24, 31–36
server_factory.py	147	93	28%	82–109, 113–115, 119–123, 127–131, 135–137, 141–150, 154–156, 160–164, 168–172, 176–198, 202, 206–210, 217–219, 225–227, 231–235, 239–243, 247–251, 255–260, 264–268, 272–274, 278–287, 291–295, 299–303, 307–311
src/kodit/application/services
code_search_application_service.py	51	32	31%	30, 44, 60–66, 70–138
commit_indexing_application_service.py	236	161	27%	101–112, 118, 127–159, 163–170, 174–219, 234, 243–>253, 253–>268, 287–369, 375–382, 396–423, 427–478, 484–527, 533–541
indexing_worker_service.py	62	62	0%	3–115
queue_service.py	28	4	81%	57–66
reporting.py	40	5	83%	13, 72, 84, 88, 102
sync_scheduler.py	39	27	27%	25–29, 33–35, 39–45, 49–64, 68–78
src/kodit/domain
errors.py	1	1	0%	4
protocols.py	131	10	92%	36, 40, 44, 48, 52, 56, 64, 72, 78, 82
value_objects.py	282	11	96%	72, 101–126, 131, 136–139, 330, 646, 650
src/kodit/domain/entities
__init__.py	132	16	86%	22, 39, 80, 93, 103–107, 238–240, 244–245, 261, 267–268
git.py	121	12	88%	27, 32–34, 52, 67, 72–76, 125–>142, 135, 163, 168
src/kodit/domain/factories
git_repo_factory.py	15	1	93%	66
src/kodit/domain/services
bm25_service.py	36	2	92%	59, 116
embedding_service.py	39	1	96%	92
git_repository_service.py	184	76	53%	75–108, 128–>126, 153–157, 165–175, 191, 212–214, 220–230, 239–259, 268–285, 291–297, 312–329, 333–337, 424
git_service.py	150	150	0%	3–300
task_status_query_service.py	8	8	0%	3–17
src/kodit/infrastructure/api/client
__init__.py	4	4	0%	3–7
base.py	39	39	0%	3–100
exceptions.py	4	4	0%	4–19
generated_endpoints.py	6	6	0%	7–23
search_client.py	13	13	0%	3–86
src/kodit/infrastructure/api/middleware
auth.py	13	13	0%	3–31
src/kodit/infrastructure/api/v1
dependencies.py	51	51	0%	3–155
src/kodit/infrastructure/api/v1/routers
commits.py	55	55	0%	3–258
queue.py	16	16	0%	3–64
repositories.py	87	87	0%	3–282
search.py	11	11	0%	3–58
src/kodit/infrastructure/api/v1/schemas
commit.py	45	45	0%	3–96
context.py	6	6	0%	3–13
queue.py	16	16	0%	3–35
repository.py	55	55	0%	3–128
search.py	94	94	0%	3–222
snippet.py	27	27	0%	3–58
tag.py	13	13	0%	3–31
task_status.py	20	20	0%	3–41
src/kodit/infrastructure/bm25
local_bm25_repository.py	76	24	65%	22–23, 46–57, 76–77, 80–81, 88–89, 102–103, 107, 112, 137–>135, 150
vectorchord_bm25_repository.py	89	55	32%	118–120, 124–131, 135–139, 143–148, 152–154, 157–161, 165–202, 206–227, 234–237
src/kodit/infrastructure/cloning/git
git_python_adaptor.py	233	88	59%	19–37, 42–59, 107–117, 158–>154, 169–171, 208, 240–249, 258–287, 305–313, 325–329, 362, 376–381, 407–411, 430–435, 445–>exit, 463–465
working_copy.py	53	3	92%	48–55
src/kodit/infrastructure/embedding
embedding_factory.py	39	7	76%	64–65, 74–77, 85–86
local_vector_search_repository.py	35	20	32%	50–70, 75–88, 97
vectorchord_vector_search_repository.py	99	72	21%	100–105, 109–115, 119–120, 124–161, 167–202, 206–240, 249–260, 263–272
src/kodit/infrastructure/embedding/embedding_providers
litellm_embedding_provider.py	61	0	99%	152–>156
local_embedding_provider.py	53	2	92%	16–17, 50–>60, 64–>78
src/kodit/infrastructure/enrichment
litellm_enrichment_provider.py	63	5	92%	99–103, 118–119
src/kodit/infrastructure/git
git_utils.py	12	12	0%	3–32
src/kodit/infrastructure/ignore
ignore_pattern_provider.py	30	30	0%	3–69
src/kodit/infrastructure/indexing
fusion_service.py	19	14	16%	26–48
src/kodit/infrastructure/mappers
git_mapper.py	53	10	77%	59–75, 87, 112
snippet_mapper.py	25	9	62%	55, 65–75, 83, 99
task_mapper.py	12	1	86%	23
task_status_mapper.py	18	8	45%	16, 42, 72–85
src/kodit/infrastructure/reporting
db_progress.py	11	4	64%	17–19, 23
log_progress.py	18	9	45%	18–20, 24–40
telemetry_progress.py	9	2	78%	15, 19
src/kodit/infrastructure/slicing
slicer.py	480	401	11%	150, 169–242, 246–255, 259–277, 283–305, 309–313, 317–319, 324–339, 343, 347, 353–363, 367–370, 376–386, 392–395, 399–405, 409–421, 425–431, 435, 439–440, 444–449, 453–459, 463–471, 475–481, 485–494, 498–504, 508–513, 517–522, 526–529, 533–536, 542–547, 551–559, 569–627, 639–644, 659–686, 692–720, 728, 738–759, 765–777, 781–795, 801–817, 823–843, 847–877, 882, 888–897, 907–929
src/kodit/infrastructure/sqlalchemy
embedding_repository.py	82	11	84%	48–51, 60, 66–72, 169, 193, 201–>209
entities.py	245	23	90%	37, 63, 180–192, 457–461, 481–483
git_branch_repository.py	105	42	55%	30–79, 118–>121, 139, 166–189, 194, 209–216, 230–>exit, 239–245, 258–263
git_commit_repository.py	142	28	78%	89–>92, 120–142, 226–231, 237–270, 295–>293, 307–>exit, 335
git_repository.py	104	26	71%	55–62, 91–99, 125–139, 208, 218, 220, 226–235
git_tag_repository.py	102	41	55%	30–77, 114–>117, 135, 162–185, 190, 203–210, 224–>exit, 233–239, 252–257
snippet_v2_repository.py	151	33	77%	126, 209–210, 225–230, 244–275, 284–310, 359, 440–450
task_repository.py	59	13	74%	52–62, 66–72, 82
task_status_repository.py	50	35	27%	20, 28–30, 35–68, 74–83, 87–91
unit_of_work.py	30	9	60%	29–>exit, 41–43, 47–49, 53–55
src/kodit/migrations
env.py	30	30	0%	3–85
src/kodit/migrations/versions
04b80f802e0c_foreign_key_review.py	23	23	0%	10–98
7c3bbc2ab32b_add_embeddings_table.py	15	15	0%	10–54
7f15f878c3a1_add_new_git_entities.py	140	140	0%	10–689
9cf0e87de578_add_queue.py	15	15	0%	10–46
9e53ea8bb3b0_add_authors.py	33	33	0%	10–102
4073b33f9436_add_file_processing_flag.py	11	11	0%	10–35
4552eb3f23ce_add_summary.py	11	11	0%	10–33
85155663351e_initial.py	23	23	0%	10–97
b9cd1c3fd762_add_task_status.py	21	21	0%	10–76
c3f5137d30f5_index_all_the_things.py	21	21	0%	10–49
f9e5ef5e688f_add_git_commits_number.py	15	15	0%	10–43
src/kodit/utils
dump_config.py	182	182	0%	3–361
dump_openapi.py	24	24	0%	3–38
generate_api_paths.py	40	40	0%	4–135
path_utils.py	38	20	39%	28–57, 72, 77, 81
TOTAL	6168	3169	45%

Tests	Skipped	Failures	Errors	Time
287	1 💤	0 ❌	0 🔥	58.606s ⏱️