Introduction

Most AI applications today rely on Large Language Models (LLMs) to generate responses, summarize documents, or reason through complex problems. But what happens when your application doesn’t need a paragraph of generated text?

What if all you need is to:

• Determine whether a contract requires written notice.
• Classify an HR complaint into a predefined category.
• Evaluate the risk associated with a contractual clause.
• Prioritize an incoming sales lead.
• Make a structured decision that another application can consume.

Traditional generative LLMs can accomplish these tasks, but often with unnecessary output generation and additional parsing.

Microsoft Decision-1 takes a different approach.

Announced in October 2026, Microsoft Decision-1 is a specialized decision model available in Microsoft Foundry. Built on the open-weight Qwen3.5–9B base model, it focuses on classification, scoring, and binary decisions rather than generating long-form responses.

The model follows a System One approach: making focused, structured judgments from supplied information.

In this tutorial, we’ll deploy the model through Microsoft Foundry and use Python to explore its three primary decision types:

1. Noul—Binary decisions with probabilities.
2. Choice—Classification into predefined categories.
3. Score—Evaluation using an ordered scoring rubric.

We’ll use examples drawn from three enterprise functions: legal, human resources, and marketing.

Complete source code and Jupyter notebooks:

https://github.com/scholarly360/Microsoft-Decision-1-on-Microsoft-Foundry

1. Understanding Microsoft Decision-1

The key difference between a generative LLM and a decision model is the type of output.

Consider the question:

“Does this contract require advance written notice for termination?”

A generative LLM might produce:

Yes. Based on the termination clause, the Customer must provide 30 days’ written notice before terminating the agreement for convenience.

Microsoft Decision-1 can instead return a probability:

0.9972

Your application can interpret this numerical result according to predefined business rules.

This is particularly useful in enterprise systems where applications need predictable output structures rather than generated explanations.

Let’s explore these capabilities using Python.

2. Deploy Microsoft Decision-1 on Microsoft Foundry

Before we write code, we need to deploy the model.

Open Microsoft Foundry:

https://ai.azure.com

Inside your Foundry project:

1. Open the model catalog.
2. Search for Microsoft-Decision-1.
3. Select the model and deploy it using an available deployment option.
4. Record the deployment name, endpoint URL, and API key.

For this tutorial, we’ll use the deployment name:

Decision-1

The endpoint used in the accompanying notebooks follows this structure:

https://<your-resource>.services.ai.azure.com/providers/microsoft

Use the exact endpoint provided by your deployment.

Set up the Python environment.

Start by cloning the repository:

git clone https://github.com/scholarly360/Microsoft-Decision-1-on-Microsoft-Foundry.git

cd Microsoft-Decision-1-on-Microsoft-Foundry

Create a virtual environment:

python -m venv .venv

Activate it on Windows:

.venv\Scripts\activate

Or on macOS/Linux:

source .venv/bin/activate

Install the dependencies:

pip install -r requirements.txt

The repository includes the following packages:

typesafe-sdk
python-dotenv
ipykernel

Configure credentials.

Create a .env file using the provided sample.env template.

api_key=YOUR_FOUNDRY_API_KEY
endpoint=https://YOUR_RESOURCE.services.ai.azure.com/providers/microsoft

Import the SDK

import os
from dotenv import load_dotenv
from typesafe_sdk import (
    TypeSafeClient,
    Noul,
    Choice,
    Score
)
load_dotenv()
api_key = os.getenv("api_key")
endpoint = os.getenv("endpoint")
deployment_name = "Decision-1"

Now let’s create a simple helper function to reuse across our examples.

def decide(state, questions):
    with TypeSafeClient(
        api_key=api_key,
        base_url=endpoint,
        model=deployment_name,
        timeout=60
    ) as client:
      response = client.system_one(
            state=state,
            questions=questions
        )
    return response.answers

This wrapper handles the connection to Microsoft Foundry and returns the structured decisions.

Notice two important arguments:

• state: The text or structured input the model evaluates.
• questions: A dictionary containing the decisions the model must make.

Now we’re ready to experiment.

3. Example 1: Legal Contract Analysis Using Noul

Let’s begin with a legal contract.

Consider this termination clause:

contract_clause = """
12. TERMINATION The Customer may terminate this Agreement for
convenience by providing thirty (30) days'
prior written notice.
The Supplier may terminate this Agreement only
if the Customer fails to pay undisputed
invoices within fifteen (15) days after
receiving written notice of non-payment.
"""

Does the Customer have to provide advance written notice before termination?

This is a binary decision, making Noul an appropriate option.

Python implementation

answers = decide(
    state=contract_clause,
    questions={
        "notice_requirement": Noul(
            instructions=(
                "Is the Customer required to provide "
                "advance written notice before termination?"
            )
        )
    }
)
result = answers["notice_requirement"]
print(f"Probability: {result.noul:.2%}")

Output

Probability: 99.72%

The noul property represents the model's estimated probability that the answer to our question is true.

A value approaching 1 indicates strong model support for the proposition. A value approaching 0 indicates support for the opposite.

Applying business rules

The numerical output can be incorporated directly into application logic.

For example:

probability = result.noul

if probability >= 0.90:
    decision = "Written notice requirement detected"
elif probability <= 0.10:
    decision = "Written notice requirement not detected"
else:
    decision = "Requires manual review"

print(decision)

These thresholds are illustrative. In production, they should be selected using representative evaluation data and the consequences of incorrect decisions.

This is the first practical advantage of a decision model.

Instead of asking an application to parse a generated paragraph, we can directly consume a typed numerical output.

4. Example 2: Contract Classification Using Choice

Let’s extend the same legal scenario.

Our contract allows the Customer to terminate for convenience, while the Supplier has a narrower termination right tied to non-payment.

We now want to identify:

Which party has termination-for-convenience rights?

The valid categories are:

• Both parties
• Customer only
• Supplier only
• Neither party

This is a classification problem.

Python implementation

answers = decide(
    state=contract_clause,
    questions={
        "termination_rights": Choice(
            instructions=(
                "Classify the parties' termination-for-"
                "convenience rights under this contract."
            ),
            criteria={
                "mutual": (
                    "Both parties can terminate "
                    "for convenience"
                ),
                "customer_only": (
                    "Only the Customer can terminate "
                    "for convenience"
                ),
                "supplier_only": (
                    "Only the Supplier can terminate "
                    "for convenience"
                ),
                "neither": (
                    "Neither party can terminate "
                    "for convenience"
                )
            }
        )
    }
)
result = answers["termination_rights"]
print("Selected category:", result.choice)
print("Confidence:", result.confidence)
print("Probabilities:", result.probabilities)

Output

Selected category: customer_only
Confidence: 0.998947

The returned probabilities were approximately:

{
    "customer_only": 0.999210,
    "mutual": 0.000123,
    "supplier_only": 0.000040,
    "neither": 0.000626
}

