📚 Novella AI

An agentic book assistant built with LangGraph and Streamlit.

Novella AI is a sophisticated AI agent that understands books, recommends reads, and engages in literary analysis through intelligent conversations. Powered by Google's Gemini 2.5 Flash and orchestrated with LangGraph's stateful workflow engine, it provides multi-turn conversations with memory and autonomous tool usage.

🌟 Key Features

• LangGraph-Powered Agent - Autonomous AI agent with stateful workflows, memory persistence, and tool orchestration
• Interactive Web Interface - Beautiful Streamlit web application for seamless conversations
• CLI Support - Terminal-based interface for command-line users
• Tool-Integrated AI - Agent autonomously searches books and manages reading lists
• Multi-turn Conversations - Context-aware discussions with memory across sessions
• Google Gemini 2.5 Flash - Fast and intelligent AI responses

---

⚙️ Requirements

• Python: 3.11 or higher
• Google API Key: Required for Gemini AI access (free tier available)
• Internet Connection: For API calls and book database access

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/MuhammedSenn/novella-ai.git
cd novella-ai

2. Set Up Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

3. Install Dependencies

Option A: For Development (Recommended)

pip install -e ".[dev]"

Option B: Using requirements files

# Production dependencies only
pip install -r requirements.txt

# With development tools
pip install -r requirements-dev.txt

4. Configure Environment Variables

⚠️ IMPORTANT: API Key Security

1. Create a .env file in the project root:

# Linux/macOS
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

2. Edit .env and add your Google API Key:

GOOGLE_API_KEY=your_actual_api_key_here

3. Template Available: Use .env.example as a reference for required variables

4. NEVER commit .env to GitHub!

   • ✅ The .gitignore file already excludes .env (checked automatically)
   • ✅ Your API key is safe from public exposure
   • ✅ Each developer should have their own .env file locally

How to get your API Key:

• Go to Google AI Studio
• Click "Create API Key"
• Copy and paste it into your .env file
• Free tier includes generous usage limits

Verify Setup:

# Check .env exists and is ignored
git status  # .env should NOT appear in output

---

🎯 Usage

Web Interface (Recommended)

streamlit run app.py

Visit http://localhost:8501 in your browser and start chatting about books!

Command Line Interface

python main.py

Type your book-related queries and press Enter. Type q, exit, or quit to stop.

---

🏗️ Architecture

User Input
    ↓
Streamlit Web App / CLI
    ↓
LangGraph Agent Workflow
├── Agent Node → Gemini LLM
├── Tool Node → OpenLibrary + JSON Storage
├── Conditional Routing → Tool Use Decision
└── Memory State → Multi-turn Context
    ↓
Response to User

How the Agent Works

1. Input Processing: User query comes through web or CLI
2. Agent Decision: LangGraph's agent decides if tools are needed
3. Tool Usage: If needed, agent autonomously:
   • Searches Open Library for books
   • Manages your reading list
4. Generation: Gemini generates intelligent responses
5. Memory: Conversation context persists across turns

---

📖 Understanding the Codebase

src/graph.py - The Agent Brain

• AgentState: TypedDict defining conversation state
• agent_node(): LLM call with tool binding
• should_continue(): Decides if tools should be executed
• create_graph(): Builds LangGraph workflow with:
  • StateGraph for workflow definition
  • ToolNode for tool execution
  • Conditional edges for routing
  • MemorySaver for state persistence

src/tools.py - Agent's Tools

• check_book_database(): Searches Open Library for books
• manage_reading_list(): CRUD operations on reading list
• Both are LangChain @tool decorated functions

src/prompt.py - Agent Personality

• System prompt defining agent behavior
• Instructions for book recommendations
• Tool usage guidelines
• Safety and content policies

---

📁 Project Structure

