{"id":30105865,"url":"https://github.com/posgnu/fastapi-langgraph","last_synced_at":"2025-08-10T00:20:23.837Z","repository":{"id":308556679,"uuid":"1031917117","full_name":"posgnu/fastapi-langgraph","owner":"posgnu","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-06T14:26:51.000Z","size":127,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-06T16:32:13.126Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/posgnu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-08-04T14:23:42.000Z","updated_at":"2025-08-06T14:28:06.000Z","dependencies_parsed_at":"2025-08-06T16:32:32.242Z","dependency_job_id":"bad7db3f-2226-4aa1-b8c0-af21f5acc239","html_url":"https://github.com/posgnu/fastapi-langgraph","commit_stats":null,"previous_names":["posgnu/fastapi-langgraph"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/posgnu/fastapi-langgraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posgnu%2Ffastapi-langgraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posgnu%2Ffastapi-langgraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posgnu%2Ffastapi-langgraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posgnu%2Ffastapi-langgraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/posgnu","download_url":"https://codeload.github.com/posgnu/fastapi-langgraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posgnu%2Ffastapi-langgraph/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269657668,"owners_count":24454906,"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-08-09T02:00:10.424Z","response_time":111,"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":[],"created_at":"2025-08-10T00:20:22.712Z","updated_at":"2025-08-10T00:20:23.771Z","avatar_url":"https://github.com/posgnu.png","language":"Python","readme":"# FastAPI LangGraph Template\n\nA production-ready template for building enterprise-grade FastAPI applications with LangGraph integration, featuring streaming conversational AI agents with thread-based persistence and conversation management.\n\n## 🎯 What This Template Provides\n\n- **Thread-Based Conversations**: Ready-to-use persistent conversation threads with unique identifiers\n- **Token-Level Streaming**: Real-time response streaming with WebSocket-like experience\n- **Enterprise-Grade Error Handling**: Comprehensive error handling and logging infrastructure\n- **Thread Management**: Complete thread lifecycle management (create, retrieve, clear, archive)\n- **RESTful API**: Well-designed API structure following enterprise patterns\n- **Type Safety**: Full TypeScript-style type annotations with Pydantic models\n\n## 🏗️ Template Architecture\n\n### Persistence Strategy\n\nThis template implements thread-based persistence using LangGraph's MemorySaver pattern:\n\n- **Thread Checkpoints**: Each conversation thread maintains its state\n- **Conversation Continuity**: Threads can be resumed exactly where they left off\n- **Message History**: Complete conversation history retrieval for any thread\n\n```mermaid\ngraph TD\n    A[User Request] --\u003e B[Thread Manager]\n    B --\u003e C[Load Thread State]\n    C --\u003e D[Agent Processing]\n    D --\u003e E[Generate Response]\n    E --\u003e F[Save Thread State]\n    F --\u003e G[Stream Response]\n```\n\n## 🚀 Getting Started with This Template\n\n### 1. Use This Template\n\n```bash\n# Create a new repository from this template\n# Click \"Use this template\" on GitHub, or clone directly:\ngit clone https://github.com/posgnu/fastapi-langraph.git your-project-name\ncd your-project-name\n\n# Rename the project\n# Update pyproject.toml, README.md, and other references as needed\n```\n\n### 2. Environment Setup\n\n```bash\n# Create environment file\ncp .env.example .env\n# Add your OPENAI_API_KEY and customize other settings\n\n# Install dependencies\npoetry install\n```\n\n### 3. Customize Your Agent\n\nEdit `fastapi_langraph/agent/` to implement your specific agent logic:\n\n```python\n# Example: Customize the agent behavior\n# In fastapi_langraph/agent/tools/\n# Add your custom tools and capabilities\n```\n\n### 4. Start Development Server\n\n```bash\npoetry run uvicorn fastapi_langraph.main:app --reload\n```\n\nThe server will start at `http://localhost:8000` with:\n- API Documentation: `http://localhost:8000/docs`\n- Service Info: `http://localhost:8000/info`\n\n### 5. Test Your Implementation\n\n```bash\n# Use the included chat client to test your agent\npoetry run python scripts/chat.py\n```\n\n## 📚 Template API Structure\n\nThis template provides a complete API structure that you can build upon:\n\n### Core Chat Endpoints\n\n#### `POST /chat/stream` - Stream Chat with Persistence\nStream conversational responses with thread persistence.\n\n**Request Format:**\n```json\n{\n  \"input\": \"Your user message here\",\n  \"thread_id\": \"optional-thread-id\",\n  \"session_metadata\": {\n    \"client\": \"your_app\",\n    \"timestamp\": \"2024-01-01T00:00:00Z\"\n  }\n}\n```\n\n**Response Stream Format:**\n```json\n{\"type\": \"metadata\", \"thread_id\": \"abc-123\", \"metadata\": {\"thread_created\": true}}\n{\"type\": \"token\", \"content\": \"Response\", \"thread_id\": \"abc-123\"}\n{\"type\": \"metadata\", \"thread_id\": \"abc-123\", \"metadata\": {\"status\": \"completed\"}}\n```\n\n### Thread Management Endpoints\n\n- `GET /threads/{thread_id}/history` - Retrieve conversation history\n- `DELETE /threads/{thread_id}` - Delete thread and history\n- `PUT /threads/{thread_id}/clear` - Clear thread messages\n- `PUT /threads/{thread_id}/archive` - Archive thread (customize as needed)\n\n### Service Information\n\n- `GET /info` - Service information and capabilities\n\n## 🛠️ Customization Guide\n\n### 1. Agent Customization\n\nReplace the default agent implementation in `fastapi_langraph/agent/`:\n\n```python\n# Example: Custom agent with your tools\nfrom your_tools import CustomTool1, CustomTool2\n\ndef create_your_agent():\n    # Implement your agent logic here\n    return agent\n```\n\n### 2. Add Custom Tools\n\nExtend the tools directory:\n\n```bash\n# Add your tools in fastapi_langraph/agent/tools/\ntouch fastapi_langraph/agent/tools/your_custom_tool.py\n```\n\n### 3. Database Integration\n\nReplace the in-memory storage with your preferred database:\n\n```python\n# For SQLite\nfrom langgraph.checkpoint.sqlite import SqliteSaver\ncheckpointer = SqliteSaver(\"./your_app.db\")\n\n# For PostgreSQL\nfrom langgraph.checkpoint.postgres import PostgresSaver\ncheckpointer = PostgresSaver(connection_string=\"postgresql://...\")\n```\n\n### 4. Middleware Customization\n\nAdd your middleware in `fastapi_langraph/middleware/`:\n\n```python\n# Example: Authentication, rate limiting, etc.\n@app.middleware(\"http\")\nasync def your_custom_middleware(request: Request, call_next):\n    # Your middleware logic\n    pass\n```\n\n### 5. API Customization\n\nExtend or modify the API routers in `fastapi_langraph/api/routers/`:\n\n```python\n# Add your custom endpoints\n@router.post(\"/your-custom-endpoint\")\nasync def your_endpoint():\n    # Your endpoint logic\n    pass\n```\n\n## 🚀 Production Deployment\n\n### 1. Update Configuration\n\n```python\n# Update fastapi_langraph/core/config.py\nclass Settings(BaseSettings):\n    project_name: str = \"Your Project Name\"\n    description: str = \"Your project description\"\n    # Add your custom settings\n```\n\n### 2. Choose Your Persistence Backend\n\n```python\n# Production-ready persistence options\n# SQLite for small-scale\n# PostgreSQL for enterprise scale\n# Redis for caching\n```\n\n### 3. Add Monitoring\n\n```python\n# Add your monitoring solution\n# Prometheus, DataDog, New Relic, etc.\n```\n\n## 🧪 Testing Your Implementation\n\n### Unit Tests\n```bash\n# Add your tests in tests/\npoetry run pytest tests/\n```\n\n### Integration Testing\n```bash\n# Test your customized endpoints\ncurl -X POST \"http://localhost:8000/chat/stream\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"input\": \"Test your agent\", \"thread_id\": \"test-thread\"}' \\\n     --no-buffer\n```\n\n### Chat Client Testing\n```bash\n# Use the included interactive client\npoetry run python scripts/chat.py\n```\n\n## 📁 Template Structure\n\n```\nyour-project/\n├── fastapi_langraph/          # Main application package\n│   ├── agent/                 # Agent implementation (customize this)\n│   │   └── tools/            # Agent tools (add your tools here)\n│   ├── api/                   # API layer\n│   │   └── routers/          # API routers (extend as needed)\n│   ├── core/                  # Core configuration and utilities\n│   └── middleware/            # Custom middleware\n├── scripts/                   # Utility scripts\n├── tests/                     # Test suite (add your tests)\n├── pyproject.toml            # Dependencies (update for your project)\n└── README.md                 # This file (customize for your project)\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\n```bash\n# Required\nOPENAI_API_KEY=your-openai-api-key\n\n# Customize these for your project\nPROJECT_NAME=Your-Project-Name\nDESCRIPTION=Your project description\nLOG_LEVEL=INFO\nMAX_CONVERSATION_LENGTH=20\n```\n\n### Agent Configuration\n\n```python\n# Customize in fastapi_langraph/core/config.py\nAGENT_CONFIG = {\n    \"model\": \"gpt-4o-mini\",  # Choose your model\n    \"temperature\": 0.1,       # Adjust for your use case\n    \"max_context_messages\": 20,\n    \"streaming\": True\n}\n```\n\n## 🎯 Next Steps\n\n1. **Clone/Fork** this template\n2. **Customize** the agent logic for your use case\n3. **Add** your specific tools and capabilities\n4. **Configure** your persistence backend\n5. **Deploy** to your preferred platform\n6. **Monitor** and iterate\n\n## 🤝 Contributing to the Template\n\nImprovements to this template are welcome:\n\n1. Fork the template repository\n2. Create a feature branch\n3. Add comprehensive tests\n4. Follow the existing code style\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🆘 Support\n\n- **Issues**: Submit GitHub issues for template bugs and improvements\n- **Discussions**: Use GitHub Discussions for questions about using this template\n\n---\n\n**⭐ Star this template if it helps you build amazing AI applications!**\n\n**Built with ❤️ using FastAPI, LangGraph, and OpenAI**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposgnu%2Ffastapi-langgraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposgnu%2Ffastapi-langgraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposgnu%2Ffastapi-langgraph/lists"}