feat(ai): add Hugging Face provider support

- Add huggingface to KnownProvider type
- Add HF_TOKEN env var mapping
- Process huggingface models from models.dev (14 models)
- Use openai-completions API with compat settings
- Add tests for all provider test suites
- Update documentation

fixes #994

packages/ai/test/total-tokens.test.ts

@@ -306,6 +306,25 @@ describe("totalTokens field", () => {
 		);
 	});
 
+	// =========================================================================
+	// Hugging Face
+	// =========================================================================
+
+	describe.skipIf(!process.env.HF_TOKEN)("Hugging Face", () => {
+		it("Kimi-K2.5 - should return totalTokens equal to sum of components", { retry: 3, timeout: 60000 }, async () => {
+			const llm = getModel("huggingface", "moonshotai/Kimi-K2.5");
+
+			console.log(`\nHugging Face / ${llm.id}:`);
+			const { first, second } = await testTotalTokensWithCache(llm, { apiKey: process.env.HF_TOKEN });
+
+			logUsage("First request", first);
+			logUsage("Second request", second);
+
+			assertTotalTokensEqualsComponents(first);
+			assertTotalTokensEqualsComponents(second);
+		});
+	});
+
 	// =========================================================================
 	// z.ai
 	// =========================================================================