Understanding Choice

Unlike Noul, which evaluates a proposition, Choice selects from a predefined set of categories.

The criteria dictionary provides the available labels and their descriptions.

The response includes:

• choice: The selected classification.
• confidence: A confidence measure for the decision.
• probabilities: The model's probability distribution across the available categories.

For enterprise applications, this is useful for contract classification, support ticket routing, document categorization, and workflow selection.

One important consideration: Choice selects from the supplied options. If a classification problem requires an "unknown" or "insufficient information" outcome, design the categories and review process accordingly rather than forcing every input into an unsuitable business label.

5. Example 3: Contract Risk Assessment Using Score

Binary decisions and classifications are useful, but many enterprise workflows require a more nuanced assessment.

For example:

How risky is this termination clause for the Supplier?

The answer is not simply Yes or No.

We need an ordered risk rubric.

Microsoft Decision-1 provides the Score decision type for this requirement.

Python implementation

answers = decide(
    state=contract_clause,
    questions={
        "termination_risk": Score(
            instructions=(
                "Assess the contractual risk to the "
                "Supplier arising from asymmetric "
                "termination rights."
            ),
            criteria=[
                "Very low: Both parties have equal "
                "termination rights",
                "Low: Minor differences in "
                "termination rights",
                "Moderate: Some imbalance in "
                "termination rights",
                "High: One party has significantly "
                "more termination rights",
                "Critical: One party has unrestricted "
                "termination rights with severe "
                "consequences"
            ]
        )
    }
)
result = answers["termination_risk"]
print("Risk score:", result.score)
print("Confidence:", result.confidence)
print("Risk levels:", result.legend)
print("Probabilities:", result.probabilities)

Output

Risk score: 3.0568
Confidence: 0.8652

The highest probability was associated with level 3:

3: High — One party has significantly
more termination rights

How does the score work?

With five criteria, the model evaluates levels indexed from 0 through 4.

The returned numerical score is a probability-weighted value across these levels, so it does not have to be an integer.

For example, a score 3.0568 is close to the high-risk level, but the full probability distribution provides a more informative representation.

We can also extract the most probable risk category:

most_likely_level = max(
    result.probabilities,
    key=result.probabilities.get
)
risk_description = result.legend[most_likely_level]
print("Most likely level:", most_likely_level)
print("Risk description:", risk_description)

This provides a clear separation between the model’s numerical score and its most likely category.

For an actual contract management system, the assessment should be treated as a triage signal, not a definitive legal conclusion.

6. Combining Multiple Decisions in One API Call

We can request multiple decisions about the same input in a single call.

Instead of invoking the model three times, we can combine related questions.

answers = decide(
    state=contract_clause,
    questions={
        "notice_requirement": Noul(
            instructions=(
                "Is the Customer required to provide "
                "advance written notice before termination?"
            )
        ),
"termination_rights": Choice(
            instructions=(
                "Which party has termination-for-"
                "convenience rights?"
            ),
            criteria={
                "mutual": "Both parties",
                "customer_only": "Customer only",
                "supplier_only": "Supplier only",
                "neither": "Neither party"
            }
        ),
        "termination_risk": Score(
            instructions=(
                "Evaluate termination-rights risk "
                "from the Supplier's perspective."
            ),
            criteria=[
                "Very low: Equal rights",
                "Low: Minor imbalance",
                "Moderate: Some imbalance",
                "High: Significant imbalance",
                "Critical: Severe imbalance"
            ]
        )
    }
)

We can then extract the individual results:

notice_probability = (
    answers["notice_requirement"].noul
)
termination_category = (
    answers["termination_rights"].choice
)
risk_score = (
    answers["termination_risk"].score
)
print("Notice probability:", notice_probability)
print("Termination category:", termination_category)
print("Risk score:", risk_score)

Combining related decisions reduces separate API requests and allows all questions to share the same input context.

For document-intelligence systems that evaluate multiple attributes of a contract, this can be particularly useful.

Before deploying such a workflow into production:

1. Evaluate against labeled data. Test using representative examples, ambiguous inputs, and edge cases.

2. Validate thresholds. Do not assume a model probability is perfectly calibrated for your business process.

3. Include human review. Particularly for HR complaints, legal risk, and other consequential workflows.

4. Design your criteria carefully. A useful classification or scoring system depends heavily on clear labels, mutually understandable categories, and well-defined rubrics.

5. Monitor outcomes. Track classification errors, latency, cost, and how outputs change as your input data evolves.

7. Download the Complete Jupyter Notebooks

I’ve put together three hands-on notebooks demonstrating the decision types across different enterprise scenarios.

Each notebook includes Python code for the three decision types, with the examples structured for experimentation against a Microsoft Foundry deployment.

GitHub Repository:

https://github.com/scholarly360/Microsoft-Decision-1-on-Microsoft-Foundry

The project is open source under the Apache 2.0 license.

Final Thoughts

As AI systems become more integrated into enterprise workflows, we need to think beyond using generative LLMs for every operation.

Some tasks require reasoning and natural language generation. Others require repeatable, bounded decisions that downstream software can consume directly.

Microsoft Decision-1 is an interesting example of the latter approach.

With just three decision types—Noul, Choice, and Score—developers can experiment with binary evaluations, classification, and ordered scoring in a consistent API.

The important architectural question is no longer simply

Which LLM should I use?

It is also:

Does this step need a generative model at all, or would a specialized decision model be a better fit?

Enterprise AI developers should explore the distinction between using a generative model and a specialized decision model for building classification pipelines, agent routing, contract analytics, or operational workflows.

If you find the examples useful, consider starring the GitHub repository or contributing additional use cases.

References

• Microsoft Decision-1 Model Catalog
• Microsoft Foundry Decision-1 Documentation
• TypeSafe Python SDK
• Complete GitHub Repository

Demystifying the Claude Mod

Claude mods are a way to customize Claude Code, Anthropic’s coding tool. They are small TypeScript functions that change how Claude Code works. Anthropic announced them on October 1, 2026.

In this Medium article, we will build a mod/plugin that explores architecture from an existing directory.

Demystifying the Claude Mod Architecture Tree

How to build smarter, modular AI systems without the headache.

Have you ever tried to give an AI a massive task, only to watch it get confused halfway through? We have all been there. As we push tools like Claude Code to handle complex software engineering, throwing everything into one giant prompt no longer works.

Enter the Claude Mod Architecture Tree.

The GitHub repository scholarly360/claude-mod-architecture-tree offers a brilliant framework for solving this exact problem. But what exactly is it? Let us break it down into plain English.

Think of It Like a Real Tree

Imagine a large corporation. The CEO does not personally handle payroll, marketing, and fixing the office printer. They delegate. The Claude Mod Architecture Tree applies this same logic to your AI workflow.

Instead of a single brain trying to juggle every part of your codebase, the architecture splits responsibilities into a hierarchical structure:

