<![CDATA[ Eva J Patel - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ https://cdn.freecodecamp.org/universal/favicons/favicon.png <![CDATA[ Eva J Patel - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ Eleventy Wed, 09 Sep 2026 11:31:20 +0000 60 <![CDATA[ How to Build an AI File Analysis Agent with Python ]]> https://www.freecodecamp.org/news/build-an-ai-analysis-agent/ 6a96f2cfeb26827ea17d08f5 Tue, 01 Sep 2026 15:44:15 +0000 If you've ever opened a 30-page PDF and thought, “There's absolutely no way I am reading all of this,” you already understand why file-analysis AI agents are useful.

Imagine uploading a research paper, résumé, CSV file, business report, or PDF and simply asking:

“What are the most important findings?”

Instead of manually searching through the document, an AI agent can inspect the file, understand what's inside it, and answer questions about it.

In this tutorial, we're going to build exactly that. We'll create a beginner-friendly AI file analysis agent in Python that can:

  • Accept a file from your computer

  • Upload the file to an AI model

  • Read the contents of the file

  • Understand natural-language questions

  • Analyze the file

  • Return a useful answer

  • Handle different types of questions without us writing a separate function for every possible question

We'll build the project using Python and the OpenAI API.

The important part is that we won't just copy and paste code and hope it works. We'll go through the code line by line so you understand what every important piece is doing.

By the end, you should understand not only how to build this project, but also the basic architecture behind many real-world AI agents.

What We'll Cover:

What Are We Actually Building?

Before writing code, let's define what an AI agent actually means.

An ordinary AI chatbot might work like this:

User → Question → AI → Answer

An AI agent can be more flexible:

User → Goal → Agent → Decide what it needs → Use tools/data → Analyze → Answer

For our project, the “data” will be a file.

For example, imagine we give our agent a research paper called:

ai-research.pdf

Then we ask:

What is the main argument of this paper?

The agent needs to:

  1. Receive the question.

  2. Access the file.

  3. Read the relevant content.

  4. Understand the content.

  5. Analyze it.

  6. Produce an answer.

The AI model handles the language understanding and reasoning. Our Python program handles the workflow around it.

That distinction is important.

The model isn't magically reading files sitting on your laptop. Our application has to give the model access to the file.

OpenAI's current API supports sending uploaded files as inputs to the Responses API, which allows models to analyze files directly.

What We Are Going to Use

Our project will use:

  • Python: our programming language

  • OpenAI Python SDK: lets Python communicate with the OpenAI API

  • Responses API: the API endpoint we'll use to interact with the model

  • An uploaded file: the information our agent will analyze

  • A prompt: instructions telling the agent what to do

We'll intentionally keep the first version simple.

You don't need LangChain, a vector database, React, or a complicated backend.

Once you understand this version, you can add those technologies later.

What You Should Know Before Starting

This tutorial is designed for beginner and intermediate developers.

You should be comfortable with basic Python concepts such as:

  • Variables

  • Functions

  • if statements

  • Imports

  • Strings

  • Lists

  • Dictionaries

  • Running Python programs from a terminal

You do not need to know machine learning, know how transformers work internally, or the mathematics behind large language models.

We're focusing on how to build the application here.

Step 1: Create the Project

First, create a folder for the project.

For example:

file-analysis-agent/

Inside it, we'll eventually have:

file-analysis-agent/
│
├── agent.py
├── requirements.txt
└── .env

Each file has a purpose.

  1. agent.py: This is where our Python application lives.

  2. requirements.txt: This tells Python which external packages our project needs.

  3. .env: This is where we can store our API key locally instead of putting it directly into our Python code.

Keeping secrets out of source code is an important habit to develop early.

Step 2: Create a Virtual Environment

Open your terminal inside the project folder.

Run:

python -m venv venv

This creates a Python virtual environment.

A virtual environment gives your project its own isolated collection of Python packages. Think of it like giving this project its own little Python workspace.

You can activate it on Windows with:

venv\Scripts\activate

On macOS or Linux:

source venv/bin/activate

Once activated, you should see something similar to:

(venv)

at the beginning of your terminal prompt.

Step 3: Install the OpenAI SDK

Now install the official OpenAI Python package:

pip install openai

The SDK gives us Python classes and methods that make API calls much easier.

Without an SDK, we would have to manually construct HTTP requests.

With the SDK, we can write Python like:

client.responses.create(...)

instead of manually constructing the entire HTTP request.

The OpenAI quickstart currently uses the Responses API as the starting point for API requests.

Step 4: Create Your API Key

You need an OpenAI API key to communicate with the API. Create an API key through your OpenAI developer account.

Do not put your real API key directly into your source code like this:

api_key = "sk-your-real-key"

That's a bad habit.

If you upload your project to GitHub, you could accidentally expose the key. Instead, store it as an environment variable.

For example, on Windows PowerShell:

$env:OPENAI_API_KEY="your_api_key_here"

On macOS/Linux:

export OPENAI_API_KEY="your_api_key_here"

The OpenAI SDK can automatically read the OPENAI_API_KEY environment variable.

Step 5: Create requirements.txt

Create a file called:

requirements.txt

Put this inside:

openai

Now another developer can install the project's dependency with:

pip install -r requirements.txt

This is a small thing, but it's a very useful professional habit.

Step 6: Create the Python File

Create:

agent.py

Start with:

from openai import OpenAI

Let's break this down.

  • from: Python's from keyword allows us to import something from another module.

  • openai: This is the Python package we installed.

  • import OpenAI: We're importing the OpenAI class from that package.

Now we can create an OpenAI client.

Add:

client = OpenAI()

This creates our API client.

You can think of client as our application's connection point to the OpenAI API. Whenever we want to communicate with the API, we'll use this client.

For example:

response = client.responses.create(...)

The client handles the underlying HTTP communication for us.

Step 7: Ask the User for a File

We want our application to allow the user to specify a file.

Add:

file_path = input("Enter the path to your file: ")

Now let's understand this line.

The input() function waits for the user to type something.

For example, the terminal might display:

Enter the path to your file:

The user might type:

research.pdf

Python stores that text inside:

file_path

So after the user enters:

research.pdf

we effectively have:

file_path = "research.pdf"

Now our program knows which file the user wants to analyze.

Step 8: Check Whether the File Exists

Before uploading anything, it's a good idea to make sure the file actually exists.

We can use Python's built-in os module for this.

Add:

import os

Then:

if not os.path.exists(file_path):
    print("File not found.")
    exit()

Let's break this down.

The os module gives Python tools for interacting with the operating system.

One of those tools is:

os.path.exists()

It checks whether a file or folder exists at a particular path.

if: We're checking a condition.

if not os.path.exists(file_path):

This means:

If the file does NOT exist...

The not keyword reverses the result.

If:

os.path.exists(file_path)

returns True then not True becomes False. But if the file doesn't exist...False becomes True.

So the code inside the if statement only runs when the file can't be found.

Next, print() displays:

File not found.

exit() stops the program.

That prevents our application from trying to upload a file that doesn't exist.

Step 9: Upload the File

Now comes the interesting part: we need to send the file to the API.

Add:

with open(file_path, "rb") as file:
    uploaded_file = client.files.create(
        file=file,
        purpose="user_data"
    )

This looks more complicated than it really is.

Let's go through it piece by piece.

Understanding open()

The first line is:

with open(file_path, "rb") as file:

The open() function opens a file.

The first argument is:

file_path

which is the path entered by the user.

The second argument is:

"rb"

This means:

  • r = read

  • b = binary

We use binary mode because we're dealing with uploaded files rather than simply reading plain text.

The with statement is important because Python automatically handles closing the file when we are finished with it.

The variable:

file

represents the opened file.

Uploading the File

Inside the with block we have:

uploaded_file = client.files.create(

This asks the OpenAI API to create an uploaded file.

The file argument:

file=file

passes the file we opened.

Then:

purpose="user_data"

tells the API that the uploaded file is intended to be used as user data.

The Files API supports a user_data purpose for flexible file use.

After this finishes, OpenAI returns information about the uploaded file. We store that information in:

uploaded_file

One useful property is:

uploaded_file.id

That ID identifies the uploaded file.

Step 10: Look at the Uploaded File ID

Add:

print("Uploaded file:", uploaded_file.id)

Now you can see something like:

Uploaded file: file-abc123

That ID is important.

Our local computer knows the file as:

research.pdf

The API knows it through something like:

file-abc123

We can use that ID when sending the file to the model.

Step 11: Create the Agent's Instructions

Now we need to tell the AI what its job is.

Create:

instructions = """
You are a file analysis assistant.

Your job is to carefully analyze the file provided by the user.

Answer questions using information from the file.

If the answer can't be found in the file, clearly say that the information is not available in the file.

Do not invent facts.

When useful, organize your answer with headings and bullet points.
"""

This is called an instruction or prompt.

The triple quotes:

"""
...
"""

allow us to create a multi-line string.

Our agent now has a role.

It knows:

  • What it's supposed to do

  • What information it should use

  • What to do when information is missing

  • How it should format answers

The instruction:

Do not invent facts.

is especially important for file-analysis applications.

We want the model to distinguish between:

“The file says this.”

and:

“I think this might be true.”

Those are not the same thing.

Step 12: Ask the User What They Want to Know

Now we need the actual question.

Add:

question = input("What would you like me to analyze? ")

For example, the user could enter:

What are the three most important findings in this paper?

Or:

Summarize this document in five bullet points.

Or:

What methodology did the researchers use?

This is where our application becomes flexible.

We don't need to create separate Python functions for every possible question. The user can ask questions naturally.

Step 13: Send the File and Question to the Model

Now we can finally create the response.

Add:

response = client.responses.create(
    model="gpt-5",
    instructions=instructions,
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": question
                },
                {
                    "type": "input_file",
                    "file_id": uploaded_file.id
                }
            ]
        }
    ]
)

This is the most important section of the entire project.

Let's slow down and understand it.

Understanding client.responses.create()

We start with:

client.responses.create(

We're asking the Responses API to generate a response.

The OpenAI API supports file inputs in the Responses API, including using an uploaded file's ID as an input_file.

Understanding the Model

We have:

model="gpt-5"

This tells the API which model should process the request.

The model is the part responsible for understanding the question and analyzing the information provided to it.

The exact model you choose can change over time, so treat the model name as a configurable part of your application rather than something permanently hard-coded into your architecture.

Understanding instructions

Next:

instructions=instructions

Remember the variable we created earlier?

instructions = """
You are a file analysis assistant.
...
"""

We're passing those instructions into the API request so the model knows what role it should perform.

Understanding input

Next we have:

input=[

The input contains the information we give the model.

In our case, we're giving it:

  1. The user's question

  2. The file

This is important because an AI model can't answer a file-specific question if we never give it the file.

Understanding the User Message

Inside the input we have:

{
    "role": "user",

This tells the API that this input represents the user's message.

Then:

"content": [

contains the actual content of that message.

Sending the Question

The first content item is:

{
    "type": "input_text",
    "text": question
}

This tells the model:

Here is some text input.

The actual text comes from:

question

which was entered by the user.

If the user entered:

What is the main conclusion?

then the model receives that question.

Sending the File

The next content item is:

{
    "type": "input_file",
    "file_id": uploaded_file.id
}

This tells the API:

Here is a file input.

And:

uploaded_file.id

tells the API exactly which uploaded file we're referring to.

So our request effectively contains:

Question:
"What is the main conclusion?"

File:
research.pdf

The model can then analyze the provided file in the context of the user's question.

Step 14: Print the Answer

We have the response stored in:

response

But we don't want to print the entire response object.

We want the generated text.

The SDK provides:

response.output_text

So add:

print("\nAgent:\n")
print(response.output_text)

The first print() creates a little spacing and prints:

Agent:

The second prints the actual answer.

Our First Complete Version

At this point, our entire agent.py looks like this:

import os
from openai import OpenAI


client = OpenAI()


file_path = input("Enter the path to your file: ")


if not os.path.exists(file_path):
    print("File not found.")
    exit()


with open(file_path, "rb") as file:
    uploaded_file = client.files.create(
        file=file,
        purpose="user_data"
    )


print("Uploaded file:", uploaded_file.id)


instructions = """
You are a file analysis assistant.

Your job is to carefully analyze the file provided by the user.

Answer questions using information from the file.

If the answer cannot be found in the file, clearly say that the information is not available in the file.

Do not invent facts.

When useful, organize your answer with headings and bullet points.
"""


question = input("What would you like me to analyze? ")


response = client.responses.create(
    model="gpt-5",
    instructions=instructions,
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": question
                },
                {
                    "type": "input_file",
                    "file_id": uploaded_file.id
                }
            ]
        }
    ]
)


print("\nAgent:\n")
print(response.output_text)

That's already a functional file-analysis AI application.

But we can make it much better.

Step 15: Run the Application

Place a file such as:

research.pdf

inside your project folder.

Then run:

python agent.py

You should see:

Enter the path to your file:

Enter:

research.pdf

Then you might see:

Uploaded file: file-abc123

Next:

What would you like me to analyze?

You could ask:

Summarize the main findings in five bullet points.

The agent will analyze the file and return an answer.

Why Is This an Agent?

At first glance, this might look like a normal API call. And technically, yes, our first version is a fairly simple agent workflow.

The important concept is the agent loop.

An agent generally has:

  1. A goal

  2. Instructions

  3. Access to information

  4. Potential tools

  5. A reasoning process

  6. An action

  7. An output

Our application has several of these pieces.

The user provides a goal:

Analyze this research paper.

The instructions define the agent's behavior:

You are a file analysis assistant.

The file provides information:

research.pdf

The model processes the information, then the application returns the result.

As applications become more advanced, agents can also use tools such as file search, web search, function calling, and other external systems. OpenAI's platform currently supports built-in tools and custom function tools for extending agents.

Step 16: Turn It Into a Real Conversation

Our current application only asks one question.

That's useful, but not ideal.

Imagine uploading a research paper and then having to restart the program every time you want to ask another question.

We can improve that by putting the question inside a loop.

Instead of:

question = input("What would you like me to analyze? ")

we can use:

while True:
    question = input("\nAsk a question (or type 'exit'): ")

    if question.lower() == "exit":
        break

Now let's understand it.

  • while True: This creates a loop that continues indefinitely. It will keep asking questions until we tell it to stop.

  • question = input(...): The user enters another question.

  • question.lower(): The .lower() method converts the question to lowercase.

For example:

EXIT

becomes:

exit

and:

Exit

also becomes:

exit

This makes our exit check more reliable.

