{"id":31424844,"url":"https://github.com/doganarif/fastapi-ai-sdk","last_synced_at":"2025-10-02T12:06:33.589Z","repository":{"id":316655934,"uuid":"1064327731","full_name":"doganarif/fastapi-ai-sdk","owner":"doganarif","description":"FastAPI helper library for Vercel AI SDK backend implementation - Stream AI responses from FastAPI to Next.js with full type safety and SSE support","archived":false,"fork":false,"pushed_at":"2025-09-25T21:50:27.000Z","size":82,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T23:42:27.976Z","etag":null,"topics":["ai","ai-sdk","fastapi","llm","nextjs","python","vercel"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doganarif.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T21:48:00.000Z","updated_at":"2025-09-25T22:49:11.000Z","dependencies_parsed_at":"2025-09-25T23:42:32.690Z","dependency_job_id":null,"html_url":"https://github.com/doganarif/fastapi-ai-sdk","commit_stats":null,"previous_names":["doganarif/fastapi-ai-sdk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/doganarif/fastapi-ai-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doganarif%2Ffastapi-ai-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doganarif%2Ffastapi-ai-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doganarif%2Ffastapi-ai-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doganarif%2Ffastapi-ai-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doganarif","download_url":"https://codeload.github.com/doganarif/fastapi-ai-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doganarif%2Ffastapi-ai-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278001478,"owners_count":25913083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-02T02:00:08.890Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-sdk","fastapi","llm","nextjs","python","vercel"],"created_at":"2025-09-30T04:06:23.131Z","updated_at":"2025-10-02T12:06:33.544Z","avatar_url":"https://github.com/doganarif.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI AI SDK\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI--green.svg)](https://fastapi.tiangolo.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA Pythonic helper library for building FastAPI applications that integrate with the [Vercel AI SDK](https://sdk.vercel.ai/). This library provides a seamless way to stream AI responses from your FastAPI backend to your Next.js frontend.\n\n## Features\n\n- **Full Vercel AI SDK Compatibility** - Implements the complete AI SDK protocol specification\n- **Type-Safe with Pydantic** - Full type hints and validation for all events\n- **Streaming Support** - Built-in Server-Sent Events (SSE) streaming\n- **Easy Integration** - Simple decorators and utilities for FastAPI\n- **Flexible Builder Pattern** - Intuitive API for constructing AI streams\n- **Well Tested** - Comprehensive test coverage\n- **Fully Documented** - Complete documentation with examples\n\n## Installation\n\n```bash\npip install fastapi-ai-sdk\n```\n\n## Quick Start\n\n### Basic Example\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_ai_sdk import AIStreamBuilder, ai_endpoint\n\napp = FastAPI()\n\n@app.post(\"/api/chat\")\n@ai_endpoint()\nasync def chat(message: str):\n    \"\"\"Simple chat endpoint that streams a response.\"\"\"\n    builder = AIStreamBuilder()\n    builder.text(f\"You said: {message}\")\n    return builder\n```\n\n### Frontend Integration (Next.js)\n\n```tsx\nimport { useChat } from \"@ai-sdk/react\";\n\nexport default function Chat() {\n  const { messages, input, handleInputChange, handleSubmit } = useChat({\n    api: \"http://localhost:8000/api/chat\",\n  });\n\n  return (\n    \u003cdiv\u003e\n      {messages.map((msg) =\u003e (\n        \u003cdiv key={msg.id}\u003e{msg.content}\u003c/div\u003e\n      ))}\n      \u003cform onSubmit={handleSubmit}\u003e\n        \u003cinput value={input} onChange={handleInputChange} /\u003e\n        \u003cbutton type=\"submit\"\u003eSend\u003c/button\u003e\n      \u003c/form\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## Documentation\n\n### Stream Events\n\nThe library supports all Vercel AI SDK event types:\n\n- **Message Lifecycle**: `start`, `finish`\n- **Text Streaming**: `text-start`, `text-delta`, `text-end`\n- **Reasoning**: `reasoning-start`, `reasoning-delta`, `reasoning-end`\n- **Tool Calls**: `tool-input-start`, `tool-input-delta`, `tool-input-available`, `tool-output-available`\n- **Structured Data**: Custom `data-*` events\n- **File References**: URLs and documents\n- **Error Handling**: Error events with messages\n\n### Using the Stream Builder\n\n```python\nfrom fastapi_ai_sdk import AIStreamBuilder\n\n# Create a builder\nbuilder = AIStreamBuilder(message_id=\"optional_id\")\n\n# Add different types of content\nbuilder.start()  # Start the stream\nbuilder.text(\"Here's some text\")  # Add text content\nbuilder.reasoning(\"Let me think about this...\")  # Add reasoning\nbuilder.data(\"weather\", {\"temperature\": 20, \"city\": \"Berlin\"})  # Add structured data\nbuilder.tool_call(  # Add tool usage\n    \"get_weather\",\n    input_data={\"city\": \"Berlin\"},\n    output_data={\"temperature\": 20}\n)\nbuilder.finish()  # End the stream\n\n# Build and return the stream\nreturn builder.build()\n```\n\n### Decorators\n\n#### `@ai_endpoint` - Automatic AI SDK Response Handling\n\n```python\n@app.post(\"/chat\")\n@ai_endpoint()\nasync def chat(message: str):\n    builder = AIStreamBuilder()\n    builder.text(f\"Response: {message}\")\n    return builder\n```\n\n#### `@streaming_endpoint` - Simple Text Streaming\n\n```python\n@app.get(\"/stream\")\n@streaming_endpoint(chunk_size=10, delay=0.1)\nasync def stream():\n    return \"This text will be streamed chunk by chunk\"\n```\n\n#### `@tool_endpoint` - Tool Call Handling\n\n```python\n@app.post(\"/tools/weather\")\n@tool_endpoint(\"get_weather\")\nasync def get_weather(city: str):\n    # Your tool logic here\n    return {\"temperature\": 20, \"condition\": \"sunny\"}\n```\n\n### Advanced Examples\n\n#### Streaming with Reasoning and Tools\n\n```python\n@app.post(\"/api/advanced-chat\")\n@ai_endpoint()\nasync def advanced_chat(query: str):\n    builder = AIStreamBuilder()\n\n    # Start with reasoning\n    builder.reasoning(\"Analyzing your query...\")\n\n    # Make a tool call\n    weather_data = await get_weather_data(\"Berlin\")\n    builder.tool_call(\n        \"get_weather\",\n        input_data={\"city\": \"Berlin\"},\n        output_data=weather_data\n    )\n\n    # Stream the response\n    builder.text(f\"Based on the weather data: {weather_data}\")\n\n    return builder\n```\n\n#### Custom Async Generators\n\n```python\nfrom fastapi_ai_sdk import create_ai_stream_response\n\n@app.get(\"/api/generate\")\nasync def generate():\n    async def event_generator():\n        from fastapi_ai_sdk.models import StartEvent, TextDeltaEvent, FinishEvent\n\n        yield StartEvent(message_id=\"gen_1\")\n\n        for word in [\"Hello\", \" \", \"from\", \" \", \"FastAPI\"]:\n            yield TextDeltaEvent(id=\"txt_1\", delta=word)\n            await asyncio.sleep(0.1)\n\n        yield FinishEvent()\n\n    return create_ai_stream_response(event_generator())\n```\n\n#### Chunked Text Streaming\n\n```python\n@app.post(\"/api/story\")\n@ai_endpoint()\nasync def generate_story(prompt: str):\n    builder = AIStreamBuilder()\n\n    story = await generate_long_story(prompt)  # Your story generation logic\n\n    # Stream with custom chunk size\n    builder.text(story, chunk_size=50)  # Streams in 50-character chunks\n\n    return builder\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests with coverage\npytest --cov=fastapi_ai_sdk --cov-report=term-missing\n\n# Run specific test file\npytest tests/test_models.py\n\n# Run with verbose output\npytest -v\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/doganarif/fastapi-ai-sdk.git\ncd fastapi-ai-sdk\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run linting\nblack fastapi_ai_sdk tests\nisort fastapi_ai_sdk tests\nflake8 fastapi_ai_sdk tests\nmypy fastapi_ai_sdk\n```\n\n### Code Style\n\nThis project uses:\n\n- **Black** for code formatting\n- **isort** for import sorting\n- **flake8** for linting\n- **mypy** for type checking\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Arif Dogan**\n\n- Email: me@arif.sh\n- GitHub: [@doganarif](https://github.com/doganarif)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## Acknowledgments\n\n- [Vercel AI SDK](https://sdk.vercel.ai/) for the excellent frontend SDK\n- [FastAPI](https://fastapi.tiangolo.com/) for the amazing web framework\n- [Pydantic](https://docs.pydantic.dev/) for data validation\n\n## Resources\n\n- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n- [Server-Sent Events Specification](https://html.spec.whatwg.org/multipage/server-sent-events.html)\n\n---\n\n\u003cp align=\"center\"\u003eMade with ❤️ for the FastAPI and AI community from Arif\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoganarif%2Ffastapi-ai-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoganarif%2Ffastapi-ai-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoganarif%2Ffastapi-ai-sdk/lists"}