feat(projects): add optional description field to project model and API

[abhinav-1305]

PR Type

Enhancement

resolves: #1465

---

Description

• Add optional description field to project model

• Update database schema with migration files

• Modify API queries to handle new field

• Update documentation with usage examples

---

Changes diagram

flowchart LR
  A["TypeSpec Model"] --> B["Database Migration"]
  B --> C["API Queries"]
  C --> D["Documentation"]
  A --> E["Project Schema"]
  E --> F["Create/List Operations"]

Loading

---

Changes walkthrough 📝

	Relevant files
Enhancement	create_project.py Update create project query for description                            src/agents-api/agents_api/queries/projects/create_project.py Add description field to SQL INSERT query Include description parameter in query execution +4/-1      list_projects.py Include description in project listing                                      src/agents-api/agents_api/queries/projects/list_projects.py Add description field to SELECT query +1/-0      models.tsp Add description to TypeSpec model                                                src/typespec/projects/models.tsp Add optional description field to Project model +3/-0
Documentation	projects.mdx Document new description field                                                      documentation/concepts/projects.mdx Add description field to project structure documentation Update usage example to show description instead of metadata +2/-1
Configuration changes	000044_add_project_description.down.sql Migration rollback for description field                                  src/memory-store/migrations/000044_add_project_description.down.sql Remove description column from projects table Revert create_default_project function changes +30/-0    000044_add_project_description.up.sql Database migration for description field                                  src/memory-store/migrations/000044_add_project_description.up.sql Add description column with length constraint Update create_default_project function to include description Add column comment for documentation +39/-0

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-merge-for-open-source]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Migration Concern The migration moves description from metadata to a dedicated column but doesn't handle existing projects that may have description in their metadata. This could result in data loss during migration. ALTER TABLE projects ADD COLUMN description TEXT DEFAULT NULL CONSTRAINT ct_projects_description_length CHECK ( description IS NULL OR length(description) <= 1000 ); Null Handling The code passes data.description directly to the SQL query without checking if it exists on the data object, which could cause AttributeError if the field is not present in the request. data.description, data.metadata,

[qodo-merge-for-open-source]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	✅ Use standard constraint naming convention Suggestion Impact: The suggestion was directly implemented - the constraint name was changed from 'ct_projects_description_length' to 'chk_projects_description_length' exactly as suggested. code diff: -CONSTRAINT ct_projects_description_length CHECK ( +CONSTRAINT chk_projects_description_length CHECK ( The constraint name should follow a more standard naming convention. Use a descriptive name that clearly indicates the table, column, and constraint type. src/memory-store/migrations/000044_add_project_description.up.sql [4-9] ALTER TABLE projects ADD COLUMN description TEXT DEFAULT NULL -CONSTRAINT ct_projects_description_length CHECK ( +CONSTRAINT chk_projects_description_length CHECK ( description IS NULL OR length(description) <= 1000 ); [Suggestion processed] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly points out that using chk_ as a prefix for a check constraint is a common convention, improving code consistency and maintainability.	Low
Update

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 4d4596b in 1 minute and 2 seconds. Click for details.

• Reviewed 161 lines of code in 6 files
• Skipped 0 files when reviewing.
• Skipped posting 6 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. documentation/concepts/projects.mdx:29

• Draft comment:
  Clarify that the top-level 'description' field is now separate from metadata. The sample payload correctly moves 'description' out of metadata, but a brief note might help avoid confusion.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

2. src/agents-api/agents_api/queries/projects/create_project.py:23

• Draft comment:
  The INSERT query now includes the 'description' column with parameter $6. Confirm that 'data.description' may be None and is handled appropriately in downstream logic.
• Reason this comment was not posted:
  Confidence changes required: 33% <= threshold 50% None

3. src/agents-api/agents_api/queries/projects/list_projects.py:26

• Draft comment:
  The SELECT query now returns the 'description' field to align with the updated model. This change looks consistent.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

4. src/memory-store/migrations/000044_add_project_description.down.sql:20

• Draft comment:
  In the down migration, the default project function still injects a 'description' key into the metadata. Verify that this behavior aligns with the pre-migration implementation.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking the PR author to verify if the behavior aligns with the pre-migration implementation. This falls under asking the author to confirm their intention or to double-check things, which is against the rules.

5. src/memory-store/migrations/000044_add_project_description.up.sql:4

• Draft comment:
  The migration up script correctly adds a 'description' column with a length constraint and updates the default project function accordingly. No issues found.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

6. src/typespec/projects/models.tsp:27

• Draft comment:
  The Project model now includes an optional 'description' field, which aligns with the API changes. Looks good.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

Workflow ID: wflow_JhHo0TQi01EvvwBo

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[abhinav-1305]

please review - @HamadaSalhab