Add filtering argument to Search Mode

[CShorten]

Description

Adds a filtering parameter to the Query Agent's Search Mode. This allows users to control the trade-off between recall and precision.

The parameter accepts two values: "recall" to optimize for finding all relevant results, or "precision" to optimize for the accuracy of returned results.

Usage example:

agent = QueryAgent(
  client=client, 
  collections=["FinancialContracts"]
)
                                                                                
# Default behavior (recall) 
results = agent.search("Find all NDAs signed by Jane Doe in 2024.")           
                                                                                
# Optimize for precision
results = agent.search(
  "Find all NDAs signed by Jane Doe in 2024.",
  filtering="precision"
)

Pagination Fix

Empty search lists are cached from precision mode's ability to output no searches, ensuring pagination requests are consistent.

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[CShorten]

Remove defaulting it to recall.

[cdpierse]

What's the desired behaviour we would like if a user does not pass filtering? If the server handles filtering=None then we should make it a optional Literal where when the value is None it defaults to server side values.

Right now if we were to make the decision for any reason to make precision the default for search mode server side for any customer they would have to update the client in order for this to take effect.

This might not be the actual desired behaviour but I wanted to flag that this what the state would be if we ship as is. Happy to hear thoughts from @augustas1 @danmichaeljones @dannyjameswilliams also here

[dannyjameswilliams]

What's the desired behaviour we would like if a user does not pass filtering? If the server handles filtering=None then we should make it a optional Literal where when the value is None it defaults to server side values.

Right now if we were to make the decision for any reason to make precision the default for search mode server side for any customer they would have to update the client in order for this to take effect.

I think this is probably a sensible solution, as long as it's kept up to date in the docs (or probably at least the docstring of the method) what the server-side default is.

Then we may also want to update result_evaluation to be the same, as it is a similar setting.

[cdpierse]

What's the need for this additional is not None check isn't the parsed_respond.searches model the same ?

[CShorten]

In precision mode we are allowing Search Mode to return no searches, so we need to check that here in order to avoid re-generating searches instead of re-executing the cached one with pagination.

[cdpierse]

Same as above

[CShorten]

In precision mode we are allowing Search Mode to return no searches, so we need to check that here in order to avoid re-generating searches instead of re-executing the cached one with pagination.