novella-ai/
├── src/                    # Application code
│   ├── graph.py           # LangGraph workflow and agent orchestration
│   ├── tools.py           # Book search and reading list tools
│   └── prompt.py          # System prompts and AI behavior
│
├── tests/                 # Test suite (39 unit tests)
│   ├── conftest.py        # Pytest fixtures and configuration
│   ├── test_graph.py      # Graph and agent tests
│   ├── test_tools.py      # Tools functionality tests
│   └── test_prompt.py     # Prompt content validation tests
│
├── app.py                 # Streamlit web application
├── main.py                # CLI application
├── pyproject.toml         # Project configuration and dependencies
├── requirements.txt       # Production dependencies
├── requirements-dev.txt   # Development tools
├── .gitignore            # Git ignore rules
├── LICENSE               # MIT License
├── README.md             # This file
├── CONTRIBUTING.md       # Contribution guidelines
└── TESTING.md           # Testing guide

---

🛠️ Development

Install Development Tools

pip install -e ".[dev]"

Code Quality

Ensure code follows PEP 8 standards:

# Format code with Black
black .

# Sort imports with isort
isort .

# Lint with Ruff
ruff check . --fix

# Type checking with mypy
mypy src/

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_tools.py -v

# Run specific test class
pytest tests/test_graph.py::TestCreateGraph -v

View coverage report: htmlcov/index.html

Key Technologies

• LangGraph 1.0.5 - Agentic framework for building stateful, multi-step workflows
• Streamlit 1.52.2 - Interactive web application framework
• Google Generative AI (Gemini 2.5 Flash) - Large language model
• LangChain 1.2.0 - Foundation for working with LLMs
• Python 3.11+ - Modern Python

---

📋 Configuration Files

pyproject.toml

• Python version requirement (≥3.11)
• Dependency management
• Build system configuration
• Tool configurations (Black, isort, Ruff, mypy, pytest)

requirements.txt

• Production dependencies only
• Pinned versions for reproducibility
• Use this for deployment

requirements-dev.txt

• Includes production dependencies via -r requirements.txt
• Development tools: Black, isort, Ruff, mypy
• Testing tools: pytest, pytest-asyncio, pytest-cov

---

🧪 Testing

Novella AI includes a comprehensive test suite:

• 39 Unit Tests across 3 modules
• Graph Tests: Workflow orchestration and agent behavior
• Tools Tests: Book database search and reading list management
• Prompt Tests: AI behavior validation

See TESTING.md for detailed testing guide.

---

🔒 Security Best Practices

API Key Security

✅ What's Protected:

• .env file is in .gitignore - never committed
• API keys are loaded from environment variables only
• Example .env.example not provided (use this README instead)

✅ What to Do:

• Create .env locally with your API key
• Never share your API key
• Regenerate API key if accidentally exposed
• Use separate keys for different environments

Code Security

• No hardcoded secrets anywhere
• All external APIs use HTTPS
• Dependencies are pinned to specific versions
• Regular updates recommended

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Bug reporting guidelines
• Feature request process
• Development workflow
• Code style standards (PEP 8)
• Pull request process

---

📦 Dependencies

Core Dependencies

• langgraph - Agentic workflow orchestration
• langchain & langchain-core - LLM abstractions
• google-genai - Gemini API client
• streamlit - Web UI framework
• requests - HTTP client for book database
• python-dotenv - Environment variable management

Development Dependencies

• black - Code formatter
• isort - Import sorter
• ruff - Fast linter
• mypy - Type checker
• pytest - Testing framework

---

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

MIT License means:

• ✅ Free to use for commercial and private purposes
• ✅ You can modify and distribute the code
• ⚠️ You must include the original license
• ℹ️ No warranty or liability

---

🙏 Acknowledgments

• Streamlit - Interactive web applications
• LangChain - LLM application framework
• Google Generative AI - Gemini models
• LangGraph - Agentic workflows
• Open Library - Book database

---

📧 Support

• Issues: Open a GitHub issue for bugs or features
• Discussions: Use GitHub Discussions for questions
• Documentation: Check TESTING.md and CONTRIBUTING.md

---

🎓 Learning Resources

• PEP 8 Style Guide
• Streamlit Documentation
• LangChain Docs
• Google Generative AI Guide

---

Made with ❤️ by Muhammed Şen

Last Updated: January 2026 | Status: Active Development