{"id":50928356,"url":"https://github.com/persteenolsen/fastapi-jwt-auth-ai-agent-two","last_synced_at":"2026-06-17T01:31:09.697Z","repository":{"id":363382460,"uuid":"1261839079","full_name":"persteenolsen/fastapi-jwt-auth-ai-agent-two","owner":"persteenolsen","description":"Python FastAPI with JWT Auth serving a Tool-Calling AI Agent running at Render","archived":false,"fork":false,"pushed_at":"2026-06-08T16:31:55.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T18:23:02.399Z","etag":null,"topics":["ai-agent","fastapi","jwt","python","render"],"latest_commit_sha":null,"homepage":"https://fastapi-jwt-auth-ai-agent-two.onrender.com/docs","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/persteenolsen.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T08:08:52.000Z","updated_at":"2026-06-08T16:32:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/persteenolsen/fastapi-jwt-auth-ai-agent-two","commit_stats":null,"previous_names":["persteenolsen/fastapi-jwt-auth-ai-agent-two"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/persteenolsen/fastapi-jwt-auth-ai-agent-two","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-ai-agent-two","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-ai-agent-two/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-ai-agent-two/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-ai-agent-two/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/persteenolsen","download_url":"https://codeload.github.com/persteenolsen/fastapi-jwt-auth-ai-agent-two/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persteenolsen%2Ffastapi-jwt-auth-ai-agent-two/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34430688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"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-agent","fastapi","jwt","python","render"],"created_at":"2026-06-17T01:31:09.100Z","updated_at":"2026-06-17T01:31:09.672Z","avatar_url":"https://github.com/persteenolsen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 FastAPI with JWT Auth serving a Tool-Calling AI Agent\n\nA production-style AI Agent API built with FastAPI, featuring JWT authentication and a fully dynamic tool-calling architecture powered by Groq LLMs.\n\nThis project demonstrates a stable and extensible AI assistant built on a Tool Registry Agent Pattern, where tools are automatically exposed to the LLM, executed safely, and used to generate grounded responses.\n\n# Version\n\nAt Render I use the PYTHON_VERSION environment variable to tell Render to use Python version 3.11. Locally I am using Python 3.12\n\n---\n\n## 📌 Project Info\n\n- Version: 0.1.0\n- Python: 3.11 / 3.12\n- Architecture: Dynamic Tool Registry Agent (plan → execute → synthesize)\n- Last Updated: 09-06-2026\n\n---\n\n## ✨ Key Features\n\n### 🔐 Authentication\n- JWT-based authentication (HS256)\n- Protected `/chat` endpoint\n- Token-based access control\n- Environment-based credentials\n\n---\n\n### 🤖 AI Agent (Dynamic Tool System)\n- LLM-driven tool selection from a dynamic registry\n- No hardcoded tool list in prompts\n- Tools auto-injected from `TOOL_REGISTRY`\n- Execution pipeline: Plan → Execute → Synthesize\n- Safe fallback to direct LLM response\n- Protection against unknown tool execution\n\n---\n\n### 🧠 LLM Integration (Groq)\n- Model: llama-3.3-70b-versatile\n- High-speed inference via Groq API\n- Temperature set to 0 for deterministic output\n- Used for tool routing, query rewriting, and final synthesis\n\n---\n\n### 🧩 Tool Registry System\n- Central `TOOL_REGISTRY` defines all tools\n- LLM automatically receives tool list from registry\n- Adding tools requires only creating the tool file and registering it\n- Built-in tools:\n  - Wikipedia 📚 (general knowledge)\n  - Wikidata 🧾 (structured facts)\n  - Calculator ➗ (safe arithmetic engine)\n\n---\n\n### ➗ Calculator Tool\n- AST-based safe evaluator (no eval)\n- Supports: +, -, *, /, %, **, // and parentheses\n- Fully sandboxed execution\n- Auto-used for pure math expressions\n\n---\n\n### 🌐 Wikipedia Tool\n- Two-step retrieval:\n  - Search API for entity lookup\n  - REST summary API for content extraction\n- Retry-enabled HTTP session\n- Robust fallback handling\n\n---\n\n### 🧾 Wikidata Tool\n- Entity search via Wikidata API\n- LLM-assisted query simplification\n- Optimized for structured facts and rankings\n\n---\n\n## 📡 API Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST   | /login  | 🔐 Get JWT access token |\n| POST   | /chat   | 💬 Chat with AI agent |\n| GET    | /health | ❤️ Service health check |\n| GET    | /health/tools | 🧩 All registered tools health |\n| GET    | /health/tools/{tool_name} | 🔍 Single tool health check |\n\n---\n\n## ⚙️ Getting Started\n\n### 1. Clone Repository\ngit clone https://github.com/your-username/your-repo.git  \ncd your-repo  \n\n### 2. 🐍 Create Virtual Environment\npython -m venv venv  \n\nActivate:\n\n🪟 Windows  \nvenv\\Scripts\\activate  \n\n🐧 Mac/Linux  \nsource venv/bin/activate  \n\n### 3. 📦 Install Dependencies\npip install -r requirements.txt  \n\n---\n\n## 🔑 Environment Variables\n\nCreate a `.env` file:\n\nSECRET_KEY=your_secret_key_here  \nGROQ_API_KEY=your_groq_api_key  \nFAKE_USERNAME=admin  \nFAKE_PASSWORD=password  \n\nGenerate secret key:\n\npython -c \"import secrets; print(secrets.token_hex(32))\"  \n\n---\n\n## ▶️ Run Application\n\nuvicorn main:app --reload  \n\n🌐 API: http://127.0.0.1:8000  \n📘 Docs: http://127.0.0.1:8000/docs  \n\n---\n\n## 🔐 Authentication Flow\n\n1. Call `/login` with credentials  \n2. Receive JWT token  \n3. Send token in header: `Authorization: Bearer \u003ctoken\u003e`  \n4. Access `/chat` endpoint  \n\n---\n\n## 🧠 How the Agent Works\n\nUser message → LLM reads available tools from registry → LLM generates tool plan → Registry validates tools → Tools execute safely → Results collected → LLM generates final grounded response  \n\n---\n\n## 🏗️ Architecture\n\n### 🟢 Tool Registry Agent (Current System)\n\n- Fully dynamic tool discovery  \n- No hardcoded tool list in prompt  \n- Safe execution via registry  \n- Extensible plug-and-play tools  \n- Deterministic execution pipeline  \n\n### 🔵 Not ReAct\n\nThis system does not use ReAct.  \nIt does not:\n- iterate reasoning step-by-step\n- call tools in loops\n- update reasoning after each tool call\n\nInstead:\n\nPlan → Execute → Synthesize\n\n---\n\n## 💬 Example Requests\n\n### No tool example\n\nPOST /chat  \n{  \n  \"message\": \"Tell me a joke\"  \n} \n\n{\n  \"response\": \"What do you call a fake noodle? An impasta.\",\n  \"tools_used\": [],\n  \"steps\": [\n    \"tool_plan=[]\"\n  ],\n  \"error_id\": null\n}\n\n---\n\n### Calculator Example\n\nPOST /chat  \n{  \n  \"message\": \"What is 25 * 18 + 10?\"  \n}  \n\n{\n  \"response\": \"To calculate the result of the expression \\\"25 * 18 + 10\\\", we can follow the order of operations. First, we multiply 25 by 18, which equals 450. Then, we add 10 to this result, giving us a final answer of 460. This calculation is confirmed by the provided tool data from the calculator, which also yields a result of 460 for the expression \\\"25 * 18 + 10\\\". Therefore, the answer to the given expression is 460.\",\n  \"tools_used\": [\n    {\n      \"tool\": \"calculator\",\n      \"query\": \"25 * 18 + 10\",\n      \"success\": true\n    }\n  ],\n  \"steps\": [\n    \"tool_plan=[{'name': 'calculator', 'query': '25 * 18 + 10'}]\"\n  ],\n  \"error_id\": null\n}\n\n---\n\n### Wikipedia Example\n\nPOST /chat  \n{  \n  \"message\": \"What is AI?\"  \n}  \n\n{\n  \"response\": \"According to the provided Wikipedia data, Artificial Intelligence (AI) refers to the ability of computational systems to perform tasks that are typically associated with human intelligence. These tasks include learning, reasoning, problem-solving, perception, and decision-making. In essence, AI is a field of research that focuses on developing methods and software to enable machines to perceive their environment, learn, and take actions to achieve specific goals.\",\n  \"tools_used\": [\n    {\n      \"tool\": \"wikipedia\",\n      \"query\": \"Artificial intelligence\",\n      \"success\": true\n    }\n  ],\n  \"steps\": [\n    \"tool_plan=[{'name': 'wikipedia', 'query': 'Artificial intelligence'}]\"\n  ],\n  \"error_id\": null\n}\n\n---\n\n## 🚀 Benefits\n\n- 🧩 Fully extensible tool system  \n- 🧠 No prompt maintenance required when adding tools  \n- 🛡️ Safe execution layer for all tools  \n- 🧱 Clean separation of agent / tools / API  \n- ⚙️ Production-ready FastAPI structure  \n- 📊 Deterministic and debuggable behavior  \n\n---\n\n## 🚧 Current Limitations\n\n- Stateless per request  \n- Single-step planning only  \n- No streaming responses yet  \n- Limited tool ecosystem  \n\n---\n\n## 🚀 Future Improvements\n\n- 🧠 Conversation memory  \n- 🌊 Streaming responses (SSE/WebSockets)  \n- ⚡ Parallel tool execution  \n- 📊 Tool confidence scoring  \n- 💾 Caching layer for Wikipedia/Wikidata  \n- 🔗 Multi-step tool chaining  \n\n---\n\n## 📄 License\n\nMIT License  \n\n---\n\n## 🙌 Final Notes\n\nThis project implements a modern dynamic tool registry architecture where tools are first-class citizens and the LLM dynamically adapts to available capabilities, enabling a scalable foundation for multi-tool AI systems.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersteenolsen%2Ffastapi-jwt-auth-ai-agent-two","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpersteenolsen%2Ffastapi-jwt-auth-ai-agent-two","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersteenolsen%2Ffastapi-jwt-auth-ai-agent-two/lists"}