• The Root (Core Identity): This is your main configuration. It sets the baseline rules, project context, and overarching goals.
• The Branches (Modules): These are specialized task managers or sub-agents. One branch might handle database operations, while another focuses strictly on user interface design.
• The Leaves (Tools and Skills): These are the highly specific actions your AI can take, such as reading a file, running a shell script, or formatting code.

Why Do We Need This?

When you build a system using a modular architecture tree, you gain three massive benefits:

1. Laser Focus: Because tasks are separated into branches, the AI does not get overwhelmed by unrelated information. A database module only looks at database code.
2. Easy Updates: If you need to change how your app handles security, you do not have to rewrite your entire AI system. You just update the specific security leaf or branch.
3. Fewer Hallucinations: By restricting what each module can see and do, you dramatically reduce the chances of the AI making things up or hallucinating incorrect code.

How It Works Under the Hood

In practical terms, this repository emphasizes a few core technical concepts made simple for developers:

1. Modular Context Instead of feeding Claude an entire textbook of code at once, the system uses targeted context. It relies on specific files to guide behavior only in the relevant areas of your project.

2. Sub-Agent Orchestration When a big task comes in, the root system breaks it down and hands the pieces to smaller, specialized AI agents. Once the sub-agents finish their specialized tasks, they report back up the chain.

3. Clear Boundaries The tree structure prevents different parts of the AI from stepping on each other’s toes. It creates a clean, predictable workflow where every component knows its exact job.

This is a small Claude Code plugin (a “mod”) that automatically gets Claude to draw your project’s architecture as a text tree whenever you ask an architecture-style question. It’s version 0.1.0, public, and has no stars or forks yet.

The plugin hooks into the prompt.submit event, which fires when you send a prompt in Claude Code. It checks your prompt for architecture-related language. If it finds some, it does two things:

1. It shows a toast saying “Architecture words found: asking for a mindmap”.
2. It quietly attaches a hidden instruction to the prompt. The instruction tells Claude to read the actual repo and also produce a box-drawing tree of the system architecture in a code block, plus a couple of sentences of notes.

Your own prompt text isn’t modified. Only Claude’s instructions are extended. It also only applies to prompts a person actually typed (or sent via an app/SDK). Relayed messages from plugins, peers or notifications pass through untouched.

What triggers it

The detection logic lives in hooks/register.ts and matches two kinds of language:

• Architecture words that trigger on their own: architecture, tech stack, microservice, monolith, data flow, system overview, project structure, and phrasings like "how is this structured".
• “Design” next to a software word: “design” alone is ambiguous, since it could mean UI or fashion. So it only counts when paired with words like system, api, database, schema, service or pattern, in either order. "Database design" and "design patterns" both match.

Opt-out: adding phrases like “no diagram”, “without a mindmap” or “skip mermaid” disables it. The opt-out only recognizes diagram, mindmap, mind map and mermaid, so "skip the tree" would not work.

my-app
├── Entry points
│   ├── src/server.ts
│   └── src/cli.ts
├── Core modules
│   ├── router
│   └── services
└── Data and storage
    ├── Postgres
    └── Redis cache

Getting Started

You do not need a PhD in computer science to appreciate modular design. By adopting the principles found in the claude-mod-architecture-tree repository, you can start treating your AI assistants less like magic eight balls and more like structured, reliable engineering teams.

Next time you are building a complex project with Claude, ask yourself: are you building a tangled web, or are you growing a healthy tree.

GitHub Link

https://github.com/scholarly360/claude-mod-architecture-tree

YouTube Video

Introduction

In the modern enterprise landscape, teams are constantly churning out content, especially PPTX. Turning vast amounts of raw text and data into polished, brand-compliant PowerPoint presentations is often a tedious, manual bottleneck. But what if you could automate this process entirely in the background.

In a recent experiments I tried to a practical look at how to build a continuous “churning machine” for PowerPoint presentations using Claude, Microsoft Foundry, and OfficeCLI.

Here is a breakdown of how this automated document-generation pipeline works and how you can replicate it using the companion GitHub repository.

The Core Technology Stack

To build this programmatic presentation generator, the workflow relies on a few key components:

• Microsoft Foundry: Acts as the hosting platform for the Claude models (such as Claude 4.5 Haiku and Claude 4.6 Sonnet), functioning similarly to AWS Bedrock but within the Azure ecosystem.
• Claude Agent SDK: The orchestrator of the operation. It allows the Claude AI to interact programmatically with predefined “skills” or tools to execute complex tasks.
• OfficeCLI: A purpose-built command-line tool and agent skill designed to read, create, and crucially verify Microsoft Office documents (like .pptx and .docx).

How the Automated Pipeline Works

The goal of the workflow is to take raw text, apply corporate branding, and output a verifiable PowerPoint document without human intervention. Here is the step-by-step execution:

1. Authentication and Setup

The system requires access to the Claude models hosted on Microsoft Foundry. By utilizing the Azure CLI (az login), the environment authenticates and connects to the Foundry endpoint securely.

2. Defining “Skills” for the AI

Instead of just asking an LLM to write text, the Claude Agent SDK is equipped with two specific local skills in this testbed:

• The office-cli Skill: Gives Claude the ability to programmatically draft and save a .pptx file.
• The brand-guideline Skill: A crucial addition for enterprises. The acts as a strict guardrail (e.g., for a fictitious company named "Acme CRM"), ensuring the generated slides use the correct corporate fonts, layout structures, and color palettes.

3. Processing the Content

The user provides a simple raw text document (content.txt) containing the baseline information about Acme CRM.

4. Generation and Verification

By running a simple Python script, the Claude Agent SDK takes over. It reads the raw text, consults the brand guidelines skill to understand the aesthetic requirements, and then invokes the OfficeCLI. In just a few minutes, it generates a complete, properly formatted two-slide PowerPoint presentation directly into the local directory.

Hands-On: The GitHub Testbed

To allow developers to experiment with this architecture, all the code used in the demonstration is open-sourced in the following repository:

scholarly360/office-cli-claude-agent-sdk.

This repository serves as a lightweight testbed for exercising OfficeCLI through the Claude Agent SDK. If you want to build upon this workflow, the repo includes:

• test-officecli.py main Python execution script that initializes the Claude client and sends the prompt.
• /skills directory: Contains the definitions for the office-cli and brand-guideline skills so you can see exactly how to constrain the AI's output.
• sample.env: Environment variables template to easily plug in your Microsoft Foundry endpoints and API keys.
• content.txt: The sample data file used to generate the slides.

Why This Matters

This architecture shifts AI from being a simple conversational assistant to a background enterprise worker. By decoupling the content from the design (via the brand guideline skill) and using a tool like OfficeCLI to handle the actual file generation, organizations can build continuous pipelines that automatically convert daily reports, data dumps, or meeting transcripts into presentation-ready decks.