Finally, the break keyword stops the loop. So:

if question.lower() == "exit":
    break

means:

If the user types exit, stop asking questions.

Step 17: Move the AI Request Into the Loop

Now the API request needs to happen inside the loop.

Our structure becomes:

while True:
    question = input("\nAsk a question (or type 'exit'): ")

    if question.lower() == "exit":
        break

    response = client.responses.create(
        model="gpt-5",
        instructions=instructions,
        input=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": question
                    },
                    {
                        "type": "input_file",
                        "file_id": uploaded_file.id
                    }
                ]
            }
        ]
    )

    print("\nAgent:\n")
    print(response.output_text)

Now the user can ask multiple questions about the same file.

For example:

Ask a question:
What is this paper about?

Then:

Ask a question:
What methodology did the researchers use?

Then:

Ask a question:
What were the biggest limitations?

And finally:

Ask a question:
exit

This makes the application feel much more like an actual assistant.

Step 18: Improve the Agent's Instructions

A good AI application isn't just about calling an API. The instructions matter a lot.

We can make our instructions more specific.

For example:

instructions = """
You are an AI file analysis assistant.

Your job is to analyze the file provided by the user.

Follow these rules:

1. Use the provided file as your primary source.
2. Answer the user's question directly.
3. Do not invent information that is not supported by the file.
4. If the file does not contain enough information to answer a question, say so.
5. When summarizing, focus on the most important information.
6. When comparing ideas, clearly explain the similarities and differences.
7. When analyzing research, distinguish between results, methods, and conclusions.
8. Use simple language unless the user asks for technical language.
9. Use bullet points when they make the answer easier to understand.
10. If you make an inference, clearly label it as an inference.
"""

This is much stronger.

We're essentially giving our AI a set of rules.

Why Good Instructions Matter

Imagine telling someone:

“Read this document.”

They might read it and give you almost anything.

Now imagine saying:

“Read this document, identify the research question, summarize the methodology, identify the major findings, and explain the limitations using simple language.”

That second instruction is much more useful.

AI agents work the same way. The more clearly you define the job, the easier it is for the model to produce consistent results.

Step 19: Add Error Handling

Right now, our program assumes everything will work.

Real applications shouldn't do that. Files can fail to upload, the API can return an error, the user can enter an invalid path, or the network can temporarily fail.

We can use try and except to handle these situations.

For example:

try:
    response = client.responses.create(
        model="gpt-5",
        instructions=instructions,
        input=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": question
                    },
                    {
                        "type": "input_file",
                        "file_id": uploaded_file.id
                    }
                ]
            }
        ]
    )

    print(response.output_text)

except Exception as error:
    print("Something went wrong:")
    print(error)

  • try: The code inside the try block is code that might fail.

  • except: If an error happens, Python jumps to the except block.

  • Exception as error: This captures the error so we can display it.

Instead of the entire application crashing with a confusing traceback, the user sees:

Something went wrong:
...

For a production application, you would usually want more sophisticated logging and error handling, but this is a good starting point.

Step 20: Validate the File Extension

We can also check which type of file the user selected.

Add:

allowed_extensions = {
    ".pdf",
    ".txt",
    ".docx",
    ".csv"
}

This creates a set of file extensions that our application expects to support.

Then:

extension = os.path.splitext(file_path)[1].lower()

Let's break this down.

os.path.splitext()

This separates the filename from its extension.

For:

research.pdf

it gives us approximately:

research

and:

.pdf

The [1] selects the extension.

Then:

.lower()

converts it to lowercase.

So:

RESEARCH.PDF

becomes:

.pdf

Now we can check:

if extension not in allowed_extensions:
    print("Unsupported file type.")
    exit()

This prevents users from uploading file types our application hasn't been designed to handle.

Always verify the currently supported file types for the API and model you choose before expanding your application. OpenAI's file and input APIs document file handling and supported input types.

Step 21: Add a File Name to the Interface

We can make the terminal experience slightly nicer.

Instead of:

print("Uploaded file:", uploaded_file.id)

we can write:

print(f"\nSuccessfully uploaded: {os.path.basename(file_path)}")

The f before the string creates an f-string.

That allows us to insert Python variables inside {}.

For example:

f"Successfully uploaded: {os.path.basename(file_path)}"

might produce:

Successfully uploaded: research.pdf

os.path.basename()

This extracts just the filename from the path.

If the user enters:

documents/research.pdf

then:

os.path.basename(file_path)

returns:

research.pdf

Step 22: Build the Clean Final Version

Now let's combine everything.

Here is a cleaner version of our application:

import os

from openai import OpenAI


# Create the OpenAI client.
client = OpenAI()


# Ask the user for a file.
file_path = input("Enter the path to your file: ").strip()


# Make sure the file exists.
if not os.path.exists(file_path):
    print("File not found.")
    exit()


# Allowed file types.
allowed_extensions = {
    ".pdf",
    ".txt",
    ".docx",
    ".csv"
}


# Get the file extension.
extension = os.path.splitext(file_path)[1].lower()


# Make sure the file type is supported by our application.
if extension not in allowed_extensions:
    print(f"Unsupported file type: {extension}")
    print("Supported types:", ", ".join(allowed_extensions))
    exit()


# Upload the file.
try:
    with open(file_path, "rb") as file:
        uploaded_file = client.files.create(
            file=file,
            purpose="user_data"
        )

except Exception as error:
    print("The file could not be uploaded.")
    print(error)
    exit()


print(f"\nSuccessfully uploaded: {os.path.basename(file_path)}")


# Define the agent's behavior.
instructions = """
You are an AI file analysis assistant.

Your job is to analyze the file provided by the user.

Follow these rules:

1. Use the provided file as your primary source.
2. Answer the user's question directly.
3. Do not invent information that is not supported by the file.
4. If the file does not contain enough information to answer a question, say so.
5. When summarizing, focus on the most important information.
6. When comparing ideas, clearly explain similarities and differences.
7. When analyzing research, distinguish between methods, results, and conclusions.
8. Use simple language unless the user asks for technical language.
9. Use bullet points when they make the answer easier to understand.
10. If you make an inference, clearly label it as an inference.
"""


# Start the conversation.
print("\nYour file is ready to analyze.")
print("Ask questions about the file.")
print("Type 'exit' when you are finished.")


while True:

    # Get a question from the user.
    question = input("\nYou: ").strip()


    # Stop the program if the user wants to exit.
    if question.lower() == "exit":
        print("Goodbye!")
        break


    # Ignore empty questions.
    if not question:
        print("Please enter a question.")
        continue


    # Send the question and file to the model.
    try:
        response = client.responses.create(
            model="gpt-5",
            instructions=instructions,
            input=[
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": question
                        },
                        {
                            "type": "input_file",
                            "file_id": uploaded_file.id
                        }
                    ]
                }
            ]
        )


        # Display the AI's response.
        print("\nAgent:")
        print(response.output_text)


    except Exception as error:
        print("\nThe agent encountered an error.")
        print(error)

Let's Understand the Architecture

At this point, it is useful to step away from the code. Our application has several layers.

Layer 1: User Interface

The terminal asks:

Enter the path to your file:

and:

You:

This is how the user interacts with our application.

Layer 2: File Handling

Python checks:

os.path.exists(file_path)

and opens:

open(file_path, "rb")

This layer handles the local file.

Layer 3: File Upload

The application sends the file to the API:

client.files.create(...)

The API gives us a file ID.

Layer 4: Agent Instructions

We define:

instructions

This tells the model how to behave.

Layer 5: User Request

The user asks:

What are the main findings?

Layer 6: Model

The model receives:

  • The instructions

  • The question

  • The file

and generates an answer.

Layer 7: Output

We display:

response.output_text

to the user.

This separation is useful because it makes the project easier to extend later.

Why We Don't Need to Manually Extract Every PDF

A beginner might wonder:

“Why don't we use Python to extract all the text first?”

That's absolutely possible. You could use libraries such as:

PyPDF
python-docx
pandas

to read different file formats yourself.

Then you could send the extracted text to an AI model.

That approach can be useful, especially when you need custom preprocessing. But it also creates more work.

You would need to write separate logic for:

PDF → extract text
DOCX → extract text
CSV → read rows
TXT → read text

Then you would need to figure out how to send all that information to the model.

With file inputs, the API can accept the file directly, which can simplify the architecture for supported use cases.

But What About Very Large Files?

This is where things get more interesting.

Imagine a user uploads a 2,000-page collection of documents. You probably don't want to send everything into every single request.

Instead, you may want a system that can search for the most relevant sections. This is where retrieval becomes important.

One common architecture is:

Documents
    ↓
Split into chunks
    ↓
Create embeddings
    ↓
Store searchable representations
    ↓
User asks question
    ↓
Find relevant chunks
    ↓
Send relevant information to model
    ↓
Generate answer

This approach is commonly associated with Retrieval-Augmented Generation, or RAG.

OpenAI also provides a file search tool that can search uploaded files using vector stores.

Our first project intentionally doesn't introduce RAG because it would add a lot of concepts at once.

First understand direct file analysis. Then learn retrieval. Then combine the two.

Direct File Input vs RAG

It's useful to understand the difference.

Direct File Input

You give the model a file for a particular request.

For example:

Upload:
research-paper.pdf

Question:
What was the main conclusion?

This is simple and great for many smaller applications.

RAG

You have a larger collection of documents.

For example:

100 research papers
50 reports
20 manuals

Instead of giving the model every document for every question, you search the collection for relevant information first. Then you provide the relevant pieces to the model.

This is more scalable for large knowledge bases.

Step 23: Make the Agent Better at Different Types of Files

Different files contain different kinds of information.

A PDF might contain:

Research paper

A CSV might contain:

Name,Age,Score
Alex,17,91
Sam,18,87

A DOCX might contain:

A long essay

A good agent should understand what kind of information it is dealing with.

We can make our instructions reflect this.

For example:

instructions = """
You are an AI file analysis assistant.

First understand what type of information the uploaded file contains.

If the file is a research paper:
- Identify the research question.
- Explain the methodology.
- Summarize the results.
- Explain the conclusion.
- Identify limitations.

If the file contains tabular data:
- Identify the columns.
- Describe important patterns.
- Identify unusual values when possible.
- Explain trends clearly.
- Do not invent numerical results.

If the file is a general document:
- Identify its main purpose.
- Summarize the important sections.
- Answer questions using information from the document.

Always:
- Use the file as your primary source.
- Do not invent facts.
- Clearly distinguish facts from inferences.
- Say when the file does not contain enough information.
- Use simple language.
"""

Now our agent has more context about the kinds of work it may perform.

Step 24: Give the Agent a Specific Role

You can think of the instruction as the agent's job description.

For example:

You are an AI research assistant.

is fairly broad.

But:

You are an AI research assistant who analyzes academic papers.

is more specific.

We can go further:

You are an AI research assistant specializing in helping students understand academic papers.

Now we have a target audience.

The model can adjust its explanations accordingly.

This is one of the easiest ways to make an AI application feel much more useful without writing a huge amount of code.

Step 25: Add an Analysis Mode

We can make the application even more useful by letting the user select an analysis mode.

For example:

1. Summarize
2. Explain
3. Find key points
4. Analyze
5. Ask a question

We could ask:

mode = input(
    "\nChoose a mode: "
    "summarize, explain, analyze, or question: "
)

Then modify the prompt based on the user's selection.

For example:

if mode.lower() == "summarize":
    task = "Summarize the most important information from the file."

elif mode.lower() == "explain":
    task = "Explain the file in beginner-friendly language."

elif mode.lower() == "analyze":
    task = "Perform a detailed analysis of the file."

else:
    task = question

This is a simple example of application logic controlling an AI model.

The AI still generates the language, but our Python application decides what kind of task it should perform.

Step 26: Why This Is Different From Hard-Coding Every Answer

Imagine you wanted to support these questions:

  1. Summarize the file.

  2. What is the main idea?

  3. What are the limitations?

  4. Who is the target audience?

  5. What evidence supports the conclusion?

You could technically create a separate Python function for each one. But that would quickly become ridiculous.

Instead, we can let the user ask naturally:

question = input("What would you like to know? ")

The AI handles the language. Our application provides the file and context.

This is one of the major advantages of using language models in applications.

Step 27: Security Matters

Now let's talk about something that's not as exciting as the AI part but is extremely important.

Never expose your API key.

Bad:

client = OpenAI(
    api_key="sk-real-secret-key"
)

Better:

client = OpenAI()

with the key stored in an environment variable.

Also avoid committing secrets to GitHub.

Your .gitignore file should include things such as:

.env
venv/
__pycache__/

If you decide to use a .env file locally, make sure it is ignored by Git.

Step 28: Be Careful With Sensitive Files

A file-analysis agent can potentially process sensitive information.

That means you should think carefully before uploading things such as:

  • Medical records

  • Financial information

  • Passwords

  • Private company documents

  • Personal identification documents

  • Confidential school records

Your application's privacy requirements depend on the type of data you're handling.

Don't treat an AI API as a place to casually upload every document on your computer.

Understand the provider's current data controls, retention behavior, and policies before deploying a file-processing application with sensitive information. OpenAI documents file retention and data controls in its platform documentation.

Common Mistakes that Developers Make

Common Mistake #1: Putting the API Key in GitHub

Never do:

api_key = "your-secret-key"

and commit it.

Use environment variables instead.

Common Mistake #2: Assuming the AI Knows Everything in the File

Just because you upload a file doesn't mean your application can magically solve every possible question.

The model's ability to analyze a file depends on:

  • File type

  • File size

  • File structure

  • Model capabilities

  • API limits

  • The quality of your instructions

  • The complexity of the question

Design your application around those limitations.

Common Mistake #3: Telling the Model to "Just Analyze It"

This:

Analyze the file.

is extremely vague.

This is better:

Identify the main argument, summarize the evidence,
explain the methodology, and identify the limitations.

Clear instructions produce a clearer task.

Common Mistake #4: Ignoring Hallucinations

AI models can generate incorrect information.

That is why our instructions include:

Do not invent information.

and:

If the file does not contain enough information, say so.

You should still validate important information yourself.

For high-stakes applications, you need stronger evaluation and verification systems.

Common Mistake #5: Sending Huge Amounts of Data Everywhere

If you have thousands of documents, don't simply throw all of them into every request.

That is when retrieval systems become useful. Search first. Then give the model the most relevant information.

Common Mistake #6: Building Everything at Once

A common beginner mistake is starting with:

React
FastAPI
LangChain
PostgreSQL
Pinecone
Docker
Kubernetes
OpenAI
Authentication
RAG
Agents

