rsazure-openai-toolkit 0.4.0

Toolkit for fast and flexible integration with Azure OpenAI

---

rsazure-openai-toolkit

A lightweight, independent toolkit (with CLI support) to simplify and accelerate integration with Azure OpenAI.

---

📚 Contents

• Why This Project?
• Design Principles
• Key Features
• Security
• Requirements
• License
• Quick Start
• Manual Setup
• Usage
• Environment Configuration
• Logging & Usage Tracking
• Advanced Configuration (Optional)
• CLI Usage (rschat)
• Developer Tools (rschat-tools)
• Possible Issues
• Changelog
• About the Author
• Contact

---

❓ Why This Project?

There are many tools for interacting with OpenAI — but most are either too simplistic for real-world use, or too complex and tightly coupled to specific platforms.

This project was born out of the need for something in between:

• 🔍 Transparent and auditable — no magic, no vendor lock-in
• ⚙️ Flexible — can be used in scripts, production systems, or CI/CD pipelines
• 🧩 Modular — easy to extend or integrate with other workflows
• 🧠 Smart — includes retry logic, environment handling, and a developer-friendly CLI
• 🧪 Lightweight — zero dependencies beyond what’s needed, no bloat

Whether you're prototyping locally or running critical flows in production, this toolkit helps you do it faster, safer, and with full control.

Built by an engineer with real-world experience in AI, cloud, and software systems — to solve real developer problems.

---

🧠 Design Principles

These principles define how this toolkit is designed, maintained, and expected to be used — prioritizing security, clarity, and real-world applicability:

• Security first: No telemetry, no hidden dependencies, and full code transparency — always auditable and verifiable.
• Simplicity over complexity: A minimal, no-friction interface that works out-of-the-box without overwhelming configuration.
• Production-readiness: Built with reliability in mind — includes retry logic, CLI validation, and clear error handling.
• Explicit over implicit: All configurations are visible and controlled; no surprises behind the scenes.
• Extendable by design: Modular and adaptable for integration into larger systems and workflows.
• Developer & team friendly: Works great for individuals, but also for teams needing reproducibility and onboarding ease.

These principles are not just technical choices — they're part of a commitment to making this toolkit secure, stable, and genuinely useful in professional environments.

---

🚀 Key Features

This toolkit was designed with reliability and real-world use in mind:

• ✅ Modular architecture — easy to integrate and extend
• ✅ Intelligent retry mechanism with exponential backoff (via tenacity)
• ✅ Fully compatible with OpenAI-style request formats
• ✅ CLI-first design — includes rschat for terminal usage and rschat-tools for automation
• ✅ Secure by design — no telemetry, no external data sent
• ✅ Production-ready — suitable for professional, CI/CD-integrated environments
• ✅ Transparent logging — opt-in logging of all interactions with token usage and config
• ✅ Smart token tracking — includes input/output/total token count (with fallback)
• ✅ Reproducible outputs — seed-based generation for deterministic results
• ✅ Config utilities — reusable get_model_config() function to define model behavior

---

🔐 Security

Security is a core pillar of this project — not an afterthought.

• ✅ All code is fully open, auditable, and free from telemetry or tracking
• ✅ No data is ever sent externally — all logic executes locally and transparently
• ✅ Direct pushes and unreviewed merges are blocked by default via GitHub branch protection
• ✅ Releases are manually reviewed and published by the maintainer

If you discover any security vulnerabilities or have concerns:

• 📧 Please report privately to [e-mail]
• 🔍 See the full SECURITY policy on GitHub.

This project follows responsible disclosure practices. Thank you for helping keep the ecosystem secure.

---

📋 Requirements

• Python 3.9 or higher
• An active Azure OpenAI resource and deployment

---

📄 License

This project is open source and licensed under the MIT License, ensuring maximum flexibility and adoption.

You are free to use it in both personal and commercial projects.

---

🧪 Quick Start

⚠️ Requires Python 3.9+ and internet access. 📂 View setup scripts