Want to try it yourself? Clone the GitHub repository and connect it to your Microsoft Foundry environment to see automated slide generation in action.

Introduction

As enterprise AI strategies mature, organizations are moving beyond standard out-of-the-box APIs and shifting toward hosting, fine-tuning, and managing open-source and custom models. Google Cloud’s Gemini Enterprise Agent Platform (formerly Vertex AI) provides a robust foundation for these tasks. Within this ecosystem, the Model Garden SDK offers a clean, programmatic way for developers to browse, configure, and provision production-ready endpoints for open-weight models like Google’s Gemma 3.

This small Medium guide provides a practical walkthrough for programmatically deploying a model from Hugging Face or Google’s open-source repository directly onto a managed Google Cloud GPU instance using the Vertex AI Model Garden SDK.

Prerequisites

Before diving into the Python environment, ensure you have the following prerequisites configured:

1. Python 3.x installed locally or in your development environment.
2. Google Cloud CLI (gcloud) installed and initialized.
3. A Google Cloud Project with the Vertex AI (Gemini Enterprise Agent Platform) API enabled.
4. An environment configuration file (.env) in your root directory containing your project coordinates:

GOOGLE_CLOUD_PROJECT_ID=your-project-id
GOOGLE_CLOUD_REGION=us-central1

Step 1: Authentication and Setup

To allow your local script or Jupyter notebook to provision infrastructure on GCP, initialize your Application Default Credentials (ADC) via the terminal:

gcloud auth application-default login

Next, install the required Python dependencies. We will need the official Google Cloud AI Platform library along with python-dotenv securely managing our environment variables.

pip install google-cloud-aiplatform python-dotenv

Step 2: Initialize Vertex AI

With the environment ready, read your variables and initialize the Vertex AI SDK. This configures the global context for your deployment target.

import os
import vertexai
from dotenv import load_dotenv
from vertexai import model_garden

# Load project credentials
load_dotenv()
PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT_ID")
LOCATION = os.environ.get("GOOGLE_CLOUD_REGION", "us-central1")

# Initialize Vertex AI
vertexai.init(project=PROJECT_ID, location=LOCATION)

Step 3: Discovering and Inspecting Models

The Model Garden SDK makes it simple to search for deployable assets programmatically. For instance, if you want to inspect available configurations for the gemma family of models (including Hugging Face integrations), you can query them directly:

# List available models matching a specific filter
models = model_garden.list_deployable_models(model_filter="gemma", list_hf_models=True)

# Select an open-source model identifier
model_id = "google/gemma3@gemma-3-1b-it"
gemma_model = model_garden.OpenModel(model_id)

# Inspect the available hardware and deployment deployment options
deploy_options = gemma_model.list_deploy_options(concise=True)
print(deploy_options)

Step 4: Provisioning Infrastructure and Deploying

Once you select your model, the SDK lets you specify hardware profiles — such as machine types, accelerator requirements, and auto-scaling boundaries — and kick off infrastructure provisioning.

Below, we provision a single NVIDIA L4 GPU instance (g2-standard-12) to serve our endpoint:

print("Deploying model endpoint. This framework provisioning step may take some time...")

gemma_endpoint = gemma_model.deploy(
    machine_type="g2-standard-12",
    accelerator_type="NVIDIA_L4",
    accelerator_count=1,
    min_replica_count=1,
    max_replica_count=1,
    endpoint_display_name="gemma_model_endpoint",
    model_display_name="gemma_model_self",
    deploy_request_timeout=3 * 60 * 60, # 3-hour timeout limit for allocation
)

print(f"Endpoint successfully deployed! Resource ID: {gemma_endpoint.resource_name}")

Step 5: Running Predictions

Once the endpoint is live, serving inference requests requires just a structured JSON payload containing your prompt configuration and generation hyperparameters:

prediction = gemma_endpoint.predict(
    instances=[{
        "prompt": "Explain the architectural differences between specialized custom model endpoints and generic LLM APIs.", 
        "temperature": 0.0001, 
        "max_tokens": 150
    }]
)

print("Model Response:")
print(prediction.predictions[0])

Step 6: Resource Cleanup

To avoid ongoing billing for cloud GPU allocation when your workflows or testing cycles are complete, please ensure to explicitly teardown the endpoint resource:

# Force-deletes the deployed endpoint and stops active billing
gemma_endpoint.delete(force=True)
print("Endpoint successfully decommissioned.")

Summary & Code Repository

Using the Model Garden SDK through the Gemini Enterprise Agent Platform simplifies the complex containerization and Kubernetes management that is usually needed for custom LLM hosting. It provides a highly developer-friendly bridge between open-weight model architectures and enterprise-grade Vertex AI inference infrastructure.

GitHub: scholarly360/Gemini-Enterprise-Agent-Platform-Model-Garden-SDK

Introduction

As developers, we love experimenting with the latest AI developer tools. But let’s be honest: installing every new CLI tool directly onto your host machine can quickly turn into a configuration nightmare. Conflicts between dependencies, messy global environments, and security concerns are enough to make anyone hesitate.

If you want to test Claude Code Anthropic’s powerful command-line agent without cluttering your main operating system, there is a better way.

By isolating Claude Code inside a persistent Docker container running a full Ubuntu desktop environment and routing its power through OpenRouter, you get a completely walled-off, highly customizable, and secure developer sandbox.

Here is precisely how to set it up.

Why Sandbox Claude Code?

Sandboxing your AI development tools offers three massive advantages:

• Isolation: Your host OS (whether Windows, macOS, or Linux) remains completely untouched.
• Persistence: By using Docker volumes, all of your files, projects, and configurations stay intact even if you stop or restart the container.
• Flexibility via OpenRouter: Instead of juggling multiple individual LLM accounts and API keys, OpenRouter gives you a unified interface to access Claude models seamlessly with a single token.

The Prerequisites

Before diving into the terminal, please ensure you have two things ready:

1. Docker Desktop: Installed and running on your host machine.
2. An OpenRouter Account: Sign up, log in, and generate a new API key (it will look like sk-or-...).

Step 1: Spin Up the Ubuntu Desktop Sandbox

Instead of a bare-bones terminal container, we are using a Kasm Web Ubuntu Jammy desktop image. This gives us a full visual desktop environment accessible directly from any web browser.

Open your host terminal (like PowerShell or bash) and execute the Docker run command to start your sandbox:

Powershell

## Run Docker
>> docker run -d --name kasm-desktop --shm-size=1024m -p 6901:6901 -e VNC_PW=Random@32 -e KASM_USER=root --user root -v C:\Users\yogen\kasm-files:/home/kasm-user/persistent  kasmweb/ubuntu-jammy-desktop:1.18.0

## See all docker containers
>> docker ps

Note: You can adjust the configuration to attach a local storage volume to ensure your project files remain persistent on your host machine.

Once the container is running, open your favorite browser and navigate to: https://localhost:6901