all at the same time.

Please don't.

You will spend more time debugging infrastructure than learning AI.

Start with:

Python
+
OpenAI API
+
File

Get that working.

Then add features one at a time.

How the Final Program Works

Let's summarize our program from beginning to end.

The user runs:

python agent.py

The program asks:

Enter the path to your file:

The user enters:

research.pdf

Python checks whether the file exists.

Then the application uploads it:

client.files.create(...)

The API returns a file ID. The application stores that ID.

Then the user asks:

What is the main argument?

Our application sends:

Instructions
+
Question
+
File

to the model.

The model analyzes the information.

Then our program prints:

response.output_text

The user receives the answer.

And that's the core of a file-analysis AI agent.

The Most Important Code to Remember

If you forget everything else, remember this structure:

from openai import OpenAI


client = OpenAI()


with open("research.pdf", "rb") as file:
    uploaded_file = client.files.create(
        file=file,
        purpose="user_data"
    )


response = client.responses.create(
    model="gpt-5",
    instructions="Analyze the uploaded file carefully.",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "What is the main argument?"
                },
                {
                    "type": "input_file",
                    "file_id": uploaded_file.id
                }
            ]
        }
    ]
)


print(response.output_text)

The important mental model is:

Open file
    ↓
Upload file
    ↓
Get file ID
    ↓
Send question + file ID
    ↓
Model analyzes file
    ↓
Print answer

Once you understand this flow, you can build much more complicated applications on top of it.

What You Can Build With This

This simple project can become the foundation for many real applications.

AI Research Assistant

Upload academic papers and ask:

What is the research question?

What methodology was used?

What were the main findings?

Résumé Analyzer

Upload a résumé and ask:

What skills are missing for this job?

Study Assistant

Upload a textbook chapter and ask:

Explain this chapter in beginner-friendly language.

Upload a document and ask questions about its contents, while carefully considering privacy, accuracy, and appropriate legal safeguards.

Business Report Analyzer

Upload a report and ask:

What are the most important trends?

Data Analysis Assistant

Upload a dataset and eventually give the agent access to Python-based analysis tools.

The possibilities are huge.

Final Thoughts

Building an AI agent that can read files sounds complicated at first.

But when you break it down, the core idea is surprisingly simple.

  1. Your Python application does the setup.

  2. The API provides access to the AI model.

  3. The file provides the information.

  4. The instructions define the agent's job.

  5. The user provides the question.

  6. The model analyzes the information and generates the response.

The really interesting part is what happens next.

Once you understand how to give an AI model access to files, you can start adding retrieval, tools, databases, web search, memory, user interfaces, and multi-step workflows.

That's where simple AI scripts start turning into actual AI applications.

And the best part? You don't need to understand every piece of AI before you start building.

Start small and get one file working. Ask one question. Understand what every line of code does. Then add the next feature.

That's how you go from: "I want to build an AI agent" to "I actually built one".

Happy coding!

]]> <![CDATA[ How to Fix a Leaked API Key: A Developer’s Guide to Git Security ]]> https://www.freecodecamp.org/news/how-to-fix-a-leaked-api-key/ 6a8ddd55902e76128f1985bb Tue, 25 Aug 2026 18:22:13 +0000 Imagine this: you're working late, your code finally works, and you're ready to push it to GitHub.

You run:

git add .
git commit -m "Fix API integration"
git push

A few minutes later, you notice something strange. Your API usage has suddenly increased. Maybe there are unexpected requests, new cloud resources, or even a bill that looks much larger than expected.

Then you find it:

const apiKey = "sk_live_123456789";

Your API key is sitting in a Git repository.

This situation is stressful, but it's fixable.

The most important rule is:

If an API key has been committed to Git, assume it has been copied and compromised, even if you delete it immediately.

Deleting the key from the latest version of your file doesn't make the old key safe. Git keeps previous versions of files in its history, and exposed credentials can be discovered by automated scanners.

In this guide, you'll learn the following:

We'll use this basic workflow throughout the article:

Invalidate → Investigate → Remove → Replace → Prevent

Let's start with what an API key actually is before we get to the most important part: what to do right now after a key is exposed.

What Is an API Key?

An API key is a credential that allows an application to communicate with another service.

For example, an application might use an API key to access:

  • A weather service

  • A payment provider

  • A mapping service

  • An artificial intelligence API

  • A cloud platform

  • A database

  • An email provider

  • A private company API

A key might look something like this:

const apiKey = "your-real-api-key";

Or it might appear in a configuration file:

{
  "apiKey": "your-real-api-key",
  "databasePassword": "your-real-password"
}

API keys are often called secrets because possessing one may allow someone to make requests, access data, create resources, or generate charges on your account.

Not every API key is equally sensitive. Some services provide browser keys that are intentionally visible to users. Those keys should still have appropriate restrictions, quotas, and permissions.

As a general rule:

If a credential can access private data, create resources, modify records, or generate charges, it shouldn't be stored directly in your source code.

The Emergency Response: What to Do First

When you discover a leaked credential, a common reaction is to delete the key from the file and push another commit.

Don't start there.

Your first priority is to make the leaked credential useless.

Use this order of operations:

1. Invalidate the leaked credential
2. Investigate suspicious activity
3. Remove the secret from your code
4. Replace it with a new credential
5. Clean the Git history if necessary
6. Verify the cleanup
7. Add protections against future leaks

Think of an API key like a house key that was dropped in a crowded street.

Deleting a picture of the key doesn't matter if someone already picked up the physical key.

Change the lock first.

Step 1: Revoke or Rotate the Leaked Key

Go to the dashboard of the service that issued the credential.

Depending on the provider, you may see options such as:

  • Revoke

  • Delete

  • Disable

  • Rotate

  • Regenerate

  • Create new key

If the provider supports key rotation, create a replacement credential before disabling the old one if possible. This can reduce application downtime while you update your configuration.

The important thing is that the original credential must no longer be usable.

Do not reuse the leaked key. Don't rename it. Don't encode it. Don't move it to another file and assume it is safe. Don't assume nobody saw it.

Treat it as compromised.

Step 2: Investigate Suspicious Activity

After disabling the credential, check the provider's usage dashboard and logs.

Look for things such as:

  • Sudden spikes in requests

  • Requests from unfamiliar locations

  • Unexpected database queries

  • New cloud resources

  • Changes to permissions

  • Unexpected downloads

  • Unusual payment activity

  • New deployments

  • Requests at times when your application was inactive

If the credential had broad permissions, assume that anything within its permission scope MAY have been accessed or modified.

For example, if a cloud credential could create virtual machines, check whether unexpected machines were created.

If a credential could access a database, review:

  • Authentication logs

  • Read operations

  • Write operations

  • Deleted records

  • Exported data

  • Newly created accounts

  • Permission changes

Also check your billing information if the credential could generate usage-based charges.

Write down what you discover. A simple timeline can help:

10:15 - API key committed
10:23 - Repository pushed publicly
10:41 - Unusual usage detected
10:45 - Key revoked
11:00 - Logs reviewed
11:30 - Replacement key deployed
12:00 - Git history cleaned

This can be especially useful if you need to report the incident to a team or service provider.

Step 3: Remove the Secret From Your Current Code

Once the original credential has been disabled, remove it from your working files.

This is unsafe:

const apiKey = "your-real-api-key";

Instead, load the credential from the environment:

const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error("API_KEY is not configured");
}

In Python:

import os

api_key = os.environ.get("API_KEY")

if not api_key:
    raise RuntimeError("API_KEY is not configured")

The important idea is simple:

Source code → environment variable → secret value

instead of:

Source code → hardcoded secret

Environment variables aren't the only way to manage secrets, but they are a common and practical solution for local development and many deployment environments.

Step 4: Use a .env File for Local Development

For local development, you can store environment variables in a .env file.

For example:

API_KEY=your-local-development-key
DATABASE_URL=your-local-database-url

A Node.js project can load these values with a package such as dotenv.

Install it with:

npm install dotenv

Then:

import "dotenv/config";

const apiKey = process.env.API_KEY;

The important part is that the .env file normally should not be committed to Git.

Add it to .gitignore:

# Environment files
.env
.env.*
!.env.example

# Credential files
*.pem
*.key
credentials.json
service-account.json

# Local development files
.DS_Store

But there's an important detail here: the .gitignore does NOT remove files that Git is already tracking.

If .env has already been committed, adding it to .gitignore won't erase it from Git.

You can stop tracking the file while keeping it on your computer:

git rm --cached .env

Then commit the .gitignore change:

git add .gitignore
git commit -m "Ignore local environment files"

But remember: this only removes the file from future commits. It does not remove the secret from previous commits.

That's where Git history comes in.

Step 5: Create a Safe .env.example

Other developers still need to know which environment variables the application requires.

Instead of committing .env, create .env.example:

API_KEY=
DATABASE_URL=
PORT=3000
LOG_LEVEL=info

This file contains variable names rather than real credentials, so it can be committed to the repository.

You can also provide comments:

# Required API credential
API_KEY=

# PostgreSQL connection string
DATABASE_URL=

# Optional application port
PORT=3000

A new developer can then copy the file:

cp .env.example .env

and provide their own values.

Use clearly fake placeholders in examples:

API_KEY=replace-me-with-your-own-key

Avoid putting realistic-looking production credentials into .env.example.

Step 6: Determine Whether the Secret Is Still in Git History

This is one of the most important parts of fixing a leaked credential.

Suppose your Git history looks like this:

Commit A: Add API key to config.js
Commit B: Update API integration
Commit C: Delete API key

Even though Commit C no longer contains the key, Commit A still does.

Git remembers previous versions of your files.

You can inspect the history of a file with:

git log --all -- config.js

To display a file from an older commit:

git show COMMIT_ID:config.js

You can also search Git history for a known leaked value:

git log --all -S"your-leaked-key" --oneline

If you know the secret was committed, you should assume that it exists somewhere in the repository's history until you've verified otherwise.

When Do You Need to Rewrite Git History?

Not every accidental secret requires a history rewrite. Consider these situations:

The Secret Was Never Committed

If the secret exists only in your working directory and was never committed, you generally don't need to rewrite history.

Remove it, add the appropriate file to .gitignore, and continue.

The Secret Was Committed Locally But Never Pushed

If the secret exists in local commits but hasn't been shared with a remote repository, you may be able to clean up those commits before pushing.

The Secret Was Pushed to a Remote Repository

Treat the credential as compromised. Revoke or rotate it immediately.

Then determine whether removing the secret from the repository's history is appropriate.

The Repository Was Public

Assume that someone or something may already have copied the secret.

This is why revocation comes before Git cleanup.

The Secret Was in a Private Repository

A private repository is safer than a public repository, but it isn't a secret vault.

Credentials can still escape through:

  • Compromised accounts

  • Contractors

  • Integrations

  • CI logs

  • Forks

  • Backups

  • Screenshots

  • Copied code

  • Pull requests

So the safest rule remains:

Never intentionally commit credentials to Git, even in a private repository.

Step 7: Remove the Secret From Git History

If the credential was committed, you may need to remove it from the repository's history.

Before rewriting history, create a backup:

git clone --mirror https://github.com/your-username/your-repository.git repository-backup.git

A mirror clone includes branches and tags, which makes it useful for recovery if something goes wrong.

Option 1: Remove an Entire File

If the secret was stored in a file such as .env, you can remove that file from the entire history:

git filter-repo --path .env --invert-paths

For a file inside a directory:

git filter-repo --path config/production.json --invert-paths

This removes the file from the repository's rewritten history.

Option 2: Replace a Secret Inside a File

Sometimes you need to keep the file but remove the secret from previous versions.

Create a temporary replacements file:

Then run:

git filter-repo --replace-text replacements.txt

You can replace the value with a placeholder:

your-leaked-key==>YOUR_API_KEY_HERE

Be extremely careful with replacements.txt. It contains the original secret, so do not commit it.

Delete it after the cleanup:

rm replacements.txt

On Windows PowerShell:

Remove-Item replacements.txt

For multiple secrets:

old-api-key==>REMOVED_API_KEY
old-database-password==>REMOVED_DATABASE_PASSWORD
old-token==>REMOVED_TOKEN

Then:

git filter-repo --replace-text replacements.txt

Test the cleanup on your backup clone first.

Step 8: Verify That the Secret Is Gone

Never assume the cleanup worked just because the command completed successfully.

Search for the known leaked value again:

git log --all -S"your-leaked-key" --oneline

You can also inspect relevant files and commits:

git log --all -- config.js

and:

git show COMMIT_ID:config.js

If your repository uses branches and tags, make sure you aren't checking only the branch you currently have checked out.

You should also inspect other locations where the secret may have appeared, including pull requests, CI/CD logs, build artifacts, release files, Docker images, package releases, documentation, issue comments, and screenshots

Remember:

Rewriting your repository doesn't erase copies that already exist somewhere else.

That's another reason why the original credential must be revoked.

Step 9: Push the Cleaned History Carefully

Once you've verified the cleanup, you may need to push the rewritten history:

git push --force --all origin
git push --force --tags origin

Important Warning

Force-pushing rewritten history is disruptive. It changes commit hashes and can affect collaborators who have existing clones of the repository.

Before doing this on a shared project:

  1. Tell your collaborators.

  2. Make sure everyone understands that history is being rewritten.

  3. Coordinate the cleanup.

  4. Follow your organization's incident-response process if one exists.

After the rewrite, collaborators may need to reclone the repository:

git clone https://github.com/your-username/your-repository.git

They shouldn't blindly merge their old repository history back into the cleaned repository.

Step 10: Replace the Credential Everywhere

Now create or use the replacement credential. Update every environment where the application runs. Common locations include:

  • Local development

  • Testing

  • Staging

  • Production

  • Docker containers

  • Kubernetes secrets

  • CI/CD systems

  • Hosting platforms

  • Scheduled jobs

  • Serverless functions

A common mistake is updating production but forgetting the deployment pipeline.

For example, your local application may work because .env contains the new key, while your CI/CD system still contains the old one.

Make a checklist:

1. Local development
2. Automated tests
3. Staging
4. Production
5. CI/CD variables
6. Docker configuration
7. Cloud deployment settings
8. Scheduled scripts
9. Serverless functions

After updating the credential, test the application in each important environment.

Step 11: Restrict the Replacement Key

Replacing a leaked credential is only part of the solution.

The new credential should have only the permissions it actually needs.

Useful restrictions can include:

  • Read-only permissions

  • Specific API scopes

  • Allowed IP addresses

  • Allowed domains

  • Environment-specific access

  • Request quotas

  • Rate limits

  • Expiration dates

