fix(provider): map 'free' model to openrouter/auto for OpenRouter free tier

[HRronaldo]

Summary

• Fix issue I can't add openrouter/free model in picoclaw #901: Users can now use model: "free" with OpenRouter provider
• The "free" alias is automatically mapped to "openrouter/auto" which selects the best available free model

Description

When using OpenRouter with model: "free", the API was returning an error:

"free is not a valid model ID"

This fix adds model alias mapping in pkg/providers/factory.go - when the model is set to "free", it's automatically converted to "openrouter/auto" which is the correct identifier for OpenRouter's free tier.

Changes made in two locations:

1. Explicit openrouter provider case (lines 95-108)
2. Default fallback case when OpenRouter is inferred (lines 302-314)

Type of Change

• Bug fix
• Feature
• Documentation
• Refactor

🤖 AI Code Generation

• 🤖 Fully AI-generated - AI wrote the code; contributor reviewed and validated it
• 🛠️ Mostly AI-generated
• 👨‍💻 Mostly Human-written

Related Issue

Closes #901

Technical Context

• OpenRouter requires specific model identifiers like "openrouter/auto" or actual model names
• "free" is an alias that should map to "openrouter/auto"
• Similar pattern used for deepseek model defaults (lines 171-173)

Test Environment

• Go 1.25+
• Tested with: go test -run TestResolveProviderSelection ./pkg/providers/
• All provider selection tests pass

[xiaket]

I think this should be changed in doc land but not in code, please change my mind.

[HRronaldo]

Hi xiaket，感谢review！

理解你的顾虑，但为什么我认为代码修复更好：

1. 用户体验：用户很自然地期望 model: "free" 能直接使用 OpenRouter 免费层。错误信息 "free is not a valid model ID" 非常容易造成困惑。

2. 与现有模式一致：代码库已经为 deepseek 做了类似的映射处理（factory.go 第 171-173 行）。

3. 降低使用门槛：代码修复后，用户只需设置 model: "free" 就能直接使用。没有修复的话，用户需要：

   • 了解 OpenRouter 的模型命名规则
   • 知道要用 "openrouter/auto"
   • 手动修改配置文件

4. 这是 Bug 而非功能：Issue I can't add openrouter/free model in picoclaw #901 标记的是 bug - 系统没有按用户预期工作。文档只是临时解决方案，不是真正的修复。

---

或者，如果你接受我的观点的话，我可以添加一个更温和的版本：只映射 model: "free" 这一个特殊情况，而不是通用的 "auto" 逻辑。这样代码变更最小，同时解决了用户的问题。

你怎么看？

[xiaket]

@HRronaldo , in order to make this community accessible to everyone, I would strongly suggest you use English for discussions.

Please translate the above into English.

[HRronaldo]

Hi xiaket, thanks for the review!

I understand your concern, but here's why I think code fix is better:

1. User Experience: Users naturally expect model: "free" to work with OpenRouter's free tier. The error "free is not a valid model ID" is confusing and provides poor UX.

2. Consistent with existing patterns: The codebase already does similar mapping for deepseek - when users set deepseek-chat, it's automatically mapped if needed (factory.go lines 171-173).

3. Lower friction: With the code fix, users can just set model: "free" and it works. Without it, users need to:

   • Understand OpenRouter's model naming
   • Know about "openrouter/auto"
   • Edit their config

4. This is a bug, not feature: Issue I can't add openrouter/free model in picoclaw #901 is marked as a bug - the system is not working as users expect. Documentation would be a workaround, not a fix.

Would you be okay with keeping both? I can add a note in the docs about "openrouter/auto" as an alternative, while keeping the code fix for better UX.

[xiaket]

Users naturally expect model: "free" to work with OpenRouter's free tier

I was looking at OpenRouter earlier and I cannot find anything that would suggest this usage. I would say the GH issue raised earlier is more of a mis-understanding, not a real issue on picoclaw.

Adding this shortcut may seem fine for now, but longer term it would bring ambiguity to the project, for example, other models may be asking the same shortcut. As you can understand, shortcut is always unofficial and would increase maintenance overhead.

[HRronaldo]

Hi xiaket,

I understand your perspective now. You're right that:

1. "free" is not an official OpenRouter model identifier
2. Adding shortcuts creates maintenance overhead and ambiguity
3. This should be handled at the documentation level, not in code

I'll close this PR and instead add a documentation note explaining that users should use model: "openrouter/auto" for OpenRouter's free tier.

Thanks for the thoughtful review - it helps keep the codebase clean and maintainable.