Log in using the credentials configured in your setup, and you’ll be greeted by a shiny new Ubuntu desktop interface right inside your browser tab.

Step 2: Install the Claude Code CLI

Inside your browser-based Ubuntu desktop, open up a terminal application. Because this is a fresh environment, you have full root access to experiment.

To download and install the official Claude Code command-line tool, simply run the following installation script:

Bash

## Check Linux (Ubuntu) Version (Optional Only for Sanity)
>> cat /etc/os-release

## Install Claude Code
>> curl -fSSL https://claude.ai/install.sh | bash

The script will automatically configure the necessary paths and binary configurations for you.

Step 3: Wire OpenRouter to Claude's Code

By default, Claude Code expects a standard Anthropic API key. To trick it into using OpenRouter’s unified interface instead, we need to create a project-level local settings file.

• Create your main project folder and navigate into it:

## Sample Folder

>> mkdir FirstProject && cd FirstProject

## Create a hidden configuration directory named `.claude`:

>> mkdir .claude && cd .claude

## Create settings.local.json

>> touch settings.local.json

• Create a file named settings.local.json and paste the following structure, making sure to substitute your actual OpenRouter key:

JSON

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-actual-open-router-key-here",
    "ANTHROPIC_API_KEY": ""
  }
}

By pointing the ANTHROPIC_BASE_URL directly to OpenRouter and feeding your token into the auth parameter, Claude Code will now communicate effortlessly through the OpenRouter proxy network.

Step 4: Launch and Test inside VS Code

The beauty of the Kasm Ubuntu image is that it comes pre-installed with Visual Studio Code.

• Launch VS Code inside your container sandbox and open your FirstProject folder.
• Head to the Extensions marketplace, search for Claude Code for VS Code, and install it.
• Open the integrated Claude Code panel. Thanks to your settings.local.json environment variables, the tool will initialize without demanding a standard Anthropic login.

To verify that everything works, type a test instruction into the agent chat terminal, such as:

“List files in directory”

You will see Claude Code analyze your sandbox file structure, execute the bash query locally within the container bounds, and report back the results in real-time.

Wrap Up

You now have a fully operational, completely isolated playground for Claude Code. You can let the AI agent read files, write scripts, and execute terminal commands with zero anxiety about what it might do to your primary computer. If anything ever breaks or goes sideways, you can simply tear down the Docker container and spin up a pristine new sandbox in seconds.

Github Link :: https://github.com/scholarly360/Claude-Code-with-OpenRouter-in-a-Sandbox

Introduction

In the rapidly evolving landscape of generative AI, Anthropic’s Claude has emerged as a powerhouse for coding and reasoning tasks. While many developers are familiar with using Claude through a web interface or basic API calls, the real power lies in Claude Code Skills.

Normally, we run these skills in local environments. However, to truly scale for enterprise productivity, we need to expose these capabilities via web services. In this article, we’ll explore how to use the Claude Agent SDK to run custom code skills within a FastAPI API.

The Challenge: Moving Beyond Local Scripts

Claude "skills" are specialized capabilities essentially encapsulated instructions and tools that allow the model to perform specific tasks (like humanizing text, generating humor, or interacting with a file system) with high precision.

The problem? Most implementations are designed for local CLI usage. To build a robust enterprise application, you need to:

1. Centralize AI logic.
2. Provide a scalable API for front-end applications.
3. Securely manage credentials (like AWS Bedrock keys).

The Solution Architecture

To solve this problem, we combine three powerful technologies:

• Claude Agent SDK: The library that manages “Agentic” workflows and skill execution.
• FastAPI: A modern, high-performance web framework for building APIs with Python.
• Amazon Bedrock: To provide secure, enterprise-grade access to Claude models (not the consumer version).

Step 1: Environment Setup

First, you need to install the necessary dependencies. In your development environment (or a Docker container as shown in the GitHub repo), install the following:

pip install fastapi uvicorn python-dotenv claude-agent-sdk

Next, configure your .env file to connect to Amazon Bedrock.

CLAUDE_CODE_USE_BEDROCK=1
AWS_REGION=us-east-1
ANTHROPIC_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-east-1
ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
AWS_BEARER_TOKEN_BEDROCK=AWS_KEY

The Claude Agent SDK looks for skills in a specific directory structure: .claude/skills/. Each skill consists of a directory with a SKILL.md file that defines its behavior.

For example here are two skills

---
name: my-humanizer
description: Rewrites and transforms text to sound natural, warm, and authentically human — eliminating AI-sounding patterns like stiff structure
---

# My Humanizer Skill

## Goal

Transform AI-generated or stiff text into prose that sounds like it was written by a real, thoughtful human being with personality, natural rhythm, and genuine voice.

---
name: my-humour-creator
description: Generate creative, high-quality humourous text on any topic, theme, emotion, or occasion. 
---
 
# my-humour-creator Skill
Generate humourous text
 
## Goal
Generate creative, evocative, and humourous text

Step 3: Integrating the SDK with FastAPI

The core of the implementation is the run_query function. This function initializes the ClaudeAgentOptions, points the SDK to your skills directory, and executes the prompt.

Here is the simplified logic:

from claude_agent_sdk import query, ClaudeAgentOptions
from fastapi import FastAPI

app = FastAPI()
async def run_query(prompt: str):
    options = ClaudeAgentOptions(
        cwd=".", # Current working directory
        setting_sources=["user", "project"],
        allowed_tools=["Skill", "Read", "Write"] # Give the agent permission to use skills
    )
    
    result = ""
    # The SDK uses an asynchronous generator to stream the response
    async for message in query(prompt, options=options):
        if hasattr(message, 'text'):
            result += message.text
    return result
@app.post("/chat")
async def chat(request: PromptRequest):
    response = await run_query(request.prompt)
    return {"response": response}

Step 4: Invoking Skills via API

Once the server is running (using uvicorn app:app --port 5000), you can invoke specific skills directly through your API endpoint.

In the video, the developer demonstrates using a prompt like

“Using skill ‘my-humanizer’ convert following text: [Your Stiff Text Here]”

The Claude Agent SDK recognizes the “Skill” tool, looks up my-humanizer in the .claude/skills directory, applies the system instructions defined in the Markdown file, and returns the processed text.

Testing with Swagger UI

FastAPI automatically generates a /docs endpoint. You can use the interface to fire POST requests to the /chat endpoint and see the “humanized” output in real-time.

Why This Matters for Enterprise

1. Simply Modular AI Logic: You can update the behavior of your AI (the “Skill”) just by editing a Markdown file, without changing a single line of application code.
2. Tool Governance: By using allowed_tools, you can strictly control what the AI can do (e.g., it can read files but not run Bash commands in a production environment).
3. Bedrock Integration: Leveraging Amazon Bedrock ensures that your data remains within your VPC and meets corporate compliance standards.

Conclusion