For example, a weather application may only need permission to read weather data.

It shouldn't have permission to manage users, modify billing, or delete unrelated resources.

This is the principle of least privilege:

Give each credential the smallest amount of access necessary to perform its job.

It's also a good idea to use different credentials for different environments:

local-development-key
testing-key
staging-key
production-key

That way, a development credential leak doesn't automatically expose production resources.

What About Frontend Applications?

This is where API-key security gets confusing.

Frontend code runs on the user's device.

That means users can inspect it.

For example:

const apiKey = "browser-key";

A user can inspect the JavaScript bundle, browser developer tools, or network requests and potentially see the value.

Some services intentionally provide browser API keys that are designed to be publicly visible.

Those keys should still be restricted by things such as:

  • Allowed domains

  • Website origins

  • API operations

  • Usage quotas

  • Referrer restrictions

  • Time limits

But a truly private credential should never be placed in browser code.

Instead of:

fetch("https://private-api.example.com/data", {
  headers: {
    Authorization: "Bearer private-secret-token"
  }
});

have the browser call your own backend:

fetch("/api/data");

Then the backend communicates with the private service:

const response = await fetch(
  "https://private-api.example.com/data",
  {
    headers: {
      Authorization: `Bearer ${process.env.PRIVATE_API_TOKEN}`
    }
  }
);

The backend can then return only the information the browser is allowed to receive.

The important distinction is:

Public/browser credential
        ↓
Can be visible, but should be restricted

Private credential
        ↓
Must remain on a trusted backend or secret-management system

Environment Variables vs Secret Managers

Environment variables are useful, but they're not a universal secret-management solution.

For a small application or local development environment, something like:

API_KEY=your-secret

may be perfectly reasonable.

For larger production systems, you may want a dedicated secret manager.

A secret-management system can provide features such as:

  • Centralized credential storage

  • Access controls

  • Auditing

  • Credential rotation

  • Versioning

  • Separation between environments

  • Integration with deployment systems

The important idea is that your source code shouldn't be responsible for storing production secrets.

Instead:

Application
    ↓
Secret management system
    ↓
Credential

rather than:

Application
    ↓
Hardcoded production credential

Which solution you use depends on the size and requirements of your project.

Add Secret Scanning to Your Workflow

Humans are excellent programmers and occasionally terrible search engines.

Automated secret scanning can catch credentials before they make it into a repository.

Popular tools include:

  • Gitleaks

  • TruffleHog

  • detect-secrets

  • Pre-commit hooks

  • Git hosting secret scanning

  • CI security scanners

For example, you can run Gitleaks locally:

gitleaks detect --source . --verbose

You can also integrate secret scanning into CI.

A basic GitHub Actions workflow might look like this:

name: Secret Scan

on:
  push:
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Scan for secrets
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Review the documentation for your chosen tool and pin versions according to your project's security practices.

Secret scanners can produce false positives, so you may need to configure exceptions for safe test values.

Be careful with allowlists, though. An overly broad exception can hide a real credential.

Use Git Hooks as an Extra Safety Net

You can also scan files before they're committed.

For example, a simple pre-commit script could search for suspicious words:

#!/usr/bin/env bash

if grep -RniE "api[_-]?key|password|secret|token|private[_-]?key" . \
  --exclude-dir=.git \
  --exclude=".env.example"; then

  echo "Possible secret detected. Commit cancelled."
  exit 1
fi

This isn't a complete security scanner, but it can catch obvious mistakes.

For stronger protection, use a dedicated secret-scanning tool through a pre-commit framework.

The goal isn't to make committing miserable. The goal is to make accidentally publishing a credential harder.

Review Your Staged Diff Before Committing

One of the simplest security habits you can develop is checking what you're actually about to commit.

First:

git status

Then stage only the files you intend to commit:

git add src/api.js README.md

Now inspect the staged changes:

git diff --cached

Look for:

  • API keys

  • Passwords

  • Tokens

  • Private URLs

  • Internal hostnames

  • Customer data

  • Debug output

  • Personal information

  • Private certificates

Only commit after the staged diff looks correct:

git commit -m "Load API key from environment"

Be cautious with:

git add .

It can stage files you never intended to publish, including .env files, database exports, generated files, or local configuration.

Common Mistakes Developers Make

Mistake 1: "I Deleted It, So It's Fine"

Deleting a secret from the current version of a file doesn't delete it from Git history.

Correct response: Revoke the credential and clean the repository history when appropriate.

Mistake 2: "The Repository Is Private"

Private repositories aren't vaults.

Credentials can still escape through compromised accounts, integrations, CI logs, forks, backups, or copied code.

Correct response: Don't commit secrets even to private repositories.

Mistake 3: "I'll Just Encode It"

These don't make a credential secret:

const key = atob("c29tZS1rZXk=");

or:

const key = "some-" + "secret-" + "value";

Encoding, splitting, renaming, or hiding a credential doesn't protect it.

If your application can reconstruct the credential, someone analyzing the application may be able to do the same.

Mistake 4: Logging the Secret

Don't do this:

console.log(process.env.API_KEY);

Logs can be stored by your terminal, CI system, hosting provider, monitoring platform, or cloud service.

Instead:

console.log(
  "API key configured:",
  Boolean(process.env.API_KEY)
);

If you absolutely need to inspect a value during debugging, avoid printing the full credential.

For example:

function maskSecret(value) {
  if (!value) return "not configured";
  if (value.length <= 8) return "********";

  return `${value.slice(0, 4)}...${value.slice(-4)}`;
}

console.log(maskSecret(process.env.API_KEY));

Even masked credentials should be handled carefully.

Mistake 5: Using the Same Credential Everywhere

If local development, testing, staging, and production all use the same credential, one leak can affect everything.

Correct response: Use separate credentials with separate permissions.

Mistake 6: Cleaning Only the Current Branch

A secret can remain in:

  • Old branches

  • Tags

  • Pull requests

  • Other references

Correct response: Consider the entire repository when investigating and cleaning a leaked credential.

Mistake 7: Forgetting Build Artifacts

A secret might also appear in:

  • Compiled JavaScript bundles

  • Docker images

  • Downloadable releases

  • Published packages

  • Generated documentation

Correct response: Revoke the credential and identify affected artifacts that may need to be removed or replaced.

A Complete API-Key Incident Checklist

If you discover that you've exposed an API key, use this checklist:

1. Revoke or rotate the leaked key
2. Create a replacement credential
3. Restrict the replacement credential
4. Review provider logs
5. Review billing and usage
6. Check for unauthorized resources
7. Remove the key from current files
8. Add secret files to .gitignore
9. Create or update .env.example
10. Search Git history
11. Check branches and tags
12. Remove the secret from Git history if necessary
13. Verify the old secret is gone
14. Force-push cleaned history if appropriate
15. Check pull requests and forks
16. Check CI and deployment logs
17. Update local configuration
18. Update staging configuration
19. Update production configuration
20. Update CI/CD secrets
21. Run a secret scanner
22. Document the incident
23. Add preventive security checks

The exact steps will depend on your provider and project, but the order matters: Invalidate first. Clean up second.

A Secure Project Structure

A simple Node.js project might look like this:

my-project/
├── src/
│   └── api.js
├── .env
├── .env.example
├── .gitignore
├── package.json
└── README.md

The local .env file contains the actual development value:

API_KEY=your-local-key

The .env.example file contains no real credential:

API_KEY=replace-me-with-your-own-key

The application reads the environment variable:

import "dotenv/config";

const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error("Missing API_KEY environment variable");
}

export async function getData() {
  const response = await fetch(
    "https://api.example.com/data",
    {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    }
  );

  if (!response.ok) {
    throw new Error(
      `API request failed: ${response.status}`
    );
  }

  return response.json();
}

And .gitignore keeps the local environment file out of future commits:

.env
.env.*
!.env.example

node_modules/

Finally, your README can explain the setup without exposing credentials:

Step 1: Copy the example environment file on your bash cp .env.example .env

Step 2: Add your own API key to .env.

And last but not least, start your application!

npm start

Final Thoughts

Leaking an API key doesn't mean you're a terrible developer. It just means your development workflow needs better guardrails.

The important thing is knowing how to respond quickly and how to prevent the same mistake from happening again.

Remember the emergency formula:

Invalidate → Investigate → Remove → Replace → Prevent

The important thing is knowing how to respond quickly and how to prevent the same mistake from happening again.

  • Invalidate the leaked credential so it can no longer be used.

  • Investigate your logs, usage, and billing to determine whether it was abused.

  • Remove the secret from your current code and, when necessary, from Git history.

  • Replace it with a new credential that has only the permissions it needs.

  • Prevent future leaks with environment variables, secret managers, secret scanning, and careful Git practices.

Git is excellent at remembering your project's history. That's useful when you accidentally delete an important function. But it's much less useful when that history contains a password.

So keep your code public when appropriate. And keep your secrets somewhere else.

Happy coding!

]]> <![CDATA[ Neural Networks Explained: What They Are and How to Build One in Python ]]> https://www.freecodecamp.org/news/neural-networks-explained-simply-in-python/ 6a88c8b8c9a055790ae586e7 Fri, 21 Aug 2026 21:52:56 +0000 Have you ever wondered how a computer can recognize a handwritten number, predict whether an email is spam, recommend a video, or understand a sentence?

A lot of modern AI systems rely on something called a neural network.

Now, the name can make them sound much more complicated than they really are. You might imagine that you need advanced calculus, a huge computer, and thousands of lines of code to build one.

You don't.

At its most basic level, a neural network is a mathematical model that takes some numbers as input, performs calculations on those numbers, makes a prediction, checks how far that prediction was from the correct answer, and then adjusts itself so it can do a little better next time.

In this tutorial, we're going to build one ourselves using Python and NumPy.

Here's What We'll Cover:

We'll start with a single artificial neuron, then gradually put together a complete neural network. By the end, you'll understand what weights and biases are, what activation functions do, how a network learns from its mistakes, what backpropagation and gradient descent actually mean, and how all of those pieces fit together.

You don't need to know advanced machine learning to follow along. Some basic Python and algebra will help, but I'll explain the important math as we go.

1. What Is a Neural Network?

Let's start with a simple example.

Imagine that we want a computer to predict whether a student will pass an exam.

We could give the computer information such as:

  • How many hours the student studied

  • How many practice questions they completed

  • Their previous test score

For example:

Study Hours = 5 Practice Questions = 80 Previous Score = 82

We also know whether the student actually passed:

Passed = 1

After seeing many examples like this, we want the computer to learn a pattern.

Maybe students who study more tend to perform better. Maybe previous test scores are useful. Maybe practice questions are helpful, too.

Instead of writing all of those rules ourselves, we can give the examples to a neural network and let it learn the relationships.

The basic idea looks like this:

Visual idea about how a neural network works

The prediction could be something like: 0.92

If we're predicting the probability of passing, we could interpret that as approximately a 92% predicted chance of passing.

The important thing is that we didn't tell the network that...

"Study hours are important, and previous scores are slightly more important."

Instead, the network learns numbers called weights that determine how strongly different inputs affect its predictions.

2. Why Are They Called Neural Networks?

The name comes from biological brains.

Your brain contains neurons that receive signals, process information, and pass signals to other neurons.

Artificial neural networks are not artificial brains. They don't work exactly like biological neurons. But the general idea of connecting many simple processing units inspired the name.

A very simplified artificial neuron looks like this:

Input and Output through a neural network

The neuron receives numbers, performs some mathematical operations, and produces another number.

A neural network is made by connecting many of these artificial neurons together.

3. The Three Main Parts of a Neural Network

A simple neural network can be divided into three types of layers:

  1. Input Layer

  2. Hidden Layer(s)

  3. Output Layer

Let's look at each one.

The Input Layer

The input layer contains the information we give the network.

For our student example, we could have three inputs:

Input 1 = Study Hours
Input 2 = Practice Questions
Input 3 = Previous Score

So one student's input might look like:

[5, 80, 82]

The network doesn't necessarily understand that these numbers mean "study hours" or "test score." To the mathematical part of the network, they're simply numbers.

That's an important idea to remember:

Neural networks work with numbers.

Images, text, audio, and other information must eventually be represented as numbers before a neural network can process them.

Hidden Layers

After the input layer come the hidden layers.

A network might look like:

Image showing how data moves from the Input Layer to the Hidden Layer and then to the Output layer

The hidden layer contains neurons that perform calculations on the inputs.

A network can have one hidden layer or many hidden layers.

When a network has many layers, we often call it a deep neural network.

The Output Layer

The output layer produces the final result.

For a simple yes/no problem, we might represent the answers as:

0 = No
1 = Yes

For example:

0.12 → probably No
0.91 → probably Yes

For a problem with multiple categories, the output could contain several numbers:

Cat  = 0.05
Dog  = 0.90
Bird = 0.05

The largest value is associated with "Dog," so the model would predict Dog.

4. What Is a Neuron?

Now let's zoom in on one neuron.

Suppose our neuron receives three inputs:

x₁
x₂
x₃

Each input has a corresponding weight:

w₁
w₂
w₃

The neuron multiplies each input by its weight and adds the results together.

It also adds something called a bias.

The equation is:

z = x₁w₁ + x₂w₂ + x₃w₃ + b

Don't worry if that equation looks intimidating.

It's basically just:

input × weight
+
input × weight
+
input × weight
+
bias

Let's use actual numbers.

Suppose:

x₁ = 2
x₂ = 3
x₃ = 4

w₁ = 0.5
w₂ = 0.2
w₃ = 0.8

b = 1

Then:

z = (2 × 0.5) + (3 × 0.2) + (4 × 0.8) + 1

Calculate each part:

2 × 0.5 = 1.0
3 × 0.2 = 0.6
4 × 0.8 = 3.2

Now add them:

z = 1.0 + 0.6 + 3.2 + 1
z = 5.8

The neuron has produced 5.8.

But we're not finished yet.

5. What Is a Weight?

A weight controls how strongly an input affects a neuron.

Imagine we have:

x = 5

If the weight is:

w = 2

then:

x × w = 5 × 2
      = 10

But if the weight is:

w = 0.1

then:

x × w = 5 × 0.1
      = 0.5

The same input produced a very different result because the weight changed.

You can think of a weight as a volume knob.

A large positive weight makes an input have a stronger positive influence. A weight close to zero makes the input have little influence. A negative weight can push the result in the opposite direction.

The network learns these weights during training.

6. What Is a Bias?

The bias is another number added to the neuron's calculation.

Without the bias, we would have:

z = x₁w₁ + x₂w₂ + x₃w₃

With the bias:

z = x₁w₁ + x₂w₂ + x₃w₃ + b

Why add another number? Because it gives the neuron more flexibility.

Think of it like adjusting the starting point of the neuron's calculation.

The network learns the bias during training just like it learns the weights.

So when you see:

weights + bias

you're looking at some of the parameters the neural network can change while it learns.

7. Why Do We Need Activation Functions?

At this point, our neuron can calculate a weighted sum:

z = x₁w₁ + x₂w₂ + ... + b

But neural networks need to learn more complicated relationships than simple weighted sums.

That's where activation functions come in. An activation function takes the neuron's calculated value and transforms it.

One common activation function is ReLU. ReLU stands for Rectified Linear Unit.

Its equation is:

ReLU(x) = max(0, x)

In simple terms:

  • If the number is positive, keep it.

  • If the number is negative, turn it into zero.

For example:

ReLU(-5) = 0
ReLU(-2) = 0
ReLU(0)  = 0
ReLU(3)  = 3
ReLU(10) = 10

In Python:

def relu(x):
    return max(0, x)

With NumPy arrays, we can use:

def relu(x):
    return np.maximum(0, x)

Activation functions are important because they allow neural networks with multiple layers to learn more complicated patterns.

8. Building Our First Neuron in Python

Let's turn the math into Python.

First, import NumPy:

import numpy as np

NumPy gives us tools for working with numbers, arrays, vectors, and matrices.

Now let's create our inputs:

x = np.array([2, 3, 4])

This creates an array containing three values:

[2, 3, 4]

Now create the weights:

weights = np.array([0.5, 0.2, 0.8])

We have one weight for each input:

x₁ = 2    w₁ = 0.5
x₂ = 3    w₂ = 0.2
x₃ = 4    w₃ = 0.8

Next, create the bias:

bias = 1

Now we calculate the weighted sum:

z = np.dot(x, weights) + bias

np.dot() performs the multiplication-and-addition operation we described earlier.

In this case:

np.dot(x, weights)

is equivalent to:

(2 × 0.5) + (3 × 0.2) + (4 × 0.8)

which equals:

4.8

Then we add the bias:

4.8 + 1 = 5.8

Now apply ReLU:

output = np.maximum(0, z)

Since z is 5.8, ReLU leaves it unchanged:

output = 5.8

Finally:

print(output)

prints:

5.8

So our entire neuron is:

import numpy as np

x = np.array([2, 3, 4])
weights = np.array([0.5, 0.2, 0.8])
bias = 1

z = np.dot(x, weights) + bias
output = np.maximum(0, z)

print(output)

We have just created a tiny artificial neuron.

9. From One Neuron to a Layer

One neuron isn't enough for most interesting problems.

Instead, we can connect several neurons together.

For example:

Input, Output and Hidden Layer depicted with neurons

Those neurons together form a layer.

A small neural network might look like:

Input Layer
     ↓
Hidden Layer
     ↓
Output Layer

Every neuron in one layer can send its output to neurons in the next layer.

This is where neural networks start becoming much more powerful.

10. How Does a Neural Network Actually Learn?

So far, we've manually chosen the weights:

0.5
0.2
0.8

But a real neural network doesn't start out knowing the correct weights.

Instead, it starts with weights that are usually initialized to small random values.

Then it goes through a cycle:

Make a prediction
       ↓
Compare prediction with correct answer
       ↓
Measure the error
       ↓
Figure out how to change the weights
       ↓
Update the weights
       ↓
Try again

This process happens over and over, and the network gradually adjusts its parameters to make better predictions on the training data.

Let's break each part down.

11. Predictions and Loss

Suppose the correct answer is:

1

but our network predicts:

0.3

The prediction isn't very close to the target.

We need a way to measure how wrong it is. That's what a loss function does.

A loss function takes the prediction and the correct answer and produces a number representing the model's error.

For a simple example, we could use squared error:

Loss = (prediction - actual)²

Using our numbers:

Loss = (0.3 - 1)²

First:

0.3 - 1 = -0.7

Then square it:

(-0.7)² = 0.49

So:

Loss = 0.49

Generally, a smaller loss means the prediction is closer to the target.

In real neural networks, different problems use different loss functions. For binary classification, binary cross-entropy is commonly used.

12. What Are Gradients?

Now we have a problem.

We know that the prediction was wrong, but how should we change the weights?

This is where gradients become useful. A gradient tells us how changing a parameter would affect the loss.

You can think of it like standing on a hill. Imagine that your goal is to reach the lowest point. If you know which direction slopes upward, you can move in the opposite direction to go downhill.

Training a neural network works with a similar idea. We want to reduce the loss. The gradients give us information about which direction the parameters should move.

13. What Is Gradient Descent?

Gradient descent is the process of using gradients to adjust the network's parameters.

A simplified update rule is:

new weight = old weight - learning rate × gradient

In Python:

weight = weight - learning_rate * gradient

The learning rate controls how large the update is.

For example:

learning_rate = 0.01

If the learning rate is too large, the network can make huge changes and potentially jump around instead of settling on a good solution.

If it's too small, learning can take a very long time.

So training involves finding parameter updates that move the model toward lower loss without making the process unstable.

14. What Is Backpropagation?

There's still one important question:

If a neural network has thousands or millions of weights, how does it figure out which weights contributed to the error?

That's where backpropagation comes in. Backpropagation calculates gradients for the parameters by working backward through the network.

Imagine a network like this:

Input
  ↓
Hidden Layer
  ↓
Output
  ↓
Loss

During the forward pass, information moves:

Input → Hidden Layer → Output

During backpropagation, gradient information moves backward:

Loss → Output → Hidden Layer → Input

The network uses these gradients to determine how its weights and biases should change.

You don't normally calculate all of these derivatives by hand when building real neural networks. Libraries such as PyTorch can calculate them automatically.

But understanding the basic idea is important:

Backpropagation calculates how the parameters contributed to the error, and gradient descent uses that information to update them.

15. The Complete Learning Cycle

Now we can put everything together.

Learning cycle of neural network: input, prediction, loss, gradients, update (and then back to prediction...)

More specifically:

Give the network data
          ↓
Calculate a prediction
          ↓
Compare it with the correct answer
          ↓
Calculate the loss
          ↓
Calculate gradients
          ↓
Update weights and biases
          ↓
Repeat

One complete pass through the training data is often called an epoch.

For example:

Epoch 1 → Loss: 0.82
Epoch 2 → Loss: 0.61
Epoch 3 → Loss: 0.43
Epoch 4 → Loss: 0.29
Epoch 5 → Loss: 0.18

These numbers are just an example, but ideally the loss decreases as training progresses.

16. Let's Build a Neural Network From Scratch

Congrats! You now understand the basics of neural networks. Now it's time to put these ideas together.

We're going to build a small neural network using only:

Python + NumPy

Our network will learn a classic machine learning problem called XOR.

XOR is a logical operation with two inputs.

Its rules are:

0 XOR 0 → 0
0 XOR 1 → 1
1 XOR 0 → 1
1 XOR 1 → 0

In other words, the output is 1 when exactly one of the inputs is 1.

Our training data will therefore be:

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

And the correct answers are:

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

We want our neural network to learn this pattern.

17. Understanding the Network Architecture

Our network will contain:

2 input neurons
       ↓
4 hidden neurons
       ↓
1 output neuron

The two inputs represent the two numbers in each XOR example.

The four hidden neurons give the network enough flexibility to learn the XOR relationship.

The output neuron produces a number between 0 and 1.

18. Setting Up the Data

Let's start our Python program.

import numpy as np

This imports NumPy. We'll use NumPy for arrays, matrix multiplication, and mathematical operations.

Next:

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

X contains our four training examples.

Each row is one example:

[0, 0]
[0, 1]
[1, 0]
[1, 1]

Now create the correct answers:

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

The first row of X corresponds to the first row of y.

So:

[0, 0] → 0
[0, 1] → 1
[1, 0] → 1
[1, 1] → 0

19. Creating the Weights and Biases

Now we need the parameters of our network.

First:

np.random.seed(42)

This makes our random numbers reproducible.

Without this line, the network would receive different random starting weights each time we ran the program.

Now create the first layer's weights:

W1 = np.random.randn(2, 4)

Why (2, 4)?

Because:

  • We have 2 input values.

  • We have 4 neurons in the hidden layer.

So W1 needs a weight connecting each input to each hidden neuron.

There are:

2 × 4 = 8

weights.

Next:

b1 = np.zeros((1, 4))

This creates four biases, one for each hidden neuron.

Now the second layer:

W2 = np.random.randn(4, 1)

There are four hidden neurons and one output neuron, so we need:

4 × 1 = 4

weights.

Finally:

b2 = np.zeros((1, 1))

This gives the output neuron one bias.

Our network parameters are therefore:

W1 → input-to-hidden weights
b1 → hidden-layer biases

W2 → hidden-to-output weights
b2 → output-layer bias

20. The Sigmoid Function

Our output represents a probability, so we'd like it to be between 0 and 1.

We can use the sigmoid function.

Its equation is:

sigmoid(x) = 1 / (1 + e⁻ˣ)

In Python:

def sigmoid(x):
    return 1 / (1 + np.exp(-x))

Let's see what it does:

sigmoid(-5) ≈ 0.007
sigmoid(0)  = 0.5
sigmoid(5)  ≈ 0.993

No matter how large or small the input is, the result stays between 0 and 1.

That's useful when our output represents a probability.

21. Forward Propagation

Now we can send the data through the network. This is called forward propagation.

First, calculate the hidden layer:

z1 = X @ W1 + b1

There's a new symbol here:

@

In Python, @ performs matrix multiplication.

You can think of this operation as performing many weighted sums at once.

Instead of manually calculating every neuron:

input × weight + input × weight + bias

NumPy can calculate all of them together.

The result is stored in z1.

Next:

a1 = np.tanh(z1)

Here we're using the tanh activation function for the hidden layer.

Tanh converts its input into values between -1 and 1.

Why use tanh here?

Because XOR isn't something a single simple linear calculation can solve. The nonlinear activation gives the hidden layer the flexibility it needs to learn the pattern.

Now calculate the output layer:

z2 = a1 @ W2 + b2

This takes the hidden layer's outputs and combines them using the second set of weights.

Finally:

a2 = sigmoid(z2)

Now a2 contains our predictions.

For example, before training, the network might produce something like:

0.52
0.61
0.48
0.55

Those predictions aren't useful yet, but that's expected. The network hasn't learned anything yet.

22. Calculating the Loss

Now we need to measure how good those predictions are.

For binary classification, we'll use binary cross-entropy, which is a loss function used in machine learning for binary classification. It measures the performance of a model whose output is a probability value between 0 and 1.

The formula is:

Loss = -mean(
    y × log(prediction)
    +
    (1 - y) × log(1 - prediction)
)

That looks much more complicated than the squared-error example from earlier, but we don't need to memorize the formula.

In Python:

loss = -np.mean(
    y * np.log(a2 + 1e-8) +
    (1 - y) * np.log(1 - a2 + 1e-8)
)

The 1e-8 is a very small number.

It prevents problems if a2 gets extremely close to 0 or 1, because taking the logarithm of exactly zero isn't valid.

At the beginning of training, the loss will probably be relatively high. But as the network learns, we'd like it to decrease.

23. Backpropagation in Code

Now comes the most mathematical part of our program.

We need to calculate the gradients.

Start with:

dz2 = a2 - y

This gives us the gradient of the loss with respect to the output layer's pre-activation value for the sigmoid + binary cross-entropy combination.

Next:

dW2 = (a1.T @ dz2) / len(X)

This calculates the gradient for W2.

The .T means transpose.

Our hidden-layer output has four neurons, while dz2 represents the output layer's error. Matrix multiplication combines them to determine how each hidden-to-output weight contributed to the loss.

We divide by:

len(X)

because we have four training examples and we're calculating the average gradient.

Now calculate the output bias gradient:

db2 = np.mean(dz2, axis=0, keepdims=True)

This calculates the average gradient for the output bias.

Next:

da1 = dz2 @ W2.T

This sends the gradient information backward from the output layer toward the hidden layer.

Now we need to account for the derivative of the tanh activation function.

The derivative of tanh can be written as:

1 - tanh(x)²

Since we already have the hidden layer's activated values in a1, we can write:

dz1 = da1 * (1 - a1**2)

This tells us how the hidden layer's pre-activation values affected the loss.

Now calculate the gradients for the first layer's weights:

dW1 = (X.T @ dz1) / len(X)

And the hidden-layer biases:

db1 = np.mean(dz1, axis=0, keepdims=True)

At this point, we have gradients for all of our trainable parameters.

24. Updating the Weights

Now we use gradient descent.

First:

W2 -= learning_rate * dW2

This updates the second layer's weights.

The -= means:

W2 = W2 - learning_rate * dW2

Then:

b2 -= learning_rate * db2

updates the output bias.

And:

W1 -= learning_rate * dW1

updates the first layer's weights.

Finally:

b1 -= learning_rate * db1

updates the hidden-layer biases.

These updates are what actually allow the network to learn.

25. The Complete NumPy Neural Network

Now let's put everything together.

import numpy as np

# 1. Training data

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

# 2. Initialize parameters

np.random.seed(42)

W1 = np.random.randn(2, 4)
b1 = np.zeros((1, 4))

W2 = np.random.randn(4, 1)
b2 = np.zeros((1, 1))

learning_rate = 0.1

# 3. Activation functions

def sigmoid(x):
    return 1 / (1 + np.exp(-x))

# 4. Training

for epoch in range(10000):

    # Forward propagation

    z1 = X @ W1 + b1
    a1 = np.tanh(z1)

    z2 = a1 @ W2 + b2
    a2 = sigmoid(z2)

    # Calculate loss

    loss = -np.mean(
        y * np.log(a2 + 1e-8) +
        (1 - y) * np.log(1 - a2 + 1e-8)
    )

    # Backpropagation

    dz2 = a2 - y

    dW2 = (a1.T @ dz2) / len(X)
    db2 = np.mean(dz2, axis=0, keepdims=True)

    da1 = dz2 @ W2.T

    dz1 = da1 * (1 - a1**2)

    dW1 = (X.T @ dz1) / len(X)
    db1 = np.mean(dz1, axis=0, keepdims=True)

    # Update parameters

    W2 -= learning_rate * dW2
    b2 -= learning_rate * db2

    W1 -= learning_rate * dW1
    b1 -= learning_rate * db1

    # Display progress

    if epoch % 1000 == 0:
        print(f"Epoch {epoch}, Loss: {loss:.4f}")

