function doc fixes and callback router

[nishika26]

Checklist

Before submitting a pull request, please ensure that you mark these task.

• Ran fastapi run --reload app/main.py or docker compose up in the repository root and test.
• If you've fixed a bug or added code that is tested and has test cases.

Notes

• Documentation Updates: Clarified include_url parameter behavior (adds signed URL when true, omits when false) and detailed callback notification workflow for document transformation completion.

• Route Description Refactoring: Replaced static route descriptions with dynamic load_description calls in doc_transformation_job.py to keep the consistency with rest of the document endpoints; cleaned up imports.

• Callback Router Implementation: Added doctransformation_callback_router and integrated a placeholder callback endpoint (POST {$callback_url}) into the document upload flow.

[coderabbitai]

Walkthrough

This pull request updates API documentation for document and job endpoints to clarify include_url parameter behavior, refactors route descriptions to load from external markdown files, and introduces a callback router structure for document transformation job notifications.

Changes

Cohort / File(s)	Change Summary
Documentation Updates backend/app/api/docs/documents/info.md, backend/app/api/docs/documents/job_info.md, backend/app/api/docs/documents/job_list.md, backend/app/api/docs/documents/list.md, backend/app/api/docs/documents/upload.md	Updated endpoint documentation to clarify include_url parameter behavior (signed URL inclusion when true, omission when false) and callback notification workflow for document transformation completion.
Route Description Refactoring backend/app/api/routes/doc_transformation_job.py	Replaced static description strings with dynamic load_description calls for GET endpoints; updated imports to remove unused HTTPException and add load_description.
Callback Router Implementation backend/app/api/routes/documents.py	Added DocTransformationJobPublic import, introduced doctransformation_callback_router, and wired callback endpoint at POST {$callback_url} into the upload_doc route via callbacks parameter. Endpoint is currently a placeholder.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Documentation changes follow a consistent, repetitive pattern across multiple files
• Route refactoring is straightforward import and function call replacement
• Callback router is structural setup with no complex logic; verify that the placeholder endpoint will be implemented in follow-up work

Poem

🐰 URLs now conditional, so wise,
Callbacks await their joyful surprise—
Docs shine with clarity bright,
Routes refactored just right,
Transformations hop toward the skies! 🎉

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: documentation updates to API endpoints and addition of a callback router mechanism.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch enhancement/doc_module_documentation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1821b84 and e95e3a6.

📒 Files selected for processing (7)

• backend/app/api/docs/documents/info.md (1 hunks)
• backend/app/api/docs/documents/job_info.md (1 hunks)
• backend/app/api/docs/documents/job_list.md (1 hunks)
• backend/app/api/docs/documents/list.md (1 hunks)
• backend/app/api/docs/documents/upload.md (1 hunks)
• backend/app/api/routes/doc_transformation_job.py (3 hunks)
• backend/app/api/routes/documents.py (3 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Use type hints in Python code (Python 3.11+ project)

Files:

• backend/app/api/routes/doc_transformation_job.py
• backend/app/api/routes/documents.py

backend/app/api/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Expose FastAPI REST endpoints under backend/app/api/ organized by domain

Files:

• backend/app/api/routes/doc_transformation_job.py
• backend/app/api/routes/documents.py

🧠 Learnings (1)

📚 Learning: 2025-10-08T12:05:01.317Z

Learnt from: CR
Repo: ProjectTech4DevAI/ai-platform PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-10-08T12:05:01.317Z
Learning: Applies to backend/app/core/doctransform/**/*.py : Place document transformation utilities under backend/app/core/doctransform/

Applied to files:

• backend/app/api/routes/documents.py

🧬 Code graph analysis (2)

backend/app/api/routes/doc_transformation_job.py (2)

backend/app/models/document.py (2)

• DocTransformationJobPublic (82-87)
• DocTransformationJobsPublic (90-92)

backend/app/utils.py (2)

• APIResponse (30-54)
• load_description (288-293)

backend/app/api/routes/documents.py (2)

backend/app/models/document.py (1)

• DocTransformationJobPublic (82-87)

backend/app/utils.py (1)

• APIResponse (30-54)

🔇 Additional comments (6)

backend/app/api/docs/documents/info.md (1)

1-1: Include_url description matches doc_info implementation

The text accurately reflects that the signed URL is only included when include_url is true and omitted otherwise, consistent with the doc_info route behavior.

backend/app/api/docs/documents/job_list.md (1)

1-1: Clear description for multi-job status endpoint

The explanation of include_url and signed URLs for transformed documents is consistent with the get_multiple_transformation_jobs endpoint’s behavior.

backend/app/api/docs/documents/upload.md (1)

5-5: Upload docs now correctly document callback behavior

The new bullet clearly explains that providing a callback_url results in a notification when the transformation job completes, matching the upload_doc endpoint and callback setup.

backend/app/api/docs/documents/job_info.md (1)

1-1: Single-job include_url behavior documented consistently

This description aligns with the get_transformation_job endpoint: when include_url is true and the job is successful, a signed URL is included; otherwise, it’s omitted.

backend/app/api/docs/documents/list.md (1)

1-1: List endpoint docs now accurately describe include_url

The description of how include_url affects inclusion of signed URLs in the documents list matches the behavior of the list_docs endpoint.

backend/app/api/routes/doc_transformation_job.py (1)

4-4: Dynamic route descriptions wired correctly to new job docs

Using load_description("documents/job_info.md") and load_description("documents/job_list.md") for the two GET endpoints is consistent with the existing pattern in other routers and correctly ties these routes to the new markdown docs. The imports are minimal and appropriate, and there’s no functional change to the handlers themselves.

Also applies to: 12-12, 23-23, 55-55

[avirajsingh7]

Suggestion:
Instead of placing the information about include_url in the top-level documentation, it would be clearer to include it within the description of that specific field.
The top-level section should focus on explaining the overall API behavior, note any exceptional or abnormal behaviors, and include general guidance or notes where appropriate.

[avirajsingh7]

Approved. please go through above comment

[Prajna1999]

LGTM!