Hugging Face's logo

Spaces:
Agents-MCP-Hackathon
/
novel-heroes
Sleeping

App Files Community
novel-heroes / README.md
ryomo's picture
ryomo
Add some description
a78ac0d
preview code
|
raw
history blame contribute delete
6.09 kB

A newer version of the Gradio SDK is available: 5.35.0

Upgrade
metadata
title: Novel Heroes
emoji: 📚
colorFrom: pink
colorTo: gray
sdk: gradio
sdk_version: 5.33.0
python_version: 3.12
app_file: app.py
pinned: true
license: mit
short_description: Chat with characters from classic novels.
thumbnail: >-
  https://huggingface.co/spaces/Agents-MCP-Hackathon/consilium_mcp/blob/main/assets/screenshot.png
tags:
  - agent-demo-track
  - mcp-server-track

Novel Heroes

What is this?

Novel Heroes is an interactive chatbot that lets you have conversations with characters from classic, public domain novels. Powered by the Gemma-3 large language model running on Modal's serverless cloud, this app brings literary heroes and villains to life—letting you chat with them as if they were real.

You can select a book, pick a character, and start a conversation. The AI responds in the personality and style of the chosen character, based on the actual content of the novel. Whether you want to ask the Queen of Hearts for advice, chat with Winnie the Pooh, or challenge Captain Hook, Novel Heroes makes it possible.

Explore classic literature in a whole new way!

Demo

Watch a demo video of Novel Heroes on Vimeo

Screenshot
English and

Screenshot in Japanese
many other languages

My recommendation

Here are some character and book combinations that I personally enjoyed and found to work especially well. Try chatting with these characters for a fun and interesting experience!

  • "Queen of Hearts" in "Alices_Adventures_in_Wonderland" Experience the Queen's unique personality—she's strict, dramatic, and always ready to shout "Off with their heads!"

  • "Winnie the Pooh" in "Winnie_the_Pooh" Enjoy gentle and whimsical conversations with Pooh, who always has a kind word (and maybe a craving for honey).

  • "Hook" in "Peter_Pan" Challenge the cunning and theatrical Captain Hook, and see how he responds to your questions or provocations.

Feel free to explore other books and characters as well!

Tip:

  • If you, as the user, also try to role-play as a character from the story, the AI will respond even more naturally and engagingly. Stepping into the world of the novel together with the AI makes the experience much more immersive!
  • Sometimes "Hook" may not appear in "Select a Hero" list, as the AI doesn't always recognize the name. If this happens, try resetting and loading again.

Development

If you want to develop this project further, here are some details to help you get started.

Notes before setting up:

  • Gradio provides the user interface (UI) for chatting with characters.
  • Modal runs the large language model (LLM) backend that powers the character responses.
  • This project uses uv for dependency management and running scripts. Please install uv if you haven't already.

After cloning the repository, you can run the following command to install the dependencies:

uv sync --frozen
  • If you don't need to develop Modal integration, you can add --no-dev to the command above to skip installing the development dependencies.

Modal

Setup Modal Tokens

  1. Open "Settings" page in Modal dashboard.
  2. Open "API Tokens" page and create a new token.
    • Note: You need to stay open the page until you run the command on the page.
  3. Go to Hugging Face Spaces and open the "Settings" page.
  4. Add "New secret" with the name MODAL_TOKEN_ID and MODAL_TOKEN_SECRET and paste the tokens you created in step 2.

Setup Hugging Face Tokens

  1. Open "Settings" page in Hugging Face, go to "Access Tokens" page.
  2. Create a new token. The token should have read access.
  3. Go to Modal dashboard and open "Secrets" page.
  4. Create a new secret with the choice of Custom with the following.
  • Name: "huggingface-secret"
  • Environment Variable:
    • Key: HF_TOKEN, Value: <your-huggingface-token>

Run on Modal:

This command will run the main.py only once on Modal.

uv run modal run modal/main.py

Deploy to Modal:

This command will deploy the main.py to Modal, allowing it to run continuously.

uv run modal deploy modal/main.py

Run deployed modal app:

This command will run the invoke.py file, which is used to invoke the deployed Modal app. This is useful for testing the deployed app.

uv run modal/invoke.py

Gradio

Run locally 

uv run gradio app.py
  • Hot reloading is enabled by default.

Setup environment variables on Hugging Face Spaces

  1. Go to Hugging Face Spaces and open the "Settings" page.
  2. Add "New variable" with the name MCP_SERVER_URL and paste the URL of the Modal MCP server.
    • In my case, it is https://agents-mcp-hackathon-novel-heroes.hf.space/gradio_api/mcp/sse.

Deploy to Hugging Face Spaces 

uv export --format requirements-txt --no-dev --no-editable --no-hashes --no-emit-project > requirements.txt
git add requirements.txt
git commit -m "Update requirements.txt"
git push

Acknowledgements

Gemma3

Gemma3 is a powerful AI model that powers this application. It is developed by Google and is available on Hugging Face. This project uses the Gemma3 LLM to generate character responses based on the content of each novel. You can find more information about Gemma3 here.

Project Gutenberg

These eBooks are downloaded from Project Gutenberg, which provides free access to a vast collection of public domain books. All book texts used in this project are sourced from Project Gutenberg.

Please note that robot access is allowed only if you follow the rules in this document: Robot Access to Pages