Integrate Ordinator reranking service into Forgejo issue search #104

New issue

Closed

opened 2026-04-30 13:34:06 +02:00 by kade · 1 comment

kade commented 2026-04-30 13:34:06 +02:00

Owner

Copy link

Ordinator Reranking Integration

Overview

Integrate Ordinator reranking service into Forgejo issue search to improve search relevance using multi-factor scoring (semantic similarity, personalization, authority, recency).

Ordinator Service Status

• Service: Running on Unix socket /var/run/reynard/ordinator.sock
• Endpoints:
  • GET /health - Service health check
  • POST /rerank - Rerank search results
  • GET /stats - Service statistics
• Deployment: Ansible-managed systemd service with resource limits
• Documentation: services/ordinator/DEPLOYMENT.md

Integration Points

1. Go HTTP Client for Ordinator

Create a Go client package to communicate with Ordinator via Unix socket:

• Location: modules/ordinator/client.go
• Functionality: HTTP client over Unix domain socket
• Endpoints: Health check, rerank request, stats

2. Issue Search Integration

Modify issue search flow in Forgejo:

• Current location: routers/api/v1/repo/issue.go - SearchIssues()
• Integration point: After initial search results from indexer, pass through Ordinator for reranking
• Configuration: Feature flag to enable/disable Ordinator reranking

3. Configuration

Add Ordinator configuration to Forgejo settings:

• Socket path: /var/run/reynard/ordinator.sock
• Enable/disable reranking
• Timeout settings
• Fallback behavior (if Ordinator unavailable)

Implementation Plan

1. Create Go HTTP client for Unix socket communication

   • Use net.Dial("unix", socketPath) for Unix socket
   • HTTP client wrapper for Ordinator endpoints
   • Error handling and fallback logic

2. Integrate into issue search

   • Modify SearchIssues() in routers/api/v1/repo/issue.go
   • Add reranking step after indexer results
   • Preserve original search results for fallback

3. Add configuration

   • Add Ordinator settings to modules/setting/setting.go
   • Add to configuration file schema
   • Admin UI for Ordinator settings

4. Testing

   • Unit tests for Go client
   • Integration tests with running Ordinator service
   • Performance benchmarks

Technical Details

Ordinator Rerank Request Format

{
  "query": "search query string",
  "candidates": [
    {"id": "issue-1", "title": "...", "body": "..."},
    {"id": "issue-2", "title": "...", "body": "..."}
  ],
  "user_context": {"user_id": 123},
  "strategy": "default",
  "limit": 10
}

Ordinator Rerank Response Format

{
  "success": true,
  "data": {
    "reranked": [
      {"id": "issue-1", "score": 0.95},
      {"id": "issue-2", "score": 0.87}
    ]
  },
  "error": null
}

Dependencies

• Ordinator service must be deployed and running
• Unix socket accessible to Forgejo process
• No external network dependencies (socket-only communication)

References

• Ordinator deployment: services/ordinator/DEPLOYMENT.md
• Ordinator API: services/ordinator/src/server.rs
• Forgejo issue search: routers/api/v1/repo/issue.go
• Forgejo issue search models: models/issues/issue_search.go

Testing and Enhancements (April 30, 2026)

✅ COMPLETED: Testing suite and comparison logging added

Comparison Logging

• Added debug logging for original issue order before reranking
• Added debug logging for reranked issue order after reranking
• Added info log when issue order changes due to reranking
• Enables easy comparison of original vs reranked results in logs

User/Agent Influence Parameters

Added query parameters to influence reranking behavior:

• ordinator_strategy: Custom reranking strategy (default: "default")
• ordinator_title_weight: Weight for title matching (float)
• ordinator_body_weight: Weight for body/content matching (float)

Example usage:

GET /api/v1/repos/{owner}/{repo}/issues/search?q=test&ordinator_strategy=semantic&ordinator_title_weight=2.0&ordinator_body_weight=1.0

Go Tests

Created comprehensive test suite for Ordinator integration:

Client Tests (modules/ordinator/client_test.go):

• TestNewClient: Client initialization with enabled/disabled states
• TestClient_IsEnabled: Enable/disable functionality
• TestClient_Health: Health check with success/error cases
• TestClient_Rerank: Rerank with disabled client, empty candidates
• TestClient_UnixSocketTransport: Unix socket transport configuration
• TestRerankRequest_Weights: Weight serialization
• TestClient_Timeout: Request timeout handling
• TestClient_ContextCancellation: Context cancellation handling

Integration Tests (routers/api/v1/repo/issue_test.go):

