ACTIVA: Accounting Concepts Taught Interactively with Visual Animations

🚀 Quick Start

ACTIVA is a Python project managed with uv. The Manim Community team also recommends uv — see their official guide at https://docs.manim.community/en/stable/installation/uv.html. The steps below cover the system dependencies Manim needs on Windows, macOS, and Linux, then how to sync this project.

1. Install uv

uv is a fast Python package and project manager. It installs Python for you, creates the virtual environment, and resolves dependencies from uv.lock.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, restart your shell so uv is on your PATH, then verify:

uv --version

2. Install Manim's system dependencies

Manim's Python build needs Cairo, Pango, and FFmpeg at the OS level. Install them once per machine.

Windows

The Manim Community Windows guide installs everything via Chocolatey or Scoop. With Chocolatey (run PowerShell as Administrator):

choco install manimce

This pulls in FFmpeg and the required C libraries. Alternatively, with Scoop:

scoop bucket add extras
scoop install ffmpeg

Pango is bundled with the GTK runtime on Windows; the Chocolatey manimce package handles it. See the official Windows install guide for screenshots.

macOS

Use Homebrew:

brew install cairo pango pkg-config ffmpeg py3cairo

Linux

Install Cairo, Pango, FFmpeg, plus the build tools needed to compile pycairo/manimpango:

# Debian / Ubuntu
sudo apt install build-essential python3-dev libcairo2-dev libpango1.0-dev ffmpeg

# Fedora
sudo dnf install python3-devel pkg-config cairo-devel pango-devel ffmpeg

# Arch
sudo pacman -Syu base-devel cairo pango ffmpeg

3. (Optional) Install LaTeX

Only required if you want Manim to render typeset formulas (MathTex, Tex). Plain Text works without LaTeX, so you can skip this step for most ACTIVA accounting prompts.

Windows

Install MiKTeX using their installer.

macOS

brew install --cask mactex-no-gui   # large download (~4 GB)
# or for a minimal install:
brew install --cask basictex

Linux

# Debian / Ubuntu
sudo apt install texlive texlive-latex-extra

# Fedora
sudo dnf install texlive-scheme-medium

# Arch
sudo pacman -Syu texlive-most

4. Clone ACTIVA and sync its environment

git clone https://github.com/EdwardoSunny/ACTIVA
cd ACTIVA
uv sync

uv sync creates .venv/, installs the pinned versions from uv.lock (Manim + LangGraph + the four LLM SDKs: openai, anthropic, google-genai, plus openai.AzureOpenAI), and registers the project itself in editable mode.

Verify Manim sees its system libraries:

uv run manim checkhealth

Prefer plain pip? You can still do python -m venv .venv && source .venv/bin/activate && pip install -e . — uv is recommended but not required. If you go this route, drop the uv run prefix from the commands below (e.g. uv run python main.py → python main.py).

5. Set Up API Access

ACTIVA requires an API key from one of the supported LLM providers. You'll need to:

Get API Keys:

• OpenAI: Visit platform.openai.com and create an account
• Claude (Anthropic): Visit console.anthropic.com and sign up
• Gemini (Google): Visit aistudio.google.com and get an API key
• Azure OpenAI: Create a resource and deployment in the Azure Portal

Configure ACTIVA:

uv run python scripts/setup_config.py

Choose your preferred provider and enter your API key when prompted. For Azure, you'll also be asked for your endpoint and deployment name.

6. Supported Models

ACTIVA works directly with each provider's native SDK, so any model accessible to your API key/deployment is supported. Suggested defaults:

• OpenAI: GPT-4o (recommended), GPT-4-turbo, GPT-3.5-turbo
• Claude: Claude Opus 4.7 (recommended), Claude Sonnet 4.6, Claude 3.5 Sonnet
• Gemini: Gemini 1.5 Pro (recommended), Gemini 1.5 Flash, Gemini 2.0 Flash
• Azure OpenAI: any deployment you've created (use the deployment name as the model)

The interactive setup will guide you through model selection.

7. Run ACTIVA

Frontend (Recommended):

uv run python scripts/run_frontend.py

Then open http://localhost:8000 in your browser.

Command Line:

uv run python main.py

📖 See docs/FRONTEND_README.md for detailed frontend usage.

🎯 What is ACTIVA?

ACCOUNTING CONCEPTS TAUGHT INTERACTIVELY WITH VISUAL ANIMATIONS (ACTIVA) is an LLM-based animation tool that generates custom accounting visualizations from natural language prompts. It uses a multi-agent framework to automatically create Manim animations for accounting education, helping students understand complex accounting concepts through visual representations.

✨ Key Features

• Natural Language Input: Describe accounting concepts in plain English
• Multi-Agent System: Intelligent planning, coding, execution, and error recovery
• Multiple LLM Support: Works with OpenAI, Claude, and Gemini
• Error Recovery: Automatic debugging and code correction
• Cost-Effective: Much cheaper than manual animation production
• Accounting-Focused: Specialized for accounting education and concept visualization

🤖 Supported LLM Providers

ACTIVA talks to each provider through its native SDK (openai, anthropic, google-genai, and openai.AzureOpenAI):

