https://github.com/savinrazvan/flexiai-toolsmith

Python framework for building AI Agents -> CLI & Quart-SSE UIs, Toolsmith RAG plug-ins, full Assistant-API workflows via the OpenAI SDK (OpenAI / Azure today). Support for DeepSeek & Qwen is pending Assistant endpoint access.
https://github.com/savinrazvan/flexiai-toolsmith

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

Last synced: 2 months ago
JSON representation

Host: GitHub
URL: https://github.com/savinrazvan/flexiai-toolsmith
Owner: SavinRazvan
License: mit
Created: 2025-05-17T08:26:02.000Z (12 months ago)
Default Branch: main
Last Pushed: 2025-06-08T16:40:01.000Z (11 months ago)
Last Synced: 2025-06-08T17:30:02.667Z (11 months ago)
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
Language: Python
Homepage:
Size: 1.17 MB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

          # FlexiAI Toolsmith

[![Python >=3.12](https://img.shields.io/badge/python-3.12+-darkblue.svg)](https://www.python.org/downloads/)

[![License: MIT](https://img.shields.io/badge/License-MIT-darkgreen.svg)](https://opensource.org/licenses/MIT)

**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.

The 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.

FlexiAI Toolsmith was designed as a reusable foundation and has been used to build multiple applied systems, including:

* **Alina Assistant** – a customer service automation system handling identification, validation, and subscription workflows.

* **Security analysis agents** that perform structured configuration checks and inspections through controlled, tool-driven execution.

The project emphasizes clarity of architecture, modular design, and real-world usability rather than experimentation or model benchmarking.

---

## Key Characteristics

* **Modular Architecture** – Clear separation between orchestration, tools, channels, and providers.

* **Tool-Driven AI** – Assistants invoke structured tools via explicit tool calls instead of relying on free-form responses.

* **Context-Aware Workflows** – Structured context is injected into assistant interactions to ensure grounded behavior.

* **Multi-Channel Interaction** – CLI and web interfaces with real-time streaming via Server-Sent Events (SSE).

* **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.

* **Provider Abstraction** – Unified interface for multiple LLM providers where supported.

---

## AI Provider Integration

FlexiAI Toolsmith supports multiple LLM providers through a unified interface.

Advanced 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.

| Provider               | Assistant API | Chat Completions | Notes                          |

| ---------------------- | ------------- | ---------------- | ------------------------------ |

| OpenAI                 | ✅             | ✅                | Threads, streaming, tool calls |

| Azure OpenAI           | ✅             | ✅                | Threads, streaming, tool calls |

| DeepSeek               | ❌             | ✅                | OpenAI SDK compatible          |

| Qwen                   | ❌             | ✅                | OpenAI SDK compatible          |

| GitHub Azure Inference | ❌             | ✅                | Azure AI SDK                   |

---

## Context-Aware Tool Orchestration

FlexiAI Toolsmith enables assistants to combine model responses with structured context and deterministic tool execution.

Instead of relying on unconstrained generation, assistants:

* Build context from structured data sources

* Invoke explicit tools via tool calls

* Process results deterministically

* Feed validated outputs back into the assistant workflow

The framework also includes **experimental support for multi-agent coordination**, where assistants can share context and delegate tasks in a controlled manner.

---

## Architecture Overview



  



**High-level message workflow** showing how user input flows through controllers, assistant execution, optional tool calls, and real-time streaming back to the user.

For detailed architecture documentation, execution workflows, and additional diagrams, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/WORKFLOW.md](docs/WORKFLOW.md).

---

## Built-in Tooling

FlexiAI Toolsmith includes built-in tooling for:

* **Data Processing** – CSV and spreadsheet operations (Excel/OpenPyXL)

* **Business Workflows** – Subscriber management, customer service automation

* **Security Analysis** – Network reconnaissance, process detection, port scanning, system updates

* **External Integration** – YouTube search, external API helpers

* **Experimental** – Multi-agent coordination, dynamic web forms, OCR utilities

See [docs/TOOLING.md](docs/TOOLING.md) for complete tool documentation and capabilities.

---

## Project Structure

```text

📦 flexiai-toolsmith

 ┣ 📂 flexiai

 ┃ ┣ 📂 agents              # Experimental multi-agent logic

 ┃ ┣ 📂 channels            # CLI, Quart SSE, Redis

 ┃ ┣ 📂 config              # Configuration & settings

 ┃ ┣ 📂 controllers         # CLI and web controllers

 ┃ ┣ 📂 core

 ┃ ┃ ┣ 📂 events            # Event models, bus, SSE manager

 ┃ ┃ ┗ 📂 handlers          # Thread manager, tool executor

 ┃ ┣ 📂 credentials         # Provider credentials

 ┃ ┣ 📂 database            # SQLAlchemy models (prepared)

 ┃ ┣ 📂 toolsmith           # Tool infrastructure

 ┃ ┗ 📂 utils               # Context utilities

 ┣ 📂 static                # Assets and diagrams

 ┣ 📂 templates             # Quart/Jinja templates

 ┣ 📂 logs                  # Application logs

 ┣ 📜 app.py                # Web entry point

 ┣ 📜 chat.py               # CLI entry point

 ┣ 📜 .env.template

 ┣ 📜 environment.yml

 ┣ 📜 requirements.txt

 ┣ 📜 Dockerfile

```

---

## Prerequisites

* Python 3.12+

* Conda or `pip` + `venv`

* **Optional system dependencies:**

  * Tesseract OCR (for OCR features): `sudo apt-get install tesseract-ocr` (Linux) or `brew install tesseract` (macOS)

  * Redis (only if using Redis channel): `sudo apt-get install redis-server` (Linux) or `brew install redis` (macOS)

* OpenAI or Azure OpenAI assistant ID

---

## Installation

```bash

git clone https://github.com/SavinRazvan/flexiai-toolsmith.git

cd flexiai-toolsmith

./setup_env.sh

```

Copy `.env.template` to `.env` and configure required variables.

**Minimal `.env` example:**

```env

CREDENTIAL_TYPE=openai

OPENAI_API_KEY=sk-your-api-key-here

ASSISTANT_ID=your_assistant_id_here

USER_ID=default_user

ACTIVE_CHANNELS=cli,quart

```

> **Note:** See [docs/ENV_SETUP.md](docs/ENV_SETUP.md) for complete configuration options and provider-specific settings.

---

## Usage

### CLI

```bash

python chat.py

```

**Example CLI Interface:**



  



**Quick Test:**

```bash

python chat.py

# Expected output:

# ======================================

#          FlexiAI Chat Session         

# ======================================

# Type '/bye' or '/exit' to quit the conversation.

#

# 👤 You: hello

# 🌺 Assistant: Hello! How can I assist you today?

```

> **Troubleshooting:** If you see errors, verify `ASSISTANT_ID` and `OPENAI_API_KEY` are set correctly in your `.env` file.

### Web (Quart + SSE)

```bash

hypercorn app:app --bind 127.0.0.1:8000 --workers 1

```

Access:

* `http://127.0.0.1:8000/` - Landing page

* `http://127.0.0.1:8000/chat/` - Chat interface

**Example Web Interface:**



  



**Quick Test:**

1. Start the server: `hypercorn app:app --bind 127.0.0.1:8000 --workers 1`

2. Open `http://127.0.0.1:8000/chat/` in your browser

3. Send a message and observe real-time streaming responses (text should appear incrementally)

> **Troubleshooting:** If no streaming appears, verify `ASSISTANT_ID` and `OPENAI_API_KEY` are set correctly in your `.env` file.

---

## Documentation

### Documentation Map

**Getting Started:**

- [docs/ENV_SETUP.md](docs/ENV_SETUP.md) – Environment setup and configuration

- [SECURITY.md](SECURITY.md) – Security guidelines and safe usage practices

**Understanding the System:**

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) – System structure, components, and responsibilities (what exists & who owns what)

- [docs/WORKFLOW.md](docs/WORKFLOW.md) – Runtime behavior and execution paths (what happens when something runs)

- [docs/TOOLING.md](docs/TOOLING.md) – Tool capabilities, safety, and contracts (what tools can do & how dangerous they are)

**Development:**

- [CONTRIBUTING.md](CONTRIBUTING.md) – Development guidelines and contribution process

- [TESTING.md](TESTING.md) – Testing guide and mocking strategies

- [docs/FILE_MAPPING.md](docs/FILE_MAPPING.md) – Internal file reference (for maintainers)

### Quick Reference

| Document | Purpose | When to Read |

|----------|---------|--------------|

| **ARCHITECTURE.md** | Structural model & component responsibilities | Understanding system design, component boundaries |

| **WORKFLOW.md** | Runtime behavior & execution sequences | Tracing execution flow, debugging, understanding startup |

| **TOOLING.md** | Tool capabilities, inputs/outputs, security | Using tools, understanding tool behavior, security concerns |

---

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, code style, and submission process.

---

## License

Released under the **MIT License**.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/savinrazvan/flexiai-toolsmith

Awesome Lists containing this project

README