The combination of Claude’s reasoning capabilities, the Agent SDK’s tool-use management, and FastAPI’s speed creates a formidable stack for any developer looking to build professional AI agents.

You are no longer limited to basic chat; you can now build a library of specialized skills and expose them to your entire organization through a simple, scalable API.

Resources

• GitHub Repository:

https://github.com/scholarly360/Claude-Code-Skills-Using-Claude-Agent-SDK

• Full Video Tutorial:

Introduction

In the fast-paced world of web development, "security" is often the thing we say we care about, but frequently the thing that gets squeezed at the end of a sprint. We’ve all been there: A deadline is looming, the features are finally working, and the security audit is treated as a final hurdle rather than a core part of the process.

But what if you could bake security into your development workflow using the same AI tools that you use to write code?

https://owasp.org/www-project-top-ten/

The “Shift Left” Reality

In the cybersecurity world, we talk a lot about “shifting left.” It simply means moving security checks earlier in the development lifecycle. The earlier you find a bug, the cheaper it is to fix.

The https://github.com/scholarly360/owasp-top10-web-skills repository provides custom "skills" for Claude Code that allow developers to scan their codebase for the most critical web security risks, from SQL Injection to Broken Access Control, directly from the terminal.

What are “Claude code skills"?

Claude Code allows users to define custom "skills," specialized prompts, and instructions that give the AI a specific lens through which to view your code. Instead of just asking, “Is this code safe?” These skills instruct Claude to search for specific patterns, misconfigurations, and logic flaws defined by OWASP.

A Deep Dive: Identifying SQL Injection

One of the most common (and dangerous) vulnerabilities is injection. In the video demo, I demonstrated a main.py file with an intentionally vulnerable FastAPI endpoint:

Sample

@app.get("/login")
def login(username: str = Query(...), password: str = Query(...)):
    db = sqlite3.connect("users.db")
    # VULNERABLE: Direct string interpolation
    query = f"SELECT * FROM users WHERE username = '{username}' AND password = '{password}'"
    # ...

https://owasp.org/Top10/2025/A05_2025-Injection/

By invoking the injection skill, Claude Code Skill doesn’t just see a function; it sees a potential disaster. It identifies that user input is interpolated directly into a SQL query and crucially provides the remediation: Parameterized queries.

Tackling Broken Access Control

Access control is notoriously difficult to test manually because it involves complex business logic. The project includes a broken access control skill that scans for things like

• Missing authorization on sensitive endpoints.
• IDOR (Insecure Direct Object Reference) vulnerabilities.
• CORS misconfigurations.

In the demo, Claude identifies that several endpoints are “Unguarded,” meaning anyone with the URL could potentially execute system commands or read arbitrary files.

"""
FastAPI Demo — Intentionally Vulnerable Endpoints
==================================================
Each endpoint is annotated with its vulnerability.
DO NOT use in production.
"""

from fastapi import FastAPI, Header, Query
import sqlite3, subprocess, os

app = FastAPI(title="Vulnerable Demo API")

DB = "users.db"

def init_db():
    con = sqlite3.connect(DB)
    con.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, username TEXT, password TEXT, role TEXT)")
    con.execute("INSERT OR IGNORE INTO users VALUES (1, 'admin', 'admin123', 'admin')")
    con.execute("INSERT OR IGNORE INTO users VALUES (2, 'alice', 'password1', 'user')")
    con.commit()
    con.close()

init_db()


# ─────────────────────────────────────────────
# 1. VULNERABILITY: SQL Injection
#    User input is interpolated directly into
#    the SQL query — an attacker can pass:
#    username=admin' OR '1'='1
# ─────────────────────────────────────────────
@app.get("/login")
def login(username: str = Query(...), password: str = Query(...)):
    con = sqlite3.connect(DB)
    query = f"SELECT * FROM users WHERE username = '{username}' AND password = '{password}'"
    row = con.execute(query).fetchone()
    con.close()
    if row:
        return {"status": "logged in", "user": row[1], "role": row[3]}
    return {"status": "invalid credentials"}


# ─────────────────────────────────────────────
# 2. VULNERABILITY: Command Injection
#    User-supplied `host` is passed directly to
#    the shell. An attacker can pass:
#    host=127.0.0.1; cat /etc/passwd
# ─────────────────────────────────────────────
@app.get("/ping")
def ping(host: str = Query(...)):
    result = subprocess.check_output(f"ping -c 1 {host}", shell=True, text=True)
    return {"output": result}


# ─────────────────────────────────────────────
# 3. VULNERABILITY: Broken Authentication
#    The "token" is just the username in plain
#    text. Anyone can impersonate any user by
#    passing their name as the token.
# ─────────────────────────────────────────────
@app.get("/profile")
def profile(x_token: str = Header(...)):
    # No real verification — token IS the username
    con = sqlite3.connect(DB)
    row = con.execute(f"SELECT * FROM users WHERE username = '{x_token}'").fetchone()
    con.close()
    if row:
        return {"username": row[1], "role": row[3]}
    return {"error": "user not found"}


# ─────────────────────────────────────────────
# 4. VULNERABILITY: Path Traversal
#    The filename is not sanitised. An attacker
#    can read arbitrary files:
#    filename=../../etc/passwd
# ─────────────────────────────────────────────
@app.get("/file")
def read_file(filename: str = Query(...)):
    path = os.path.join("uploads", filename)   # no realpath / jail check
    with open(path, "r") as f:
        content = f.read()
    return {"content": content}


# ─────────────────────────────────────────────
# 5. VULNERABILITY: Sensitive Data Exposure
#    The endpoint returns every user's password
#    in plain text with no authorisation check.
# ─────────────────────────────────────────────
@app.get("/users")
def list_users():
    con = sqlite3.connect(DB)
    rows = con.execute("SELECT id, username, password, role FROM users").fetchall()
    con.close()
    return [{"id": r[0], "username": r[1], "password": r[2], "role": r[3]} for r in rows]


# ─────────────────────────────────────────────
# 6. VULNERABILITY: Mass Assignment / IDOR
#    Any caller can change any user's role,
#    including escalating themselves to "admin",
#    with no ownership or permission check.
# ─────────────────────────────────────────────
@app.put("/user/{user_id}")
def update_user(user_id: int, username: str = Query(None), role: str = Query(None)):
    con = sqlite3.connect(DB)
    if username:
        con.execute(f"UPDATE users SET username='{username}' WHERE id={user_id}")
    if role:
        con.execute(f"UPDATE users SET role='{role}' WHERE id={user_id}")
    con.commit()
    con.close()
    return {"status": "updated"}

How to Set It Up

If you’re already using Claude Code, setting this up is incredibly straightforward.

Clone the Repository:

clone https://github.com/scholarly360/test-owasp-top10-web-skills.git

Locate Your Skills Folder: Claude Code looks for custom skills in the .claude/skills directory of your project.