OpenAI

• SDK: openai (chat completions)
• Models: GPT-4o, GPT-4-turbo, GPT-3.5-turbo, GPT-5.x
• Setup: Requires OpenAI API key (optional custom base_url for OpenAI-compatible endpoints)

Claude (Anthropic)

• SDK: anthropic (messages API)
• Models: Claude Opus 4.7, Claude Sonnet 4.6, Claude 3.5 Sonnet
• Setup: Requires Anthropic API key

Gemini (Google)

• SDK: google-genai (models.generate_content)
• Models: Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 2.0/3.x
• Setup: Requires Google API key

Azure OpenAI

• SDK: openai.AzureOpenAI (chat completions)
• Models: any deployment in your Azure resource
• Setup: Requires API key, endpoint (https://<resource>.openai.azure.com/), deployment name, and API version (default 2024-10-21)

🏗️ How It Works

ACTIVA uses four specialized agents working together:

1. Planning Agent: Analyzes your prompt and searches for implementation examples
2. Code Writing Agent: Generates Manim Python code based on the task
3. Execution Agent: Runs the animation and checks for success
4. Error Search Agent: Finds fixes if execution fails

The system iterates until successful execution or reaches the maximum attempts.

📁 Project Structure

VisualsGeneration/
├── docs/                  # 📚 Documentation
│   ├── README.md         # Main project documentation (this file)
│   └── FRONTEND_README.md # Frontend usage guide
├── scripts/               # 🔧 Utility Scripts
│   ├── setup_config.py   # LLM provider setup
│   └── run_frontend.py   # Frontend launcher
├── config/                # ⚙️ Configuration
│   ├── config.py         # Configuration management
│   └── config.json       # LLM provider settings (auto-created)
├── .chainlit/             # 🌐 Chainlit Configuration
│   └── config.toml       # Frontend timeout and server settings
├── activa/                # 🧠 Core Agent System
│   ├── agent/            # Multi-agent framework
│   │   ├── graph.py      # Agent workflow definition
│   │   ├── nodes.py      # Individual agent implementations
│   │   └── state.py      # State management
│   └── utils/            # Manim execution utilities
│       └── manim_tools.py # Code execution and error handling
├── frontend.py           # 🌐 Web interface (Chainlit)
├── main.py               # 🖥️ Command line entry point
├── chainlit.md           # 📋 Chainlit sidebar content
├── pyproject.toml        # 📦 Project dependencies
├── LICENSE               # 📄 License information
└── generated_code/       # 📁 Generated animation files

🎬 Example Prompts

• "Create an animation showing how to calculate depreciation expense using the straight-line method"
• "Visualize the accounting equation: Assets = Liabilities + Equity"
• "Show a cash flow statement with animated transitions between operating, investing, and financing activities"
• "Animate a journal entry showing the purchase of equipment on credit"

🔧 Configuration

Interactive Setup

uv run python scripts/setup_config.py

Manual Configuration

Edit config/config.json. The provider must be one of openai, anthropic, google, or azure.

OpenAI / Anthropic / Google:

{
  "provider": "openai",
  "model": "gpt-4o",
  "api_key": "your-api-key-here",
  "base_url": null,
  "max_tokens": 4000
}

Azure OpenAI (the model field doubles as the deployment name):

{
  "provider": "azure",
  "model": "my-gpt4o-deployment",
  "api_key": "your-azure-api-key",
  "azure_endpoint": "https://my-resource.openai.azure.com/",
  "azure_api_version": "2024-10-21",
  "max_tokens": 4000
}

Environment Variables (Alternative)

export ACTIVA_PROVIDER="anthropic"           # openai | anthropic | google | azure
export ACTIVA_MODEL="claude-opus-4-7"
export ACTIVA_API_KEY="your-api-key"
# Azure-only:
export ACTIVA_AZURE_ENDPOINT="https://my-resource.openai.azure.com/"
export ACTIVA_AZURE_API_VERSION="2024-10-21"

Frontend Configuration

The frontend includes extended timeout settings (5 minutes) for long-running operations:

• Agent Generation: Up to 5 minutes for code generation
• Animation Execution: Up to 5 minutes for Manim rendering
• Progress Updates: Real-time status during operations

🚀 Usage Examples

Quick Test

# 1. Setup (one-time)
uv run python scripts/setup_config.py

# 2. Run frontend
uv run python scripts/run_frontend.py

# 3. Open browser to http://localhost:8000
# 4. Type: "Create an animation showing how to calculate accrued salaries expense"

Command Line Usage

# Run the example in main.py (accounting salaries expense example)
uv run python main.py

🔧 Troubleshooting

Common Issues

• Timeout Errors: The frontend is configured with 5-minute timeouts for long operations
• Connection Issues: Check your internet connection and API key validity
• Generation Failures: Try simpler prompts first, then increase complexity

Frontend Issues

• Server Won't Start: Run uv run python scripts/run_frontend.py from the project root
• Timeout During Generation: The system automatically handles long operations
• Animation Execution Fails: Check the generated code in generated_code/ directory

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

🆘 Support

• Open an issue on GitHub
• Check the documentation
• Review example implementations