Let's go through the program from top to bottom.

Line-by-Line Explanation of the Full Code

Importing NumPy:

import numpy as np

We import NumPy because our network will work with arrays and matrix operations.

Creating the inputs

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

Each row is one XOR example.

There are four examples and two input values per example.

So the shape of X is:

4 × 2

Creating the answers

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

There are four correct answers, one for each row in X.

Making random initialization reproducible

np.random.seed(42)

This makes NumPy generate the same starting random values each time.

The number 42 isn't special. You could use another number.

Creating the first weight matrix

W1 = np.random.randn(2, 4)

This creates a matrix containing random numbers.

Its shape is 2*4

There are two inputs and four hidden neurons.

Creating the first biases

b1 = np.zeros((1, 4))

This creates four zeros:

[0, 0, 0, 0]

There is one bias for every hidden neuron.

Creating the second weight matrix

W2 = np.random.randn(4, 1)

There are four hidden neurons and one output neuron.

Therefore:

4 × 1

weights are needed.

Creating the output bias

b2 = np.zeros((1, 1))

The output layer has one neuron, so it needs one bias.

Setting the learning rate

learning_rate = 0.1

This controls how strongly the gradients affect each update.

Creating sigmoid

def sigmoid(x):
    return 1 / (1 + np.exp(-x))

This converts the output into a value between 0 and 1.

Starting the Training Loop

for epoch in range(10000):

This tells Python to repeat the training process 10,000 times.

Each repetition is an epoch, which is one complete pass of the entire training dataset through a neural network

Calculating the hidden layer

z1 = X @ W1 + b1

This performs the weighted-sum calculation for all four hidden neurons and all four training examples.

Applying tanh

a1 = np.tanh(z1)

This applies the nonlinear activation function to the hidden layer.

Calculating the output layer

z2 = a1 @ W2 + b2

This takes the hidden layer's values and calculates the output neuron's weighted sum.

Applying sigmoid

a2 = sigmoid(z2)

This turns the output into probabilities between 0 and 1.

Calculating the loss

loss = -np.mean(
    y * np.log(a2 + 1e-8) +
    (1 - y) * np.log(1 - a2 + 1e-8)
)

This measures how different the predictions are from the correct answers.

A lower value generally means the predictions are better.

Calculating the output gradient

dz2 = a2 - y

This calculates the gradient needed to update the output layer.

Updating the second-layer weight gradients

dW2 = (a1.T @ dz2) / len(X)

This determines how each weight connecting the hidden layer to the output layer contributed to the loss.

Updating the output bias gradient

db2 = np.mean(dz2, axis=0, keepdims=True)

This calculates the average gradient for the output bias.

Moving backward toward the hidden layer

da1 = dz2 @ W2.T

This passes the gradient information backward through the output layer.

Applying the tanh derivative

dz1 = da1 * (1 - a1**2)

This accounts for the effect of the tanh activation function.

Calculating the first-layer gradients

dW1 = (X.T @ dz1) / len(X)

This determines how the input-to-hidden weights contributed to the loss.

Then:

db1 = np.mean(dz1, axis=0, keepdims=True)

calculates the gradients for the hidden-layer biases.

Updating the parameters

W2 -= learning_rate * dW2
b2 -= learning_rate * db2

W1 -= learning_rate * dW1
b1 -= learning_rate * db1

These four lines are where the network changes what it has learned.

The gradients tell us which direction to move, while the learning rate determines how large the movement should be.

Printing the loss

if epoch % 1000 == 0:
    print(f"Epoch {epoch}, Loss: {loss:.4f}")

The % operator gives us the remainder after division.

So:

epoch % 1000 == 0

is true every 1,000 epochs.

That means we don't print something 10,000 times. Instead, we get occasional updates such as:

Epoch 0, Loss: ...
Epoch 1000, Loss: ...
Epoch 2000, Loss: ...
...

If training is working well, the loss should generally decrease.

26. Testing the Network

After training, we can use the network to make predictions.

z1 = X @ W1 + b1
a1 = np.tanh(z1)

z2 = a1 @ W2 + b2
predictions = sigmoid(z2)

print(predictions)

The network should produce values close to:

[[0],
 [1],
 [1],
 [0]]

The actual values probably won't be exactly 0 and 1.

You might get something more like:

[[0.01],
 [0.98],
 [0.99],
 [0.02]]

That's fine.

The network is producing probabilities.

We can convert those probabilities into classes using a threshold:

classes = (predictions >= 0.5).astype(int)

print(classes)

The result should be:

[[0],
 [1],
 [1],
 [0]]

Our network has learned the XOR pattern.

27. Why Did We Need a Hidden Layer?

You might wonder why we couldn't just connect the two inputs directly to the output.

The reason is that XOR isn't something a single linear layer can represent.

The hidden layer gives the network additional transformations that allow it to learn the more complicated relationship.

This is one of the most important ideas behind neural networks: a network doesn't necessarily learn one giant rule. Instead, different layers can transform information step by step.

For an image recognition system, you can imagine a simplified process like:

Image recognition system visually depicted

Real neural networks don't literally create neat layers called "edges," "shapes," and "objects." This is just an intuition for how increasingly complex representations can emerge through multiple layers.

28. What Happens in a Larger Neural Network?

The network we built is tiny. Modern neural networks can have millions, billions, or even more parameters.

A simplified network might look like:

Simplified neural network visually depicted

Each connection can have its own weight.

The more neurons and connections a network has, the more parameters it may need to learn.

Large models therefore require significant amounts of computing power and memory.

But remember the basic process:

Input
 ↓
Calculations
 ↓
Prediction
 ↓
Loss
 ↓
Gradients
 ↓
Parameter Updates

The size of the network changes dramatically, but the basic training idea remains.

29. Do You Have to Build Neural Networks From Scratch?

No. Building a neural network from scratch is useful for learning because it forces you to understand what's happening underneath the libraries.

But you normally wouldn't manually calculate every gradient when building a real machine learning application.

That's where machine learning frameworks come in. Some commonly used Python libraries include:

  • NumPy

  • PyTorch

  • TensorFlow

  • Keras

  • scikit-learn

For deep learning, PyTorch is one of the most commonly used frameworks. It can automatically calculate gradients and handle many of the mathematical operations involved in training.

30. Building the Same Network With PyTorch

Let's see how much shorter the network becomes with PyTorch.

First, install it:

pip install torch

Then import it:

import torch
import torch.nn as nn

Now create the model:

model = nn.Sequential(
    nn.Linear(2, 4),
    nn.Tanh(),
    nn.Linear(4, 1),
    nn.Sigmoid()
)

Let's break that down.

nn.Linear(2, 4)

creates a layer that takes two inputs and produces four outputs.

That's our hidden layer.

Next:

nn.Tanh()

applies the tanh activation function.

Then:

nn.Linear(4, 1)

connects the four hidden neurons to one output neuron.

Finally:

nn.Sigmoid()

converts the output into a value between 0 and 1.

So the architecture is:

2 inputs
   ↓
4 hidden neurons
   ↓
Tanh
   ↓
1 output neuron
   ↓
Sigmoid

Notice how much shorter this is than our NumPy implementation.

That's because PyTorch handles many of the calculations for us.

31. Training the Network With PyTorch

First, create the training data:

X = torch.tensor([
    [0., 0.],
    [0., 1.],
    [1., 0.],
    [1., 1.]
])

y = torch.tensor([
    [0.],
    [1.],
    [1.],
    [0.]
])

The decimal points are important because neural networks normally work with floating-point numbers.

Now create the model:

model = nn.Sequential(
    nn.Linear(2, 4),
    nn.Tanh(),
    nn.Linear(4, 1),
    nn.Sigmoid()
)

Next, choose our loss function:

loss_function = nn.BCELoss()

BCELoss calculates binary cross-entropy loss.

Now create an optimizer:

optimizer = torch.optim.Adam(
    model.parameters(),
    lr=0.01
)

Adam is an optimization algorithm that updates the model's parameters during training.

model.parameters() tells the optimizer which values it should update.

lr=0.01 sets the learning rate.

Now we can train:

for epoch in range(5000):

    predictions = model(X)

    loss = loss_function(predictions, y)

    optimizer.zero_grad()

    loss.backward()

    optimizer.step()

    if epoch % 500 == 0:
        print(
            f"Epoch {epoch}, Loss: {loss.item():.4f}"
        )

Let's look at the important parts.

First:

predictions = model(X)

This sends the training data through the network.

Then:

loss = loss_function(predictions, y)

compares the predictions with the correct answers.

Next:

optimizer.zero_grad()

clears gradients from the previous training step.

Then:

loss.backward()

calculates the gradients automatically using backpropagation.

Finally:

optimizer.step()

uses those gradients to update the model's parameters.

That's the same basic learning process we implemented manually with NumPy. The difference is that PyTorch takes care of many of the calculations.

32. NumPy vs. PyTorch

So why did we build the network twice? Well, because the two versions teach different things.

With NumPy, we manually handled weights, biases, forward propagation,
loss, gradients, backpropagation, and parameter updates. That makes the mechanics easier to see.

With PyTorch, we can write the same general idea in much less code because the framework handles many of those calculations.

You can think of it like this:

Comparison between NumPy and PyTorch

Learning how the NumPy version works makes the PyTorch version much less mysterious.

33. What Is Deep Learning?

You may have heard the term deep learning. Deep learning is a part of machine learning that uses neural networks with multiple layers.

For example:

Input
  ↓
Layer 1
  ↓
Layer 2
  ↓
Layer 3
  ↓
Layer 4
  ↓
Output

The word "deep" refers to the depth of the network, or the number of layers involved.

There isn't a magical point where a neural network suddenly becomes intelligent. Adding layers simply gives the model more opportunities to transform the input into useful representations.

34. Where Are Neural Networks Used?

Neural networks are used in many different areas. Here are a few examples...

Computer Vision

Neural networks can process images.

For example:

Image
  ↓
Neural Network
  ↓
Prediction

They can be used for tasks such as image classification and object detection.

Natural Language Processing

Neural networks can also process text.

For example:

Text
  ↓
Neural Network
  ↓
Prediction

Modern language models use neural networks to process and generate text.

Speech Recognition

Neural networks can process audio and help convert spoken language into text.

Audio
  ↓
Neural Network
  ↓
Words

Recommendation Systems

Neural networks can learn patterns from user behavior and help predict which content or products might be useful to someone.

Generative AI

Large neural networks can also be used to generate text, images, audio, code, video, and much more.

These systems are much more complicated than the small XOR network we built, but they still rely on the same general idea of learning parameters from data.

35. The Whole Process in One Picture

At this point, we've covered a lot.

Here's the entire training process:

Data
   ↓
Neural Network
   ↓
Prediction
   ↓
Loss
  ↓
Backpropagation
  ↓
Update Parameters
  ↓
Repeat

Once training is finished, we use the learned parameters to make predictions on new data:

New Data
   ↓
Trained Neural Network
   ↓
Prediction

That's the basic idea behind neural network training.

36. The Most Important Ideas to Remember

If you don't remember every equation from this tutorial, that's okay.

Start with these concepts.

Inputs

The numbers we give to the network.

x₁, x₂, x₃...

Weights

Numbers that determine how strongly inputs affect neurons.

w₁, w₂, w₃...

Biases

Additional values that give neurons more flexibility.

b

Activation Functions

Functions that transform neuron outputs and allow networks to learn nonlinear patterns.

Examples include:

ReLU
Tanh
Sigmoid

Forward Propagation

Sending data from the input toward the output.

Input → Hidden Layers → Output

Loss

A measurement of how different the prediction is from the correct answer.

Backpropagation

Calculating gradients by working backward through the network.

Gradient Descent

Using those gradients to update the network's parameters.

And the entire learning process can be summarized as:

Predict
   ↓
Measure Error
   ↓
Calculate Gradients
   ↓
Update Parameters
   ↓
Repeat

37. What Should You Learn Next?

If you want to continue learning neural networks with Python, you don't need to jump directly into complicated research papers.

A useful learning path is:

Python
  ↓
NumPy
  ↓
Basic Linear Algebra
  ↓
Probability & Statistics
  ↓
Machine Learning Basics
  ↓
Neural Networks
  ↓
PyTorch
  ↓
Deep Learning
  ↓
Computer Vision / NLP / Generative AI

You can also learn by building small projects.

For example:

  1. XOR classifier

  2. House price predictor

  3. Handwritten digit classifier

  4. Simple image classifier

  5. Spam message classifier

  6. Neural network that learns a mathematical function

The projects don't need to be huge. A small project that you completely understand is often more useful than a large project where you copied code without understanding it.

Final Takeaway

Neural networks can look intimidating because the systems used in modern AI can contain enormous numbers of parameters.

But the basic idea is much smaller.

A neural network takes numbers as input, combines them using weights and biases, applies mathematical functions, produces a prediction, measures how wrong that prediction was, and then adjusts its parameters.

The cycle looks like this:

Input
  ↓
Weighted Calculations
  ↓
Activation Functions
  ↓
Prediction
  ↓
Loss
  ↓
Gradients
  ↓
Parameter Updates
  ↓
Repeat

That's the foundation.

The XOR network we built in this tutorial is tiny compared with the neural networks used in modern AI. But the ideas you just learned (parameters, layers, activation functions, forward propagation, loss, backpropagation, gradients, and optimization) are fundamental ideas that appear again and again in deep learning.

The next time you hear that an AI model has millions or billions of parameters, it might still sound overwhelming.

But underneath all that scale, the basic learning loop is still familiar:

  1. Make a prediction.

  2. Measure the error.

  3. Figure out how to improve.

  4. Update the parameters.

  5. Try again.

And that's the core idea behind a neural network.

Happy coding and keep learning!

]]> <![CDATA[ How to Build a Basic Discord Storytelling, Chat, and Mental Wellness Bot with Python ]]> https://www.freecodecamp.org/news/how-to-build-a-basic-discord-bot-with-python/ 6a7f44fc58366ecdaf016624 Fri, 14 Aug 2026 16:40:28 +0000 Discord bots can look surprisingly complicated when you see them in action. A bot can respond to messages, tell stories, remember parts of conversations, and stay online around the clock.

When I first started looking into how they worked, I assumed there had to be a huge amount of complicated code behind all of it.

But the basic idea is actually pretty simple.

At its core, a Discord bot is just a Python program that connects to Discord, waits for something to happen, and then decides how to respond. Once you understand that basic idea, you can start adding features one at a time and turn a simple bot into something much more interesting.

