{"id":28260080,"url":"https://github.com/savinrazvan/flexiai-toolsmith","last_synced_at":"2026-02-22T13:44:48.856Z","repository":{"id":293869838,"uuid":"985183644","full_name":"SavinRazvan/flexiai-toolsmith","owner":"SavinRazvan","description":"Python framework for building AI Agents -\u003e CLI \u0026 Quart-SSE UIs, Toolsmith RAG plug-ins, full Assistant-API workflows via the OpenAI SDK (OpenAI / Azure today). Support for DeepSeek \u0026 Qwen is pending Assistant endpoint access.","archived":false,"fork":false,"pushed_at":"2025-06-08T16:40:01.000Z","size":1231,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-08T17:30:02.667Z","etag":null,"topics":["ai","ai-assistant","azure-openai","chatbot-framework","cli","csv-tools","deepseek","event-driven","github-azure-inference","ocr","openai","quart","qwen","rag","redis-pubsub","security-audit","spreadsheets","sse","streaming","toolsmith"],"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/SavinRazvan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2025-05-17T08:26:02.000Z","updated_at":"2025-06-08T16:40:05.000Z","dependencies_parsed_at":"2025-06-08T17:23:51.625Z","dependency_job_id":"5933402d-09b0-48dc-bfc7-1041cbf830f1","html_url":"https://github.com/SavinRazvan/flexiai-toolsmith","commit_stats":null,"previous_names":["savinrazvan/flexiai-toolsmith"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SavinRazvan/flexiai-toolsmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SavinRazvan%2Fflexiai-toolsmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SavinRazvan%2Fflexiai-toolsmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SavinRazvan%2Fflexiai-toolsmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SavinRazvan%2Fflexiai-toolsmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SavinRazvan","download_url":"https://codeload.github.com/SavinRazvan/flexiai-toolsmith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SavinRazvan%2Fflexiai-toolsmith/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260450037,"owners_count":23010997,"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","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-assistant","azure-openai","chatbot-framework","cli","csv-tools","deepseek","event-driven","github-azure-inference","ocr","openai","quart","qwen","rag","redis-pubsub","security-audit","spreadsheets","sse","streaming","toolsmith"],"created_at":"2025-05-20T04:09:09.864Z","updated_at":"2026-02-22T13:44:48.819Z","avatar_url":"https://github.com/SavinRazvan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlexiAI Toolsmith\n\n[![Python \u003e=3.12](https://img.shields.io/badge/python-3.12+-darkblue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-darkgreen.svg)](https://opensource.org/licenses/MIT)\n\n**FlexiAI Toolsmith** is a modular Python framework for building applied AI assistants that combine large language models with structured context, backend tools, and external services.\n\nThe framework focuses on **orchestration, extensibility, and practical use cases**, enabling AI systems to move beyond generic chat and perform concrete tasks such as data processing, automation workflows, and system checks. It supports both CLI and web-based interaction with real-time streaming and a pluggable tool architecture.\n\nFlexiAI Toolsmith was designed as a reusable foundation and has been used to build multiple applied systems, including:\n\n* **Alina Assistant** – a customer service automation system handling identification, validation, and subscription workflows.\n* **Security analysis agents** that perform structured configuration checks and inspections through controlled, tool-driven execution.\n\nThe project emphasizes clarity of architecture, modular design, and real-world usability rather than experimentation or model benchmarking.\n\n---\n\n## Key Characteristics\n\n* **Modular Architecture** – Clear separation between orchestration, tools, channels, and providers.\n* **Tool-Driven AI** – Assistants invoke structured tools via explicit tool calls instead of relying on free-form responses.\n* **Context-Aware Workflows** – Structured context is injected into assistant interactions to ensure grounded behavior.\n* **Multi-Channel Interaction** – CLI and web interfaces with real-time streaming via Server-Sent Events (SSE).\n* **Event-Oriented Pipeline** – Structured event flow for streaming, tool calls, and output routing. Components publish/subscribe to internal events; not a full message-broker-based event-driven system.\n* **Provider Abstraction** – Unified interface for multiple LLM providers where supported.\n\n---\n\n## AI Provider Integration\n\nFlexiAI Toolsmith supports multiple LLM providers through a unified interface.\n\nAdvanced Assistant API features (threads, runs, tool calls, streaming) are currently available for **OpenAI** and **Azure OpenAI**. Assistant API support enables structured tool calls, streaming execution, and deterministic workflows. Other providers are supported via chat-completions compatibility where applicable.\n\n| Provider               | Assistant API | Chat Completions | Notes                          |\n| ---------------------- | ------------- | ---------------- | ------------------------------ |\n| OpenAI                 | ✅             | ✅                | Threads, streaming, tool calls |\n| Azure OpenAI           | ✅             | ✅                | Threads, streaming, tool calls |\n| DeepSeek               | ❌             | ✅                | OpenAI SDK compatible          |\n| Qwen                   | ❌             | ✅                | OpenAI SDK compatible          |\n| GitHub Azure Inference | ❌             | ✅                | Azure AI SDK                   |\n\n---\n\n## Context-Aware Tool Orchestration\n\nFlexiAI Toolsmith enables assistants to combine model responses with structured context and deterministic tool execution.\n\nInstead of relying on unconstrained generation, assistants:\n\n* Build context from structured data sources\n* Invoke explicit tools via tool calls\n* Process results deterministically\n* Feed validated outputs back into the assistant workflow\n\nThe framework also includes **experimental support for multi-agent coordination**, where assistants can share context and delegate tasks in a controlled manner.\n\n---\n\n## Architecture Overview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"static/images/diagrams/FlexiAI%20Message%20Workflow-2026-01-22-113746.png\" alt=\"FlexiAI Message Workflow Diagram\" style=\"max-width: 100%; height: auto;\"\u003e\n\u003c/p\u003e\n\n**High-level message workflow** showing how user input flows through controllers, assistant execution, optional tool calls, and real-time streaming back to the user.\n\nFor detailed architecture documentation, execution workflows, and additional diagrams, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/WORKFLOW.md](docs/WORKFLOW.md).\n\n---\n\n## Built-in Tooling\n\nFlexiAI Toolsmith includes built-in tooling for:\n\n* **Data Processing** – CSV and spreadsheet operations (Excel/OpenPyXL)\n* **Business Workflows** – Subscriber management, customer service automation\n* **Security Analysis** – Network reconnaissance, process detection, port scanning, system updates\n* **External Integration** – YouTube search, external API helpers\n* **Experimental** – Multi-agent coordination, dynamic web forms, OCR utilities\n\nSee [docs/TOOLING.md](docs/TOOLING.md) for complete tool documentation and capabilities.\n\n---\n\n## Project Structure\n\n```text\n📦 flexiai-toolsmith\n ┣ 📂 flexiai\n ┃ ┣ 📂 agents              # Experimental multi-agent logic\n ┃ ┣ 📂 channels            # CLI, Quart SSE, Redis\n ┃ ┣ 📂 config              # Configuration \u0026 settings\n ┃ ┣ 📂 controllers         # CLI and web controllers\n ┃ ┣ 📂 core\n ┃ ┃ ┣ 📂 events            # Event models, bus, SSE manager\n ┃ ┃ ┗ 📂 handlers          # Thread manager, tool executor\n ┃ ┣ 📂 credentials         # Provider credentials\n ┃ ┣ 📂 database            # SQLAlchemy models (prepared)\n ┃ ┣ 📂 toolsmith           # Tool infrastructure\n ┃ ┗ 📂 utils               # Context utilities\n ┣ 📂 static                # Assets and diagrams\n ┣ 📂 templates             # Quart/Jinja templates\n ┣ 📂 logs                  # Application logs\n ┣ 📜 app.py                # Web entry point\n ┣ 📜 chat.py               # CLI entry point\n ┣ 📜 .env.template\n ┣ 📜 environment.yml\n ┣ 📜 requirements.txt\n ┣ 📜 Dockerfile\n```\n\n---\n\n## Prerequisites\n\n* Python 3.12+\n* Conda or `pip` + `venv`\n* **Optional system dependencies:**\n  * Tesseract OCR (for OCR features): `sudo apt-get install tesseract-ocr` (Linux) or `brew install tesseract` (macOS)\n  * Redis (only if using Redis channel): `sudo apt-get install redis-server` (Linux) or `brew install redis` (macOS)\n* OpenAI or Azure OpenAI assistant ID\n\n---\n\n## Installation\n\n```bash\ngit clone https://github.com/SavinRazvan/flexiai-toolsmith.git\ncd flexiai-toolsmith\n./setup_env.sh\n```\n\nCopy `.env.template` to `.env` and configure required variables.\n\n**Minimal `.env` example:**\n\n```env\nCREDENTIAL_TYPE=openai\nOPENAI_API_KEY=sk-your-api-key-here\nASSISTANT_ID=your_assistant_id_here\nUSER_ID=default_user\nACTIVE_CHANNELS=cli,quart\n```\n\n\u003e **Note:** See [docs/ENV_SETUP.md](docs/ENV_SETUP.md) for complete configuration options and provider-specific settings.\n\n---\n\n## Usage\n\n### CLI\n\n```bash\npython chat.py\n```\n\n**Example CLI Interface:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"static/images/demos/Security%20Advisor%201%20(CLI%20Chat).png\" alt=\"CLI Chat Example - Security Advisor\" style=\"max-width: 100%; height: auto; border: 1px solid #ddd; border-radius: 4px;\"\u003e\n\u003c/p\u003e\n\n**Quick Test:**\n```bash\npython chat.py\n# Expected output:\n# ======================================\n#          FlexiAI Chat Session         \n# ======================================\n# Type '/bye' or '/exit' to quit the conversation.\n#\n# 👤 You: hello\n# 🌺 Assistant: Hello! How can I assist you today?\n```\n\n\u003e **Troubleshooting:** If you see errors, verify `ASSISTANT_ID` and `OPENAI_API_KEY` are set correctly in your `.env` file.\n\n### Web (Quart + SSE)\n\n```bash\nhypercorn app:app --bind 127.0.0.1:8000 --workers 1\n```\n\nAccess:\n\n* `http://127.0.0.1:8000/` - Landing page\n* `http://127.0.0.1:8000/chat/` - Chat interface\n\n**Example Web Interface:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"static/images/demos/FlexiAI%20-%20WebChat%20-%20Security%201.png\" alt=\"Web Chat Example - Security Assistant\" style=\"max-width: 100%; height: auto; border: 1px solid #ddd; border-radius: 4px;\"\u003e\n\u003c/p\u003e\n\n**Quick Test:**\n1. Start the server: `hypercorn app:app --bind 127.0.0.1:8000 --workers 1`\n2. Open `http://127.0.0.1:8000/chat/` in your browser\n3. Send a message and observe real-time streaming responses (text should appear incrementally)\n\n\u003e **Troubleshooting:** If no streaming appears, verify `ASSISTANT_ID` and `OPENAI_API_KEY` are set correctly in your `.env` file.\n\n---\n\n## Documentation\n\n### Documentation Map\n\n**Getting Started:**\n- [docs/ENV_SETUP.md](docs/ENV_SETUP.md) – Environment setup and configuration\n- [SECURITY.md](SECURITY.md) – Security guidelines and safe usage practices\n\n**Understanding the System:**\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) – System structure, components, and responsibilities (what exists \u0026 who owns what)\n- [docs/WORKFLOW.md](docs/WORKFLOW.md) – Runtime behavior and execution paths (what happens when something runs)\n- [docs/TOOLING.md](docs/TOOLING.md) – Tool capabilities, safety, and contracts (what tools can do \u0026 how dangerous they are)\n\n**Development:**\n- [CONTRIBUTING.md](CONTRIBUTING.md) – Development guidelines and contribution process\n- [TESTING.md](TESTING.md) – Testing guide and mocking strategies\n- [docs/FILE_MAPPING.md](docs/FILE_MAPPING.md) – Internal file reference (for maintainers)\n\n### Quick Reference\n\n| Document | Purpose | When to Read |\n|----------|---------|--------------|\n| **ARCHITECTURE.md** | Structural model \u0026 component responsibilities | Understanding system design, component boundaries |\n| **WORKFLOW.md** | Runtime behavior \u0026 execution sequences | Tracing execution flow, debugging, understanding startup |\n| **TOOLING.md** | Tool capabilities, inputs/outputs, security | Using tools, understanding tool behavior, security concerns |\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, code style, and submission process.\n\n---\n\n## License\n\nReleased under the **MIT License**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavinrazvan%2Fflexiai-toolsmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsavinrazvan%2Fflexiai-toolsmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavinrazvan%2Fflexiai-toolsmith/lists"}