Don't want to deal with virtual environments or manual setup?

Set up your environment with one command:

▶️ Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/renan-siqueira/rsazure-openai-toolkit/main/scripts/setup.ps1 | iex

🐧 Linux/macOS (Bash):

curl -sSfL https://raw.githubusercontent.com/renan-siqueira/rsazure-openai-toolkit/main/scripts/setup.sh | bash

This will:

• Create a virtual environment
• Activate it
• Install rsazure-openai-toolkit
• Print usage instructions

Ideal for both beginners and experienced developers 🚀

💬 Want to try it out quickly? Run rschat-tools samples after setup to see ready-to-run examples.

---

💻 Manual Setup (Alternative)

From PyPI:

pip install rsazure-openai-toolkit

From GitHub:

pip install git+https://github.com/renan-siqueira/rsazure-openai-toolkit

---

Usage

from rsazure_openai_toolkit import call_azure_openai_handler

response = call_azure_openai_handler(
    api_key="your-api-key",
    azure_endpoint="https://your-resource.openai.azure.com/",
    api_version="2023-12-01-preview",
    deployment_name="gpt-35-turbo",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize what artificial intelligence is."}
    ]
)

print(response)

---

Environment Configuration

To simplify local development and testing, this toolkit supports loading environment variables from a .env file.

Create a .env file in your project root (or copy the provided .env.example) and add your Azure OpenAI credentials:

AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2023-12-01-preview
AZURE_DEPLOYMENT_NAME=your-deployment-name

In your script, load the environment variables before calling the handler:

from dotenv import load_dotenv
import os

load_dotenv()  # defaults to loading from .env in the current directory

from rsazure_openai_toolkit import call_azure_openai_handler

response = call_azure_openai_handler(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    deployment_name=os.getenv("AZURE_DEPLOYMENT_NAME"),
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize what artificial intelligence is."}
    ]
)

---

📊 Logging and Usage Tracking

This toolkit gives you full control over logging behavior — by default, no logs are saved unless explicitly configured.

To enable logging:

RSCHAT_LOG_MODE=jsonl      # or csv
RSCHAT_LOG_PATH=~/.rsazure/chat_logs.jsonl

What gets logged:

• Prompt and response
• Token usage (input, output, total)
• Model used
• Seed (if any)
• Response time
• Raw API response
• Full model configuration

This helps with debugging, cost estimation, and auditability — without compromising privacy.

If you set RSCHAT_LOG_MODE=none or omit both variables, no logs will be generated — respecting user intent by design.

---

🔧 Advanced Configuration (Optional)

This toolkit provides a utility function called get_model_config() to help you explicitly configure OpenAI model behavior — in a way that is transparent, reproducible, and easy to override.

It returns a dictionary of model parameters that can be passed directly into the call_azure_openai_handler.

✅ Benefits:

• Clear defaults for fast iteration
• Full support for OpenAI parameters
• Reproducible generation with optional seed
• Easy to override only what you need

🔍 Supported Parameters

Parameter	Description
temperature	Controls randomness (0.0 = deterministic, 1.0 = more creative)
max_tokens	Maximum number of tokens to generate
seed	Makes generation deterministic for same input (if supported by model)
top_p	Controls diversity via nucleus sampling
frequency_penalty	Penalizes repetition
presence_penalty	Encourages introduction of new topics
stop	Sequence(s) to stop generation (e.g., "\nUser:")
user	Optional user identifier (e.g., "rschat-cli")
logit_bias	Bias certain tokens (e.g., {token_id: -100} to suppress a token)

---

⚙️ Default Configuration

If you call get_model_config() with no arguments, you get:

from rsazure_openai_toolkit.utils.model_config_utils import get_model_config

model_config = get_model_config()

# Returns:
# {
#     "temperature": 0.7,
#     "max_tokens": 1024,
#     "seed": 1
# }

This ensures a balance of creativity, length, and reproducibility.

---

🧩 Custom Overrides

You can selectively override any parameter using the overrides argument:

# Adjust temperature and disable seed for non-deterministic behavior
config = get_model_config(overrides={"temperature": 0.5}, seed=None)

# Set a custom top_p and seed
config = get_model_config(overrides={"top_p": 0.9}, seed=42)

# Completely override everything
config = get_model_config(overrides={
    "temperature": 0.2,
    "max_tokens": 512,
    "seed": 123,
    "frequency_penalty": 0.5
})

If seed is provided as both an argument and inside overrides, the override takes precedence:

get_model_config(overrides={"seed": 99}, seed=1)  # → uses seed=99

---

🔄 Why This Matters

In production scenarios, controlling model behavior explicitly improves:

• Cost and token budgeting
• Debugging and reproducibility
• Output consistency for testing and evaluation

You’re always in control — no hidden defaults.

---

💡 This function powers the CLI (rschat) under the hood, and you can reuse it in your own apps or pipelines.

---

💻 CLI Usage (rschat)

After installing the package, you can interact with Azure OpenAI directly from your terminal using:

rschat "What can you do for me?"

Make sure you have a valid .env file with your Azure credentials configured:

AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2023-12-01-preview
AZURE_DEPLOYMENT_NAME=your-deployment-name

You can also ask in Portuguese (or any supported language):

rschat "Resuma o que é inteligência artificial"

If any required variable is missing, the CLI will exit with a clear error message.

📝 Logging with CLI

To enable logging while using the CLI:

RSCHAT_LOG_MODE=jsonl
RSCHAT_LOG_PATH=~/.rsazure/chat_logs.jsonl

This will record your interactions, including prompt, response, token usage, seed, and full configuration.

To disable logging:

RSCHAT_LOG_MODE=none
# Or omit RSCHAT_LOG_MODE and RSCHAT_LOG_PATH variables

---

🧰 Developer Tools (rschat-tools)

The toolkit includes a companion CLI called rschat-tools to assist with setup and onboarding.

To generate sample projects in your current directory, run:

rschat-tools samples

You'll see an interactive menu like this:

[0] Exit
[1] Basic Usage
[2] Advanced Usage
[3] Env Usage
[4] Env + Advanced Usage
[all] Generate All

Choose an option, and a folder will be created inside ./samples/ containing ready-to-run scripts and configurations.

💡 Samples that include a chat loop will clearly display: Type 'exit' to quit
This ensures the CLI is friendly even for non-developers who might not be familiar with Ctrl+C.

You can generate all examples at once using:

rschat-tools samples
# then select: all

This is the fastest way to explore real usage examples and start integrating Azure OpenAI with minimal setup.

---

🚨 Possible Issues

• Invalid API Key or Endpoint
  Ensure your AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT are correctly set in your .env file.

• Deployment Not Found
  Check that your deployment_name matches exactly the name defined in your Azure OpenAI resource.

• Timeouts or 5xx Errors
  The toolkit includes automatic retries with exponential backoff via tenacity. If errors persist, verify network access or Azure service status.

• Missing Environment Variables
  Always ensure load_dotenv() is called before accessing os.getenv(...), especially when testing locally.

---

📦 Changelog

We follow semantic versioning to ensure predictable upgrades.

• 🔎 Check the full CHANGELOG.md for detailed release notes
• 📌 Visit the Releases Page to explore version history

---

👨‍💻 About the Author

I'm a software engineer with real-world experience across backend, frontend, DevOps, cloud, and AI — building solutions that are designed to last.

Today, my passion is helping teams make AI development more accessible, maintainable, and truly production-ready — with full control, transparency, and respect for sound engineering principles.

I believe that great tools should be simple, powerful, and built to empower — not to lock people in. That’s the mindset behind everything I build and share.

---

📬 Contact

I'm always open to feedback, ideas, or professional collaboration.

• GitHub: github.com/renan-siqueira
• Email: [e-mail]
• LinkedIn: linkedin.com/in/renan-siqueira-antonio

Feel free to connect or open an issue.
Suggestions, contributions, and responsible disclosures are always welcome.