• TestSearchIssues_OrdinatorIntegration: Integration test structure
• TestSearchIssues_OrdinatorLogging: Logging verification
• TestSearchIssues_OrdinatorQueryParams: Query parameter parsing
• TestSearchIssues_OrdinatorUserContext: User context handling
• TestSearchIssues_OrdinatorEdgeCases: Edge case handling

Test Results:

ok      forgejo.org/modules/ordinator   0.030s

All unit tests pass successfully.

Code Changes

Modified Files:

• routers/api/v1/repo/issue.go: Added comparison logging, query parameters, weights support
• modules/ordinator/client.go: Added Weights field to RerankRequest
• modules/ordinator/client_test.go: Comprehensive test suite (new file)
• routers/api/v1/repo/issue_test.go: Integration test structure (new file)

New Features:

• Original order logging: log.Debug("Ordinator: Original issue order: %v", originalOrder)
• Reranked order logging: log.Debug("Ordinator: Reranked issue order: %v", rerankedOrder)
• Order change detection: log.Info("Ordinator: Issue order changed by reranking")
• Strategy parameter: ordinator_strategy query param
• Weight parameters: ordinator_title_weight, ordinator_body_weight query params

AI Editor Configuration

• Added vendor/forgejo/ to .codeiumignore to exclude large vendored package
• Foodchain AI editor uses .codeiumignore as allowlist_file (already configured)

Deployment

• Rebuilt Forgejo with new changes
• Redeployed via Ansible successfully
• Services running with new logging and parameter support

Research

Go Testing Best Practices:

• Table-driven tests for multiple test cases
• testify/assert and testify/require for assertions
• httptest for HTTP server mocking
• Context cancellation testing
• Timeout testing
• Error handling verification

References:

• Go Wiki: TableDrivenTests
• Testing in Go with table drive tests and Testify
• Prefer table driven tests (Dave Cheney)
• Go Testing Excellence: Table-Driven Tests and Mocking

Next Steps

• Implement full integration tests with Forgejo test environment
• Add performance benchmarks for reranking
• Create admin UI for Ordinator settings
• Add metrics for reranking performance
• Consider adding A/B testing framework for reranking strategies

Integration Status (April 30, 2026)

✅ COMPLETED: Ordinator reranking service integrated into Forgejo issue search

Implementation Summary

• Go HTTP Client: Created modules/ordinator/client.go with Unix socket communication
• Settings Module: Created modules/ordinator/ordinator.go with configuration support
• API Integration: Modified routers/api/v1/repo/issue.go to rerank search results
• Configuration: Added [ordinator] section to Forgejo app.ini with ENABLED=true
• Build: Successfully built Forgejo with Ordinator integration
• Deployment: Redeployed Forgejo via Ansible with new configuration

Integration Details

• Socket Path: /var/run/reynard/ordinator.sock
• Endpoint: POST /rerank for reranking search results
• Fallback: Graceful fallback to original results if Ordinator unavailable
• User Context: Passes user_id for personalized reranking
• Strategy: Default reranking strategy with configurable limit

Configuration

[ordinator]
ENABLED = true
SOCKET_PATH = /var/run/reynard/ordinator.sock
TIMEOUT = 5

Service Status

• Ordinator service: Running on Unix socket /var/run/reynard/ordinator.sock
• Forgejo service: Running with Ordinator integration enabled
• Socket permissions: 0666 (read/write for all)

Files Modified

• vendor/forgejo/modules/ordinator/client.go - HTTP client for Unix socket
• vendor/forgejo/modules/ordinator/ordinator.go - Settings module
• vendor/forgejo/routers/api/v1/repo/issue.go - Issue search integration
• ansible/roles/forgejo/templates/app.ini.j2 - Configuration template
• ansible/roles/forgejo/tasks/main.yml - Fixed sly.so frontend conditional

Testing

• Forgejo built successfully with Ordinator integration
• Services deployed and running
• Socket accessible to Forgejo process
• Configuration loaded correctly

Next Steps

• Test issue search with reranking in production
• Monitor performance impact
• Adjust reranking strategy based on results
• Consider adding admin UI for Ordinator settings

close