In this tutorial, we'll start with a very small bot and gradually build it into something more capable. Along the way, you'll learn about Discord commands, events, asynchronous Python, user state, environment variables, and basic deployment.

One quick disclaimer before we start: the mental-wellness feature that we'll be integrating in this bot in this project is not therapy, and the bot is not a therapist or medical professional. It should only provide general supportive suggestions and encourage users to reach out to a trusted person when appropriate.

With that out of the way, let's get coding!

What We'll Cover:

What We're Building

Our finished bot will have several commands:

!hello
!story
!chat hello!
!support I'm having a stressful day
!help

For example:

User:
!story

Bot:
You wake up inside an abandoned library.

There are three doors in front of you:

1. A red wooden door
2. A metal door covered in strange symbols
3. A staircase leading underground

Which one do you choose?

The user can then continue the story.

For chat:

User:
!chat What's a good way to learn Python?

Bot:
Try building small projects instead of only reading tutorials.
A Discord bot is actually a pretty fun project to start with.

And for mental-wellness support:

User:
!support I'm really stressed about school.

Bot:
That sounds like a lot to deal with. You could try breaking
the work into one small task at a time and taking a short
break between tasks.

I'm a bot, not a therapist, so if you need personal support,
consider talking with someone you trust.

The goal isn't to make a magical robot therapist. It's to build a useful bot while learning how Discord APIs, Python functions, events, asynchronous programming, and basic conversational logic fit together.

What You Need

You only need a few things:

  • Python (version 3.8+ is recommended)

  • A Discord account

  • A Discord server where you have permission to add a bot

  • A code editor (I personally prefer VS Code or PyCharm)

  • The discord.py library

We'll also use Python's built-in os module for reading environment variables.

If you don't already have Python installed, install a current supported version of Python from the official Python website.

Then check that Python works:

python --version

You should see something similar to:

Python 3.x.x

Create the Discord Bot

Before Python can control Discord, we need to create a Discord application.

Go to the Discord Developer Portal: https://discord.com/developers/applications

Picture of the discord developer application page

This is what the page will look like, you might need to login with your discord email/username and password before you start.

Click on the "New Application" button on the top right and give your bot a name. For this tutorial, let's call ours StoryBot.

Picture of what it looks like when you click on the "New Application" button

The application is basically the home for your bot.

Discord's developer platform provides the tools needed to create and configure applications and bots.

Once you've created the application, open its Bot section and create the bot user. You can add your own icon picture and your own banner if you want to.

You will then go to the Token section and click on "Reset Token" to generate your token. Treat that token like a password. Do NOT put it directly into your Python source code.

Picture of what the Token part in the Bots section looks like

Never do this:

bot.run("my-secret-token")

And definitely don't upload a token to GitHub or commit it to source control. Instead, we'll store it in an environment variable, which we'll talk about later.

Give the Bot Permission to Read Messages

Our bot needs to see the messages that contain commands.

Discord uses something called Gateway Intents to control which types of events a bot receives. The discord.py documentation explains that intents must be enabled both in your code and, for privileged intents, in the Discord Developer Portal.

In the Developer Portal, find:

Bot
→ Privileged Gateway Intents

Enable:

Message Content Intent

It should look somewhat like this:

What should the "Message Content Intent" section look like

We'll also enable it in Python, which we will talk about later in this article.

Create the Project

Create a folder:

discord-story-bot/

Inside it, we'll eventually have:

discord-story-bot/
│
├── bot.py
├── requirements.txt
└── .env

The three important files are:

  • bot.py: our Python program

  • requirements.txt: text file that contains the name of the packages our bot needs

  • .env: our secret token during local development

Create a Virtual Environment

Open your terminal inside the project folder.

Run:

python -m venv venv

Then activate it.

On Windows:

venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

A virtual environment gives this project its own little Python bubble.

That means packages installed for this bot won't randomly interfere with packages used by another project.

Install discord.py

Now install the Discord library:

pip install -U discord.py

The official discord.py documentation uses this installation approach for setting up the library.

We'll also install python-dotenv, which makes reading our local .env file easier:

pip install python-dotenv

Then save the dependencies:

pip freeze > requirements.txt

Your requirements.txt should contain the packages needed by the project.

Create Your First Bot

Let's start small.

Open bot.py:

import os

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


bot.run(TOKEN)

That is already a functional Discord bot.

Let's break it apart piece by piece.

Importing Our Libraries

First:

import os

os lets Python communicate with parts of the operating system.

We'll use it to read environment variables.

Next:

import discord

This imports discord.py.

Then:

from discord.ext import commands

The commands extension makes creating commands much easier.

Instead of manually checking every message for something like !hello, we can write:

@bot.command()
async def hello(ctx):
    await ctx.send("Hello!")

The discord.py command system is built around Python functions decorated as commands.

Finally:

from dotenv import load_dotenv

This lets us load values from our .env file.

Loading the Token

Our bot needs a token to connect our Python program to Discord. Think of the token as a password that allows our program to authenticate as the bot.

We don't want to put this secret directly into our Python code. Instead, we'll store it in an environment variable.

First, install python-dotenv:

pip install python-dotenv

This package lets Python read values from a .env file.

Now create a new file called .env in the same folder as bot.py.

Inside .env, add:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE

Replace YOUR_BOT_TOKEN_HERE with the token you copied from the Discord Developer Portal.

Your file should look something like this:

DISCORD_TOKEN=your_actual_token_here

Don't share this token with anyone or upload your .env file to GitHub. Your bot token should be treated like a password.

To make sure Git doesn't accidentally include the .env file in a repository, create a file called .gitignore in your project folder and add:

.env
venv/
__pycache__/

Now let's load the token in Python.

At the top of bot.py, add:

import os
from dotenv import load_dotenv

Then add:

load_dotenv()

This tells Python to look for the .env file and load the variables inside it.

Now we can get our Discord token:

TOKEN = os.getenv("DISCORD_TOKEN")

os.getenv() looks for the environment variable named "DISCORD_TOKEN" and gives us its value.

We can also check that the token was actually found:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

If Python can't find the token, the program stops and gives us a clear error message instead of failing later in a confusing way.

Understanding Intents

Remember how we talked about enabling message content readability in python? We are going to do that now.

Add:

intents = discord.Intents.default()
intents.message_content = True

The first line creates a set of Discord's default intents.

The second line tells Discord that our bot needs access to message content.

Now we need to give these intents to our bot when we create it:

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

The command_prefix="!" means our bot will recognize commands that begin with !.

For example:

!hello

The intents=intents part gives our bot the permissions we configured above.

There are two steps here because Discord needs to know that our bot is allowed to receive message content, while our Python program also needs to tell Discord that it wants to receive it.

Our basic setup should now look like this:

import os
import discord

from dotenv import load_dotenv
from discord.ext import commands

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

Now our bot has its token safely loaded and discord.py knows which intents to request when it connects to Discord.

What Is ctx?

This part can look weird when you're learning Discord bots:

async def hello(ctx):

What is ctx? ctx stands for context. It contains information about the command that was used.

For example, it can tell us:

  • Who ran the command

  • Which server it came from

  • Which channel it came from

  • What message triggered it

Then:

await ctx.send("Hello!")

means:

"Send this message back to the place where the command was used."

Why Does Everything Say async and await?

You might notice:

async def hello(ctx):

and:

await ctx.send(...)

Discord bots spend a lot of time waiting.

They wait for:

  • Messages

  • Discord responses

  • API requests

  • Timers

  • Other events

Python's asynchronous programming features allow the bot to wait for these operations without freezing everything else.

You don't need to become an async-programming expert before building your first bot.

For now, think of await as:

"Pause this task until this operation finishes, while letting the bot handle other things."

Run the Bot

Start it with:

python bot.py

If everything works, your terminal should print something similar to:

Logged in as StoryBot

Now go to your Discord server and type !hello. Your bot should respond.

Congratulations! You've officially made a Discord bot.

Now let's make it interesting.

Build the Storytelling System

First, we're going to create an interactive storytelling command.

At the top of bot.py, add:

import random

Then create some story ingredients:

story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]

Now create the command:

@bot.command()
async def story(ctx):
    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    story_text = (
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

    await ctx.send(story_text)

Now !story might produce:

You wake up in a futuristic city.

Next to you is an ancient notebook.

A hidden door opens nearby.

What do you do?

Run it again and you might get something completely different.

That's because of:

random.choice(...)

Python randomly picks one item from each list.

It's a simple technique, but suddenly your bot can generate hundreds of different combinations.

Let's Make the Story Remember the User

Random stories are fun, but interactive stories are much better when the bot remembers what happened.

We can create a dictionary:

user_stories = {}

The dictionary will store story information for each user.

For example:

user ID → current story

Now let's modify the story command:

@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

Now each user can have their own active story.

Add a Story Choice

Let's give users choices.

@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send("You don't have an active story. Try `!story` first.")
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)

Now users can type:

!choose left

or:

!choose right

Notice this:

async def choose(ctx, choice: str):

The choice parameter receives the text after the command.

So:

!choose left

becomes approximately:

choice = "left"

This is one of the reasons command frameworks are so convenient. A command framework is a set of tools that makes it easier to create and manage commands in a program. In our case, discord.py provides the command framework that lets us turn Python functions into Discord commands using decorators like @bot.command().

Instead of manually checking every message to figure out whether someone typed !choose, discord.py handles that work for us. It recognizes the command, takes the user's arguments, and passes them to our function.

So when someone types:

!choose left

discord.py knows that choose is the command, "left" is the argument, and that it should call our choose() function with that information.

Add a Casual Chat Command

Now let's make the bot capable of basic conversation.

We could connect it to a large language model API, but you don't actually need AI to learn how a chat command works. We'll start with a simple keyword-based response system.

First, we'll create a dictionary containing some keywords and possible responses:

chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],
    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],
    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}

Think of `chat_responses` as a small collection of things our bot knows how to talk about. Each key, such as `"python"` or `"discord"`, represents a keyword the bot can look for. The value associated with each key is a list of possible responses.

We use a list instead of a single response so the bot doesn't give exactly the same answer every time. Later, we'll randomly choose one of these responses.

Now let's create the actual `!chat` command:

```python
@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )

There are a few things happening here, so let's break it down.

First, this part:

@bot.command()
async def chat(ctx, *, message: str):

turns the chat() function into a Discord command. The * is important because it tells discord.py to treat everything after the command as one argument.

For example, if someone types:

!chat I want to learn Python

the entire phrase after !chat becomes the value of message:

message = "I want to learn Python"

Next, we have:

text = message.lower()

This converts the message to lowercase. That means Python, python, and PYTHON will all become python. Without this, our keyword check could miss a match simply because the user capitalized a word differently.

Now we get to the loop:

for keyword, responses in chat_responses.items():

.items() lets us go through both the keyword and its corresponding list of responses. During each loop, keyword contains something like "python", while responses contains the list of responses associated with it.

Then we check:

if keyword in text:

This asks whether the current keyword appears anywhere in the user's message.

If the user writes:

!chat I want to learn Python

the lowercase version becomes:

i want to learn python

Since "python" appears inside that text, the condition is true.

The bot can then choose a random response:

await ctx.send(random.choice(responses))

random.choice() picks one item from the response list, while ctx.send() sends that response back to the Discord channel.

Finally, we have:

return

This stops the function after a matching keyword is found. Without it, the loop would continue checking the other keywords even after the bot had already responded.

But what happens if none of the keywords match?

That's what this part handles:

await ctx.send(
    "I'm still learning how to respond to that. "
    "Try talking to me about Python or Discord!"
)

If the loop finishes without finding a keyword, the bot sends this fallback message instead.

For example:

!chat I like pizza

doesn't contain "hello", "python", or "discord", so the bot doesn't have a specific response to use.

This gives us a simple way for the bot to have conversations without needing an AI model.

Add a Mental-Wellness Support Feature

Now for the feature that needs a little more care.

Instead of calling this a "therapy command" internally, we'll call it:

!support

Quick additional disclaimer before we start...this is just a fun wellness script, not a real therapist!

Create:

support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}

Now create the command:

@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )

Now someone can type:

!support I'm stressed about school

The bot sees the word:

school

and chooses one of the school-related responses.

This is deliberately simple.

For a real public bot, you'd want much more careful safety handling, testing, moderation, privacy protection, and escalation logic before allowing users to rely on it for sensitive situations.

Add a Help Command

A good bot should explain itself.

@bot.command()
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )

There's one small issue.

Discord's default help command is already called help.

So instead of:

async def help(ctx):

we've named ours:

commands_help

If you want the command itself to be called !help, you can write:

@bot.command(name="help")
async def commands_help(ctx):
    ...

That tells Discord:

Use !help for this function even though the Python function has another name.

Improve Error Handling

Bots shouldn't crash just because someone enters an invalid command.

Add:

@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")

Now if someone types:

!chat

without giving the bot a message, it can respond with a useful explanation instead of dumping a confusing error into the conversation.

Put Everything Together

At this point, your bot.py can look like this:

import os
import random

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")


intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]


user_stories = {}


chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],

    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],

    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}


support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )


@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send(
            "You don't have an active story. Try `!story` first."
        )
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)


@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )


@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )


@bot.command(name="help")
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )


@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")


bot.run(TOKEN)

This is enough to create a surprisingly capable beginner Discord project.

But there's an important limitation.

Our Bot Doesn't Actually Remember Anything

There's one small problem with our bot so far: it doesn't actually remember anything after it shuts down.

Right now, we're storing our story information in a Python dictionary:

user_stories = {}

This works while the bot is running. But if you stop the program and start it again, the dictionary starts empty.

To fix this, we need somewhere to permanently store our data. That's where a database comes in.

For this project, we'll use SQLite. SQLite is a lightweight database that stores information in a file on your computer. Python already includes SQLite through the built-in sqlite3 module, so we don't need to install anything extra.

Create the Database

First, add this import near the top of bot.py:

import sqlite3

Then create a connection to a database file:

db = sqlite3.connect("bot.db")
cursor = db.cursor()

The first line creates a database file called bot.db if one doesn't already exist. If the file already exists, SQLite simply opens it.

The second line creates a cursor. You can think of the cursor as the part of our Python program that lets us send instructions to the database.

Now we need to create a table where we can store our users' story information:

cursor.execute("""
    CREATE TABLE IF NOT EXISTS user_stories (
        user_id INTEGER PRIMARY KEY,
        location TEXT,
        item TEXT,
        event TEXT
    )
""")

db.commit()

Let's break this down.

cursor.execute() tells SQLite to run the SQL command inside the parentheses.

The SQL command starts with:

CREATE TABLE IF NOT EXISTS user_stories

This tells SQLite to create a table called user_stories, but only if that table doesn't already exist.

Inside the parentheses, we define the information that each row can contain:

user_id INTEGER PRIMARY KEY,
location TEXT,
item TEXT,
event TEXT

user_id stores the Discord user's ID. We use it as the PRIMARY KEY, which means each user gets their own unique row.

location, item, and event are all pieces of information about the user's current story.

Finally:

db.commit()

saves the changes to the database.

At this point, your project folder should contain a new file called:

bot.db

You don't need to open or edit this file manually. SQLite will manage it for us.

Save a User's Story

Now let's actually put information into our database.

Suppose we have these variables:

user_id = ctx.author.id
location = "an abandoned castle"
item = "a mysterious key"
event = "a locked door"

We can save them using:

cursor.execute(
    """
    INSERT OR REPLACE INTO user_stories
    (user_id, location, item, event)
    VALUES (?, ?, ?, ?)
    """,
    (user_id, location, item, event)
)

db.commit()

The SQL statement tells SQLite to insert the information into the user_stories table.

The ? symbols are placeholders for the actual values. The values are provided separately here:

(user_id, location, item, event)

This is safer than manually inserting values directly into the SQL string.

INSERT OR REPLACE also means that if this user already has a saved story, their old story information can be replaced with the new information.

Get the Story Back

Saving information is only half of the job. We also need to be able to retrieve it.

We can search the database for a user's story like this:

cursor.execute(
    """
    SELECT location, item, event
    FROM user_stories
    WHERE user_id = ?
    """,
    (user_id,)
)

story = cursor.fetchone()

This time, we're using SELECT to ask SQLite for information.

The WHERE part is important:

WHERE user_id = ?

It tells SQLite to find the row belonging to this specific Discord user.

Then:

story = cursor.fetchone()

gets the first matching result.

If the user has a saved story, story will contain their information. If they don't, story will be None.

We can check for that:

if story:
    location, item, event = story

    await ctx.send(
        f"You're currently in {location}. "
        f"You have {item}, and you're facing {event}."
    )
else:
    await ctx.send("I don't have a saved story for you yet!")

Now the bot can retrieve information that was saved earlier, even after the Python program has been restarted.

Put It Into a Command

We can turn this into a simple command that lets users check their saved story:

@bot.command()
async def status(ctx):
    user_id = ctx.author.id

    cursor.execute(
        """
        SELECT location, item, event
        FROM user_stories
        WHERE user_id = ?
        """,
        (user_id,)
    )

    story = cursor.fetchone()

    if story:
        location, item, event = story

        await ctx.send(
            f"You're currently in {location}. "
            f"You have {item}, and you're facing {event}."
        )
    else:
        await ctx.send(
            "You don't have a saved story yet. "
            "Start one with `!story`!"
        )

Now a user can type:

!status

and the bot can look up their story from the database.

This is a big improvement over our original dictionary. A dictionary only remembers information while the Python program is running. SQLite lets us save that information so it can still be there when the bot starts again.

For a larger bot, you could eventually store things like user preferences, story progress, inventory, conversation history, or other data. But for now, this simple database is enough to give our bot some real memory.

Adding Real AI Chat

Before we connect our bot to an AI model, let's quickly talk about Hugging Face.

If you've never used it before, Hugging Face is a platform where developers can find, share, and use machine learning models and datasets. Think of it as a huge community and library for AI tools.

Hugging Face also provides tools that let Python programs communicate with these models without having to build and train an AI model from scratch.

For our bot, we'll use Hugging Face's Inference Providers to send a user's message to a supported language model and receive its response.

We won't be training an AI model ourselves. Instead, we'll use an existing model and connect it to our Discord bot through Python.

Now that we know what Hugging Face is, let's connect it to our bot.

Install the Hugging Face Library

First, install huggingface_hub:

pip install -U huggingface_hub

We already installed python-dotenv, so we can use the same .env file from earlier to keep our Hugging Face token out of the source code.

Add your Hugging Face token to .env:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE
HF_TOKEN=YOUR_HUGGING_FACE_TOKEN_HERE

Replace YOUR_HUGGING_FACE_TOKEN_HERE with your actual Hugging Face access token.

Just like your Discord bot token, don't share this token or upload it to GitHub.

Create the Hugging Face Client

Now add this import near the top of bot.py:

from huggingface_hub import InferenceClient

Then load the token:

HF_TOKEN = os.getenv("HF_TOKEN")

if not HF_TOKEN:
    raise RuntimeError("HF_TOKEN is not set.")

The first line gets the token from our environment variables. The if statement checks whether the token actually exists. If it doesn't, Python stops and gives us a useful error instead of letting the program fail later in a confusing way.

Now create the Hugging Face client:

client = InferenceClient(
    api_key=HF_TOKEN
)

The InferenceClient is what our Python program will use to communicate with Hugging Face's inference service.

Connect the AI Model to the Bot

Now we can replace our previous keyword-based !chat command with one that sends the user's message to a language model.

@bot.command()
async def chat(ctx, *, message: str):
    try:
        response = client.chat_completion(
            model="YOUR_SUPPORTED_MODEL_ID",
            messages=[
                {
                    "role": "system",
                    "content": (
                        "You are a friendly Discord bot. "
                        "Keep responses helpful, concise, and conversational."
                    )
                },
                {
                    "role": "user",
                    "content": message
                }
            ],
            max_tokens=200
        )

        answer = response.choices[0].message.content

        await ctx.send(answer)

    except Exception as error:
        print(f"AI error: {error}")
        await ctx.send(
            "I couldn't generate a response right now. "
            "Please try again later."
        )

There's quite a bit happening here, so let's walk through it.

We start with the same command structure we've already used:

@bot.command()
async def chat(ctx, *, message: str):

This creates our !chat command and stores everything the user types after it in message.

For example:

!chat What is Python?

gives us:

message = "What is Python?"

Next, we use:

try:

This tells Python that we're about to run code that could potentially fail. Since we're communicating with an external service, things like an unavailable model, an invalid token, or a temporary connection problem can happen.

Now we call:

response = client.chat_completion(

This sends a chat-completion request to the model through Hugging Face. The messages parameter contains the conversation we want the model to respond to.

The first message has the role "system":

{
    "role": "system",
    "content": (
        "You are a friendly Discord bot. "
        "Keep responses helpful, concise, and conversational."
    )
}

The system message gives the model instructions about how it should respond.

Then we provide the user's actual message:

{
    "role": "user",
    "content": message
}

If the user typed:

!chat What is Python?

then message contains:

What is Python?

So the model receives that as the user's input.

We also have:

max_tokens=200

This limits how much text the model can generate for one response. Keeping responses relatively short works well for Discord because huge blocks of text aren't always very pleasant to read in a chat channel.

You also need to replace:

model="YOUR_SUPPORTED_MODEL_ID"

with the ID of a model currently available through the Hugging Face Inference Providers you are using. Hugging Face's documentation shows that InferenceClient can use a model ID hosted on the Hugging Face Hub for chat completion.

Once the request is complete, we need to get the actual text from the response:

answer = response.choices[0].message.content

The response contains information about the model's output. choices[0] gets the first generated response, and .message.content gives us the actual text.

Then we send it to Discord:

await ctx.send(answer)

So the whole process looks like this:

User types !chat
        ↓
Discord sends the command to our bot
        ↓
Python gets the user's message
        ↓
Hugging Face receives the message
        ↓
The AI model generates a response
        ↓
Python gets the generated text
        ↓
The bot sends it back to Discord

Handle AI Errors

The last part of our command is:

except Exception as error:
    print(f"AI error: {error}")
    await ctx.send(
        "I couldn't generate a response right now. "
        "Please try again later."
    )

If something goes wrong inside the try block, Python jumps to the except block instead of crashing the entire bot.

The error is printed in the terminal so you can investigate what happened:

print(f"AI error: {error}")

Meanwhile, the Discord user gets a simple message:

I couldn't generate a response right now. Please try again later.

This is much better than letting an API error take down the whole bot.

At this point, you have a real AI-powered !chat command. You can type something like:

!chat Tell me an interesting fact about space.

and the model can generate a response instead of choosing from a small list of pre-written messages.

One thing to remember is that this bot is sending user messages to an external AI service. Don't automatically send private or sensitive conversations to an AI provider. If you make this bot available to other people, be clear about what information it processes and avoid storing or sending more data than the bot actually needs.

You can also combine this AI system with the SQLite database from earlier. For example, you could save a limited amount of conversation history and send relevant previous messages along with a new message. That would allow the bot to keep some context between messages instead of treating every message as a completely new conversation.

How Do We Keep the Bot Online?

Here's where the phrase "online forever" needs a little clarification.

There are two different situations.

Option 1: Run It on Your Computer

When you run:

python bot.py

the bot stays online while that program is running.

Close the terminal?

Bot goes offline.

Turn off the computer?

Bot goes offline.

Lose internet?

Bot goes offline.

This is perfect for development but it's not a 24/7 production setup.

Option 2: Host It on a Server

For a bot that should stay online while your computer is off, you need a computer somewhere that stays available.

That computer can be a cloud server.

You upload your project, install the dependencies, add your environment variables, and start:

python bot.py

Now the cloud machine runs the program instead of your laptop.

Services designed for continuously running workloads can be used for this kind of application. For example, Render currently provides a Background Worker service type for continuously running processes that don't need to receive incoming web traffic.

But you should check the provider's current pricing and service limitations before deploying. Free hosting tiers aren't necessarily designed for an always-on Discord bot, and a "free forever" 24/7 setup isn't something you should assume a hosting platform will provide.

What "Forever" Actually Means

There isn't really a magical:

ONLINE_FOREVER = True

setting.

A bot can stay online continuously only as long as the computer or server running it continues operating.

Even a professionally hosted bot can go offline because of:

  • Server maintenance

  • Deployments

  • Bugs

  • Network problems

  • Provider outages

  • Invalid credentials

  • API changes

  • Billing or account issues

So the realistic goal is to keep the bot running automatically and restart it when something goes wrong.

That is what production hosting is designed to help with.

If your provider supports automatic restarts, enable them.

You can also make your Python code fail clearly when an important environment variable is missing:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

A clear error is much easier to debug than a mysterious bot that simply doesn't appear online.

Don't Try to "Keep It Awake" With Random Tricks

You may find tutorials suggesting that you deploy a web server and repeatedly ping it from another service to prevent a free hosting instance from sleeping.

Be careful with that approach.

Hosting providers change their free-tier rules, and attempting to work around those limits can violate their terms.

If you need an actually persistent bot, use a hosting option that explicitly supports the workload.

For example, a background worker is designed for continuously running processes. That's much cleaner than trying to convince a web service that your Discord bot is secretly a website.

Additional Features and Where to Go Next

Now that you have a working Discord bot, there are plenty of directions you can take the project next.

You could turn the storytelling system into a more complete game by adding an inventory, multiple chapters, puzzles, or different endings. You could also replace text-based commands with Discord slash commands and buttons to make the bot easier to interact with.

If you're interested in AI, you could expand the chat system by giving the bot different personalities, adding carefully limited conversation context, or using AI to generate parts of the stories.

You could also add moderation features, daily story prompts, or other commands that fit the kind of Discord community you're building.

These are ideas for extending the project rather than features we'll build step by step in this tutorial. The important thing is that you now have the foundation to experiment with them yourself.

Start with one small feature, figure out how it works, and build from there. You don't need to turn the bot into a massive project all at once.

The more you experiment with the code, the more you'll start seeing how Python, Discord, databases, and AI can work together in a real application.

Test Everything Locally First

Before deploying, test:

!hello
!story
!choose left
!choose right
!chat hello
!chat I want to learn Python
!support I'm stressed
!help

Then test weird inputs:

!choose banana
!chat
!support
!unknowncommand

You want to discover bugs while you're sitting in front of your computer, not three days later when someone tells you:

"Your bot has been broken since Tuesday."

Deploying the Bot

First, make sure your project contains:

discord-story-bot/
│
├── bot.py
├── requirements.txt
├── .gitignore
└── .python-version

A .python-version file can contain something like:

3.13

Using a version file makes your deployment environment more predictable. Render currently supports specifying a Python version through .python-version or an environment variable.

Your requirements.txt should contain your dependencies.

For example:

discord.py
python-dotenv

For deployment, you generally don't need the local .env file.

Instead, add:

DISCORD_TOKEN

as an environment variable in your hosting provider's dashboard.

That way the secret isn't stored inside your repository.

The Start Command

Your deployment service needs to know what to run.

For this project, the start command is:

python bot.py

The important thing is that the process doesn't immediately exit.

A Discord bot stays alive because bot.run(TOKEN) starts the Discord connection and keeps the program running.

If your hosting service supports background workers, that's a natural fit for a bot like this because the bot doesn't need to serve normal HTTP requests. Render specifically describes background workers as continuously running services that don't receive incoming network traffic.

Remember: Keep Your Secrets Secret

This is worth repeating because it causes a lot of beginner projects to get compromised.

Never commit this:

bot.run("YOUR_REAL_TOKEN")

Never upload:

.env

Never paste your actual token into a public GitHub issue.

If a token accidentally becomes public, treat it as compromised and regenerate it.

Environment variables are your friend.

What You Learned

You've now built a Discord bot that demonstrates several real programming concepts.

You learned how to:

  • Create a Discord application

  • Connect Python to Discord

  • Use discord.py

  • Configure Gateway Intents

  • Create commands

  • Use asynchronous functions

  • Read command arguments

  • Generate random stories

  • Store temporary user state

  • Create a basic chat system

  • Create a mental-wellness support feature

  • Handle command errors

  • Keep secrets out of source code

  • Prepare a project for deployment

  • Think about persistent hosting

And underneath all those features, the architecture is still surprisingly simple:

User sends command
        ↓
Discord receives message
        ↓
discord.py receives event
        ↓
Python function runs
        ↓
Bot generates response
        ↓
Discord displays response

You don't need thousands of lines of code to get started.

You need a clear idea, a few Python concepts, and the willingness to keep debugging when something inevitably breaks.

Final Thoughts

The coolest part of this project isn't really the Discord bot. It's what the project teaches you.

And once you understand the pieces, you can reuse the same ideas in countless projects.

A Discord bot can become a game, which could become a web application, which could also become a larger software project.

And suddenly you're not just learning Python syntax anymore. You're learning how software actually gets built, one command at a time.

Happy coding!

]]>