Add key suggestions endpoint for barcodes and category tags

[Copilot]

Overview

This PR implements a new /suggestions/{identifier} endpoint that provides intelligent key suggestions for products and category tags in the Folksonomy API. This addresses issue #[issue_number] by helping users discover which key-value pairs they can add to products based on usage patterns across the database.

What's New

/suggestions/{identifier} Endpoint

The new endpoint analyzes the folksonomy database to return the top 10 most commonly used keys, providing inspiration for users when tagging products or categories.

Parameters:

• identifier (path, required): Product barcode (e.g., '3701027900001') or category tag (e.g., 'en:lasagne')
• owner (query, optional): Empty string for public tags, or user_id for private suggestions (requires authentication)

Response: JSON array of KeySuggestion objects with:

• k: The suggested key name
• count: Number of times this key is used across all products

Key Features

• ✅ Smart filtering: Excludes keys already present on the specified identifier
• ✅ Popularity-based: Results sorted by usage count (most popular first)
• ✅ Privacy support: Works with both public and private tags with proper authentication
• ✅ Flexible identifiers: Accepts both product barcodes and category tags
• ✅ Limited results: Returns top 10 suggestions to avoid overwhelming users

Example Usage

# Get suggestions for a product barcode
curl "https://api.folksonomy.openfoodfacts.org/suggestions/3701027900001"

# Response:
[
  {"k": "origin", "count": 250},
  {"k": "packaging", "count": 180},
  {"k": "label", "count": 120}
]

# Get suggestions for a category tag
curl "https://api.folksonomy.openfoodfacts.org/suggestions/en:lasagne"

# Get private suggestions (requires authentication)
curl "https://api.folksonomy.openfoodfacts.org/suggestions/3701027900001?owner=myusername" \
     -H "Authorization: Bearer YOUR_TOKEN"

Implementation Details

• New Model: KeySuggestion Pydantic model for structured responses
• SQL Query: Efficient aggregation query that groups by key and counts usage
• OpenAPI Documentation: Fully documented with examples in the API schema
• Tag: Added to "Keys & Values" section for logical organization

Testing

Added 5 comprehensive tests covering:

• Product barcodes with existing keys (ensures exclusion works)
• New products without existing keys (returns popular keys)
• Category tag identifiers
• Empty database scenarios
• Private suggestions with authentication

All 41 tests passing (36 existing + 5 new)

Additional Improvements

• Fixed db-migration.py to properly handle PostgreSQL host configuration with explicit port
• Added python-dotenv dependency for better environment configuration support

Security

✅ No vulnerabilities detected by CodeQL scanner

Related Issues

Closes #[issue_number]

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• install.python-poetry.org

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Provide 10 suggestions of keys for a given Barcode or category tag (eg. en:lasagne)</issue_title>
<issue_description>### Story

• Provide 10 suggestions of keys for a given category tag (eg. en:lasagne) so that users have inspirations of key-value Paris to add
• use as needed the folksonomy engine and the open prices and or open food facts api (which have the list of barcodes and an associates category)

</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #318

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.93%. Comparing base (b9cda65) to head (330e5e5).
⚠️ Report is 130 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #319       +/-   ##
===========================================
- Coverage   95.06%   78.93%   -16.13%     
===========================================
  Files           5        4        -1     
  Lines         324      565      +241     
===========================================
+ Hits          308      446      +138     
- Misses         16      119      +103     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.