Copy the Skills: Move the .json skill files from the cloned repo into your project’s .claude/skills folder.

Run the Scan: Inside the Claude Code CLI, you can simply say:

“Test the file ‘main.py’ using ‘broken-access-control’ local skill”

Claude will then “noodle,” “think,” and “percolate” (as the CLI status messages charmingly put it) before delivering a detailed report of findings, severity levels, and fix suggestions.

Why This Matters for the Enterprise

For enterprise teams, this isn’t just about catching bugs; it’s about

• Consistency: By using standardized OWASP skills, you ensure that every developer on the team is checking for the same risks.
• Education: When Claude flags a vulnerability and explains why it’s a risk, it acts as a real-time security coach for the developer.

The Future of AI-Assisted Security

We are moving toward a future where “security by design” isn’t just a buzzword but a default state. Tools like Claude Code, paired with community-driven repositories like this one, lower the barrier to entry for robust security testing.

You don’t need to be a penetration tester to write secure code; you just need the right tools in your terminal.

Check out the full project on GitHub:

GitHub - scholarly360/owasp-top10-web-skills: Agent Skills for OWASP Top 10 Application Security Risks (https://owasp.org/Top10/2025/)

https://github.com/scholarly360/test-owasp-top10-web-skill

Youtube Video

Background

Claude Code is brilliant. But in an enterprise, you can’t just pipe AI calls directly to Anthropic’s servers. You need everything routed through your cloud provider for billing, compliance, and your security team’s sanity. This Medium article shows you how to wire Claude code through Amazon Bedrock in under 15 minutes.

If you’re working in an enterprise environment, you’ve probably run into this wall: your cloud team doesn’t want LLM traffic bypassing your AWS account. It is not bureaucracy for its own sake. Routing through Bedrock gives you centralized billing, audit logs, VPC controls, and the ability to apply your existing IAM policies. It’s actually the right call.

Before we start: what you actually need

Node and Git should be installed

1. Node.js: (e.g., version v24.14.0). Download from nodejs.org
2. Git: (e.g., version 2.33.0). Download from git-scm.com

node -v
git --version

The four-step setup

Install Claude Code globally

One command, and you’re done. This installs the latest version of Claude Code globally via npm so you can run it from any directory:

npm install -g @anthropic-ai/claude-code@latest

Create your local settings file

Navigate to your project directory. Then create a .claude folder with a settings.local.json file inside it. This file is where you tell Claude Code to use Bedrock instead of calling Anthropic directly.

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "ANTHROPIC_MODEL": "us.anthropic.claude-sonnet-4-6",
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1",
    "AWS_BEARER_TOKEN_BEDROCK": "YOUR_LONG_TERM_API_KEY"
  }
}

Generate your Bedrock API key

Head over to your Amazon Bedrock console. In the left nav, look for API Keys. You’ll see two options—short-term and long-term. For any kind of team or production setup, pick long-term API keys.

Click Generate long-term API keys, copy what it gives you, and drop it into the AWS_BEARER_TOKEN_BEDROCK field in your settings file. Treat this key like a password; don't commit it to version control.

Fire it up

From your project directory, just run:

claude

If everything is wired correctly, the CLI will initialize and confirm it’s connecting.

https://www.youtube.com/watch?v=_vfZnWDo504&t

I built a real-time speech-to-text app with Next.js and Azure.

I’ve been tinkering with voice interfaces for a while now. Most of the tutorials out there are either way too complicated or use outdated browser APIs that barely work. Last weekend, I dedicated myself to creating a straightforward Next.js (Next JS 16) application that utilizes a microphone to display words on the screen as we speak.

No fancy UI. No twelve-step configuration wizards. The interface consists solely of a text box and a button.

Why I Built This Application

Here’s the thing: the Web Speech API is unreliable. It works differently across browsers, drops connections randomly, and the accuracy isn’t great. I wanted something that actually works consistently, and Azure’s VoiceLive API turned out to be that thing. On the contrary, Azure Voice LiveAPI is an overkill, as it is a real-time speech-to-text and text-to-speech service in one package.

Here is the link for Speech SDK, also known as Cognitive Services

Azure Cognitive Services Speech SDK is a developer toolkit from Microsoft that lets you add speech-to-text, text-to-speech, and speech translation capabilities into your applications using simple APIs. It is part of the broader Azure AI Speech service under Azure Cognitive Services.

Capabilities

• Real-time transcription (streaming mic/audio)
• Batch transcription (audio files)
• Custom speech models (domain vocabulary)
• Speaker diarization (who spoke when)
• Multi-language recognition

Typical uses

• Meeting transcription
• Voice command systems
• Call center analytics
• Dictation apps

It took me about a day to get it working properly.

The Stack

I went with Next.js 16, TypeScript, Tailwind CSS, and shadcn/ui for the handful of components I needed. The speech recognition logic lives in a single custom hook, use-voicelive-stt.ts which handles the Azure connection, audio capture, format conversion, and streaming. Everything else is just a clean editor UI.

The project structure is minimal on purpose:

• An app/ folder with the layout and main page
• A components/ui/ folder for the button and textarea
• A lib/ folder where the STT hook and utilities live

That’s it. There is no need for a state management library, complex routing, or over-engineering.

How the Hook Works

"use client";
/** 
   This is client side next js client side rendering

   Versions :: 
   "microsoft-cognitiveservices-speech-sdk": "^1.42.0",
    "next": "16.1.6",
    "react": "^19.0.0"
*/ 

import { useRef, useState, useCallback } from "react";

/**
 * Speech-to-text hook using the Azure Cognitive Services Speech SDK.
 * Requires:
 *   NEXT_PUBLIC_AZURE_SPEECH_KEY    - your Speech resource key
 *   NEXT_PUBLIC_AZURE_SPEECH_REGION - e.g. "eastus2" 
 *   Pls make ".env.local" and add above to it.
 */