# Ordinator Reranking Integration ## Overview Integrate Ordinator reranking service into Forgejo issue search to improve search relevance using multi-factor scoring (semantic similarity, personalization, authority, recency). ## Ordinator Service Status - **Service**: Running on Unix socket `/var/run/reynard/ordinator.sock` - **Endpoints**: - `GET /health` - Service health check - `POST /rerank` - Rerank search results - `GET /stats` - Service statistics - **Deployment**: Ansible-managed systemd service with resource limits - **Documentation**: `services/ordinator/DEPLOYMENT.md` ## Integration Points ### 1. Go HTTP Client for Ordinator Create a Go client package to communicate with Ordinator via Unix socket: - Location: `modules/ordinator/client.go` - Functionality: HTTP client over Unix domain socket - Endpoints: Health check, rerank request, stats ### 2. Issue Search Integration Modify issue search flow in Forgejo: - Current location: `routers/api/v1/repo/issue.go` - `SearchIssues()` - Integration point: After initial search results from indexer, pass through Ordinator for reranking - Configuration: Feature flag to enable/disable Ordinator reranking ### 3. Configuration Add Ordinator configuration to Forgejo settings: - Socket path: `/var/run/reynard/ordinator.sock` - Enable/disable reranking - Timeout settings - Fallback behavior (if Ordinator unavailable) ## Implementation Plan 1. **Create Go HTTP client for Unix socket communication** - Use `net.Dial("unix", socketPath)` for Unix socket - HTTP client wrapper for Ordinator endpoints - Error handling and fallback logic 2. **Integrate into issue search** - Modify `SearchIssues()` in `routers/api/v1/repo/issue.go` - Add reranking step after indexer results - Preserve original search results for fallback 3. **Add configuration** - Add Ordinator settings to `modules/setting/setting.go` - Add to configuration file schema - Admin UI for Ordinator settings 4. **Testing** - Unit tests for Go client - Integration tests with running Ordinator service - Performance benchmarks ## Technical Details ### Ordinator Rerank Request Format ```json { "query": "search query string", "candidates": [ {"id": "issue-1", "title": "...", "body": "..."}, {"id": "issue-2", "title": "...", "body": "..."} ], "user_context": {"user_id": 123}, "strategy": "default", "limit": 10 } ``` ### Ordinator Rerank Response Format ```json { "success": true, "data": { "reranked": [ {"id": "issue-1", "score": 0.95}, {"id": "issue-2", "score": 0.87} ] }, "error": null } ``` ## Dependencies - Ordinator service must be deployed and running - Unix socket accessible to Forgejo process - No external network dependencies (socket-only communication) ## References - Ordinator deployment: `services/ordinator/DEPLOYMENT.md` - Ordinator API: `services/ordinator/src/server.rs` - Forgejo issue search: `routers/api/v1/repo/issue.go` - Forgejo issue search models: `models/issues/issue_search.go` ## Testing and Enhancements (April 30, 2026) **✅ COMPLETED**: Testing suite and comparison logging added ### Comparison Logging - Added debug logging for original issue order before reranking - Added debug logging for reranked issue order after reranking - Added info log when issue order changes due to reranking - Enables easy comparison of original vs reranked results in logs ### User/Agent Influence Parameters Added query parameters to influence reranking behavior: - `ordinator_strategy`: Custom reranking strategy (default: "default") - `ordinator_title_weight`: Weight for title matching (float) - `ordinator_body_weight`: Weight for body/content matching (float) Example usage: ``` GET /api/v1/repos/{owner}/{repo}/issues/search?q=test&ordinator_strategy=semantic&ordinator_title_weight=2.0&ordinator_body_weight=1.0 ``` ### Go Tests Created comprehensive test suite for Ordinator integration: **Client Tests** (`modules/ordinator/client_test.go`): - TestNewClient: Client initialization with enabled/disabled states - TestClient_IsEnabled: Enable/disable functionality - TestClient_Health: Health check with success/error cases - TestClient_Rerank: Rerank with disabled client, empty candidates - TestClient_UnixSocketTransport: Unix socket transport configuration - TestRerankRequest_Weights: Weight serialization - TestClient_Timeout: Request timeout handling - TestClient_ContextCancellation: Context cancellation handling **Integration Tests** (`routers/api/v1/repo/issue_test.go`): - TestSearchIssues_OrdinatorIntegration: Integration test structure - TestSearchIssues_OrdinatorLogging: Logging verification - TestSearchIssues_OrdinatorQueryParams: Query parameter parsing - TestSearchIssues_OrdinatorUserContext: User context handling - TestSearchIssues_OrdinatorEdgeCases: Edge case handling **Test Results**: ``` ok forgejo.org/modules/ordinator 0.030s ``` All unit tests pass successfully. ### Code Changes **Modified Files**: - `routers/api/v1/repo/issue.go`: Added comparison logging, query parameters, weights support - `modules/ordinator/client.go`: Added Weights field to RerankRequest - `modules/ordinator/client_test.go`: Comprehensive test suite (new file) - `routers/api/v1/repo/issue_test.go`: Integration test structure (new file) **New Features**: - Original order logging: `log.Debug("Ordinator: Original issue order: %v", originalOrder)` - Reranked order logging: `log.Debug("Ordinator: Reranked issue order: %v", rerankedOrder)` - Order change detection: `log.Info("Ordinator: Issue order changed by reranking")` - Strategy parameter: `ordinator_strategy` query param - Weight parameters: `ordinator_title_weight`, `ordinator_body_weight` query params ### AI Editor Configuration - Added `vendor/forgejo/` to `.codeiumignore` to exclude large vendored package - Foodchain AI editor uses `.codeiumignore` as allowlist_file (already configured) ### Deployment - Rebuilt Forgejo with new changes - Redeployed via Ansible successfully - Services running with new logging and parameter support ### Research **Go Testing Best Practices**: - Table-driven tests for multiple test cases - testify/assert and testify/require for assertions - httptest for HTTP server mocking - Context cancellation testing - Timeout testing - Error handling verification **References**: - Go Wiki: TableDrivenTests - Testing in Go with table drive tests and Testify - Prefer table driven tests (Dave Cheney) - Go Testing Excellence: Table-Driven Tests and Mocking ### Next Steps - Implement full integration tests with Forgejo test environment - Add performance benchmarks for reranking - Create admin UI for Ordinator settings - Add metrics for reranking performance - Consider adding A/B testing framework for reranking strategies ## Integration Status (April 30, 2026) **✅ COMPLETED**: Ordinator reranking service integrated into Forgejo issue search ### Implementation Summary - **Go HTTP Client**: Created `modules/ordinator/client.go` with Unix socket communication - **Settings Module**: Created `modules/ordinator/ordinator.go` with configuration support - **API Integration**: Modified `routers/api/v1/repo/issue.go` to rerank search results - **Configuration**: Added `[ordinator]` section to Forgejo app.ini with ENABLED=true - **Build**: Successfully built Forgejo with Ordinator integration - **Deployment**: Redeployed Forgejo via Ansible with new configuration ### Integration Details - **Socket Path**: `/var/run/reynard/ordinator.sock` - **Endpoint**: `POST /rerank` for reranking search results - **Fallback**: Graceful fallback to original results if Ordinator unavailable - **User Context**: Passes user_id for personalized reranking - **Strategy**: Default reranking strategy with configurable limit ### Configuration ```ini [ordinator] ENABLED = true SOCKET_PATH = /var/run/reynard/ordinator.sock TIMEOUT = 5 ``` ### Service Status - Ordinator service: Running on Unix socket `/var/run/reynard/ordinator.sock` - Forgejo service: Running with Ordinator integration enabled - Socket permissions: 0666 (read/write for all) ### Files Modified - `vendor/forgejo/modules/ordinator/client.go` - HTTP client for Unix socket - `vendor/forgejo/modules/ordinator/ordinator.go` - Settings module - `vendor/forgejo/routers/api/v1/repo/issue.go` - Issue search integration - `ansible/roles/forgejo/templates/app.ini.j2` - Configuration template - `ansible/roles/forgejo/tasks/main.yml` - Fixed sly.so frontend conditional ### Testing - Forgejo built successfully with Ordinator integration - Services deployed and running - Socket accessible to Forgejo process - Configuration loaded correctly ### Next Steps - Test issue search with reranking in production - Monitor performance impact - Adjust reranking strategy based on results - Consider adding admin UI for Ordinator settings close

kade added the

enhancement

label 2026-04-30 13:34:06 +02:00

kade commented 2026-05-02 11:27:59 +02:00

Author

Owner

Copy link

Duplicate of #106. Closing to consolidate duplicate issues.

Duplicate of #106. Closing to consolidate duplicate issues.

kade closed this issue 2026-05-02 11:28:32 +02:00

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

forgejo

feature/graph-enhancement-project

main

No results found.

Labels

Clear labels   

auth

auth issues

  

bug

bug issues

  

chore

chore issues

  

ci/cd

ci/cd issues

  

dependencies

dependencies issues

  

documentation

documentation issues

  

enhancement

enhancement issues

  

feature

feature issues

  

fix

fix issues

  

graphics

graphics issues

  

tracking

tracking issues

  

vendor

vendor issues

  

workgroup

workgroup issues

No labels

auth

bug

chore

ci/cd

dependencies

documentation

enhancement

feature

fix

graphics

tracking

vendor

workgroup

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

kade/forgejo#104

No description provided.