export function useSpeechToText(onTranscript: (text: string) => void) {
  const [isListening, setIsListening] = useState(false);
  const [isConnecting, setIsConnecting] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [interimText, setInterimText] = useState<string>("");

  const recognizerRef = useRef<any>(null);

  /* ═══════════════════════ START ════════════════════════════ */
  const startListening = useCallback(async () => {
    try {
      setError(null);
      setIsConnecting(true);
      setInterimText("");

      // 1. Validate env vars
      const speechKey = process.env.NEXT_PUBLIC_AZURE_SPEECH_KEY;
      const speechRegion = process.env.NEXT_PUBLIC_AZURE_SPEECH_REGION;

      if (!speechKey || !speechRegion) {
        throw new Error(
          "Missing NEXT_PUBLIC_AZURE_SPEECH_KEY or NEXT_PUBLIC_AZURE_SPEECH_REGION. " +
            "Copy .env.local.example → .env.local and fill in your values."
        );
      }

      // 2. Dynamic import (keeps the SDK out of the server bundle)
      const sdk = await import("microsoft-cognitiveservices-speech-sdk");

      // 3. Configure
      const speechConfig = sdk.SpeechConfig.fromSubscription(
        speechKey,
        speechRegion
      );
      speechConfig.speechRecognitionLanguage = "en-US";
      // Change en-US to your Language e.g. "en-IN"

      // Use browser microphone
      const audioConfig = sdk.AudioConfig.fromDefaultMicrophoneInput();

      // 4. Create recognizer
      const recognizer = new sdk.SpeechRecognizer(speechConfig, audioConfig);
      recognizerRef.current = recognizer;

      // ── "recognizing" — fires continuously with interim/partial results ──
      recognizer.recognizing = (_sender: any, event: any) => {
        const partial = event.result?.text ?? "";
        console.log("[STT] 📝 Recognizing:", partial);
        setInterimText(partial);
      };

      // ── "recognized" — fires when a phrase is finalized ──
      recognizer.recognized = (_sender: any, event: any) => {
        const sdk2 = sdk; // capture for ResultReason
        if (event.result.reason === sdk2.ResultReason.RecognizedSpeech) {
          const finalText = event.result.text?.trim();
          console.log("[STT] ✅ Recognized:", finalText);
          if (finalText) {
            onTranscript(finalText);
          }
        } else if (event.result.reason === sdk2.ResultReason.NoMatch) {
          console.log("[STT] No match — could not recognize speech");
        }
        setInterimText("");
      };

      // ── "canceled" — fires on errors or end of stream ──
      recognizer.canceled = (_sender: any, event: any) => {
        const sdk2 = sdk;
        console.error("[STT] ❌ Canceled:", event.errorDetails);
        if (event.reason === sdk2.CancellationReason.Error) {
          setError(event.errorDetails ?? "Speech recognition error");
        }
        setIsListening(false);
      };

      // ── session events ──
      recognizer.sessionStarted = () => {
        console.log("[STT] 🎤 Session started — listening");
        setIsListening(true);
        setIsConnecting(false);
      };

      recognizer.sessionStopped = () => {
        console.log("[STT] Session stopped");
        setIsListening(false);
      };

      // 5. Start continuous recognition
      recognizer.startContinuousRecognitionAsync(
        () => {
          console.log("[STT] ✅ Continuous recognition started");
        },
        (err: string) => {
          console.error("[STT] Failed to start:", err);
          setError(err);
          setIsConnecting(false);
        }
      );
    } catch (err: any) {
      console.error("[STT] startListening error:", err);
      setError(err?.message ?? "Failed to start listening.");
      setIsConnecting(false);
    }
  }, [onTranscript]);

  /* ═══════════════════════ STOP ═════════════════════════════ */
  const stopListening = useCallback(async () => {
    const recognizer = recognizerRef.current;
    if (recognizer) {
      recognizer.stopContinuousRecognitionAsync(
        () => {
          console.log("[STT] Stopped ✅");
          recognizer.close();
          recognizerRef.current = null;
        },
        (err: string) => {
          console.error("[STT] Stop error:", err);
          recognizer.close();
          recognizerRef.current = null;
        }
      );
    }
    setIsListening(false);
    setInterimText("");
  }, []);

  return {
    isListening,
    isConnecting,
    error,
    interimText,
    startListening,
    stopListening,
  };
}

This is a custom React hook called useSpeechToText that provides real-time speech-to-text functionality using Azure Cognitive Services Speech SDK. Here's how it works:

Purpose: It captures audio from the user’s microphone, streams it to Azure’s speech recognition service, and returns transcribed text in real time.

State it manages:

• isListening — whether the mic is actively capturing
• isConnecting — brief transition state while setting up the connection
• error — any error message
• interimText — partial/in-progress transcription (updates as you speak, before a phrase is finalized)

startListening flow:

1. Reads the Azure API key and region from environment variables
2. Dynamically imports the Speech SDK (so it doesn’t bloat the server-side bundle in Next.js)
3. Creates a SpeechConfig (credentials + language) and an AudioConfig (browser microphone)
4. Instantiates and wires up four event handlers:

• recognizing — fires repeatedly with partial results as you speak (the "live caption" effect)
• recognized — fires when Azure finalizes a complete phrase; calls onTranscript(finalText) to pass it to the parent component
• canceled — handles errors or unexpected disconnections
• sessionStarted/sessionStopped toggle the isListening state

Usage pattern: A component would call startListening on a button press, display interimText as a live preview, and receive finalized sentences via the onTranscript callback, for example, appending them to a text input field.

Azure Cognitive Services Speech SDK is the traditional, modular toolkit for adding individual speech capabilities to your applications. It provides discrete services like speech-to-text, text-to-speech, speech translation, and speaker recognition. You integrate each component separately and orchestrate the pipeline yourself, for example, taking audio input, running STT, sending text to your LLM, and then running TTS on the response. It’s available across many programming languages (C#, C++, Java, JavaScript, Python, Go, etc.) and platforms and supports both real-time and non-real-time scenarios using local devices, files, blob storage, and streams.

Azure Voice Live (sometimes called “Voice Live API”) is a newer, higher-level managed service specifically designed for real-time speech-to-speech voice agents. It consolidates speech recognition, generative AI, and text-to-speech into a single unified interface, so you can build end-to-end voice experiences with less integration work. Instead of having to stitch together the speech-to-text (STT), large language model (LLM), and text-to-speech (TTS) components yourself, Voice Live manages the entire pipeline for you.

When to Use Which

Use the Speech SDK when you need individual speech components (just transcription, just synthesis), batch processing, custom speech models, translation, or fine-grained control over each piece of the pipeline.

Use Voice Live when you’re building a real-time conversational voice agent and want a turnkey solution that handles the full STT → LLM → TTS pipeline with minimal latency and integration effort.

Setting It Up

If you want to try it yourself, the setup is about five minutes. Clone the repo, run npm install, create a .env.local file with your Azure endpoint and API key, and hit npm run dev. The README walks through it step by step.

You will need an Azure account that includes a Microsoft Foundry resource (formerly known as Azure Foundry).

GitHub repo: github.com/scholarly360/Azure-Voice-STT-With-Next-JS

A Word About Security

The demo uses NEXT_PUBLIC_ environment variables, which means your API key is exposed in the browser. This is fine for local development and quick demos, but please don't ship it to production as-is. In a real app, you'd want to proxy requests through a backend route so your keys stay server-side.

What I’d Add Next

A few things are on my mind for future iterations. Language selection would be helpful; right now it defaults to English. Speaker diarization (identifying who’s talking) would make this useful for meeting transcription. And exporting the transcript to a file seems like an obvious quality-of-life feature.

But honestly? For a weekend project, I’m happy with where it landed. The project performs a single function effectively.

If you’re building voice features into a web app and want a clean starting point, feel free to fork the repo and make it your own. It’s MIT licensed; do whatever you want with it.