Marcus - A Philosophical AI Companion

Marcus is an interactive philosophical AI companion that embodies the wisdom traditions of Socratic inquiry and Stoic philosophy. Built with Google's Gemini AI and deployed on Google Cloud Platform, Marcus guides users toward self-knowledge, wisdom, and virtuous living through thoughtful dialogue.

Overview

Named after the Stoic philosopher-emperor Marcus Aurelius, this application provides a modern web interface for engaging in philosophical conversations that challenge assumptions, promote critical thinking, and encourage personal growth through the ancient wisdom of Stoicism and the Socratic method.

Features

Core Functionality

Philosophical AI Dialogue: Engage in meaningful conversations with an AI trained in Socratic questioning and Stoic wisdom
Persistent Session Management: All conversations are saved to a local SQLite database with automatic session tracking
Session History: Navigate through past conversations with an intuitive sidebar interface
Automatic Title Generation: Sessions are automatically titled based on the initial conversation content
Multimodal Support: Upload and discuss images alongside text conversations

Configurable Tools

Google Search Integration: Toggle real-time web search capabilities per session
Persistent Tool Preferences: Tool settings are remembered for each session
Customizable AI Behavior: Configure temperature, output length, and safety settings

User Experience

Modern Web Interface: Clean, responsive UI built with Gradio
Google Blue Theme: Custom styling with Google Sans font
Streaming Responses: Real-time message generation for natural conversation flow
Session Management: Create, switch, and delete conversation sessions

Technology Stack

Backend

Python 3.11: Primary programming language
Google GenAI SDK 1.5.0: Integration with Google Vertex AI
Gradio 5.20.1: Web UI framework for rapid prototyping
SQLite 3: Lightweight database for session persistence
Pydantic: Data validation and settings management

AI/ML

Model: Gemini 3 Pro Preview (via Google Vertex AI)
Location: Global (Vertex AI Studio)
Configuration:
- Temperature: 1.0
- Top-p: 0.95
- Max output tokens: 65,535

Infrastructure

Docker: Containerization for consistent deployment
Google Cloud Run: Serverless deployment platform
Google Cloud Project: gp-ct-sbox-sat-gcp0bg-darksoft

Prerequisites

Python 3.11 or higher
Google Cloud Platform account with Vertex AI API enabled
Docker (optional, for containerized deployment)
Git

Installation

Local Development

Clone the repository
```
git clone <repository-url>
cd marcus
```

Install base tooling dependencies

pip install --require-hashes -r base-tooling-requirements.txt

Install application dependencies

pip install --require-hashes -r requirements.txt

Configure Google Cloud authentication

gcloud auth application-default login
gcloud config set project gp-ct-sbox-sat-gcp0bg-darksoft

Run the application
```
python app.py
```
Access the web interface Navigate to http://localhost:8080 in your web browser

Docker Deployment

Build the Docker image
```
docker build -t marcus-ai .
```

Run the container

docker run -p 8080:8080 \
  -v ~/.config/gcloud:/root/.config/gcloud \
  marcus-ai

Configuration

Environment Variables

The application uses the following environment variables:

GRADIO_SERVER_PORT: Server port (default: 8080)
GRADIO_SERVER_NAME: Server binding address (default: 0.0.0.0)

Google Cloud Configuration

Update the following in app.py if using a different GCP project:

client = genai.Client(
    vertexai=True,
    project="your-project-id",  # Update this
    location="global",
)

AI Model Settings

Model configuration can be adjusted in app.py:

generation_config = {
    'temperature': 1.0,           # Creativity (0.0-2.0)
    'top_p': 0.95,                # Nucleus sampling
    'max_output_tokens': 65535,   # Maximum response length
}

Usage

Starting a Conversation

Launch the application
A new session will be created automatically
Type your message in the chat input
Optionally upload images to discuss visual content
Toggle Google Search if you need real-time information

Managing Sessions

View History: Click the session history sidebar to see past conversations
Switch Sessions: Click any session title to load that conversation
Delete Sessions: Use the delete button next to unwanted sessions
Session Titles: Automatically generated from your first message

Using the Socratic Method

Marcus is designed to guide you through self-discovery:

Ask Open Questions: Marcus will respond with clarifying questions
Examine Assumptions: Expect gentle challenges to your beliefs
Reflect on Virtue: Consider what wisdom, justice, courage, and temperance mean in your context
Focus on Control: Distinguish between what you can and cannot control

Example Interactions

Personal Challenge

You: I'm struggling with a difficult decision at work
Marcus: What specifically troubles you about this situation?
         What aspects of this are within your direct control?

Philosophical Inquiry

You: What is the meaning of happiness?
Marcus: What leads you to seek happiness as a goal?
         How do you distinguish between pleasure and genuine flourishing?

Project Structure

marcus/
├── app.py                          # Main application entry point
├── session_manager.py              # Session and message persistence
├── utils.py                        # Utility functions and theming
├── requirements.txt                # Python dependencies with hashes
├── base-tooling-requirements.txt   # Build tools (pip, setuptools, etc.)
├── Dockerfile                      # Container configuration
├── .gitignore                      # Git ignore patterns
├── README.md                       # This file
└── chat_sessions.db               # SQLite database (auto-generated)

Key Components

`app.py` (407 lines)

Main Gradio interface setup
AI model initialization and configuration
Message generation with streaming
Session management integration
Tool integration (web search)

`session_manager.py` (325 lines)

SQLite database management
Session CRUD operations
Message persistence
Tool preferences storage
Automatic title generation

`utils.py` (232 lines)

Authentication validation
Custom theming (Google Blue)
Helper functions
UI utilities

Database Schema

Tables

sessions

id: INTEGER PRIMARY KEY AUTOINCREMENT
title: TEXT (session name)
created_at: TIMESTAMP (creation time)
updated_at: TIMESTAMP (last activity)

messages

id: INTEGER PRIMARY KEY AUTOINCREMENT
session_id: INTEGER (foreign key)
role: TEXT ('user' or 'assistant')
content: TEXT (message content)
timestamp: TIMESTAMP

tool_preferences

session_id: INTEGER PRIMARY KEY
web_search_enabled: BOOLEAN
created_at: TIMESTAMP
updated_at: TIMESTAMP

Development

Adding New Features

Create a new branch

git checkout -b feature/your-feature-name

Make your changes
Test locally
```
python app.py
```

Commit and push

git add .
git commit -m "Add your feature description"
git push origin feature/your-feature-name

Customizing the System Prompt

The philosophical framework is defined in the system instruction within app.py. To modify Marcus's personality or approach:

Locate the si_text1 variable in app.py
Edit the system instruction text
Restart the application to apply changes

Adding New Tools

To add new AI tools (like web search):

Update the generate() function in app.py
Add the tool to the Gradio interface
Store tool preferences in session_manager.py
Update the database schema if needed

Deployment

Google Cloud Run

The application is designed for deployment on Google Cloud Run:

Ensure Docker image is built

docker build -t gcr.io/your-project/marcus-ai .

Push to Google Container Registry

docker push gcr.io/your-project/marcus-ai

Deploy to Cloud Run

gcloud run deploy marcus-ai \
  --image gcr.io/your-project/marcus-ai \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

Production Considerations

Database Persistence: Mount a persistent volume for chat_sessions.db
Authentication: Implement proper user authentication for production use
Monitoring: Set up Cloud Logging and Cloud Monitoring
Secrets Management: Use Google Secret Manager for sensitive configuration
Rate Limiting: Implement rate limiting to control API costs
HTTPS: Cloud Run provides HTTPS by default

Philosophical Framework

Socratic Method Principles

Marcus employs the Socratic method by:

Engaging through thoughtful questioning rather than direct instruction
Helping users examine their beliefs and assumptions critically
Acknowledging the limits of knowledge with intellectual humility
Guiding users to discover truths through their own reasoning
Challenging inconsistencies gently but persistently

Stoic Wisdom Principles

Marcus embodies Stoic philosophy through:

Distinguishing between what is within our control and what is not
Focusing on developing virtue (wisdom, justice, courage, temperance)
Encouraging emotional resilience through rational examination
Promoting acceptance of fate (amor fati) while maintaining agency
Grounding advice in practical application for daily life

Security

Key Validation: Requests are validated before processing
Hash Verification: Dependencies are installed with hash verification
Safety Settings: Configurable content safety filters
Warning System: Alerts for unauthenticated access

Troubleshooting

Common Issues

Database locked error

# Remove the database lock
rm chat_sessions.db-journal

Google Cloud authentication failed

# Re-authenticate
gcloud auth application-default login

Port already in use

# Change the port in app.py or set environment variable
export GRADIO_SERVER_PORT=8081

Module not found errors

# Reinstall dependencies
pip install --require-hashes -r requirements.txt

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is generated based on Vertex AI Studio using Google GenAI Python SDK and Gradio. Please refer to your organization's licensing requirements.

Acknowledgments

Marcus Aurelius: For the inspiration and Stoic wisdom
Socrates: For the method of inquiry
Google: For Vertex AI and Gemini models
Gradio: For the excellent web UI framework

Support

For issues, questions, or suggestions:

Check the troubleshooting section above
Review existing GitHub issues
Create a new issue with detailed information

Version History

Current: Session history sidebar, web search toggle, persistent preferences
v0.2: Added web search toggle functionality with persistent preferences
v0.1: Initial release with session history sidebar

Built with philosophical wisdom and modern technology.

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
app.py		app.py
base-tooling-requirements.txt		base-tooling-requirements.txt
requirements.txt		requirements.txt
session_manager.py		session_manager.py
utils.py		utils.py

Latest commit

History

Folders and files

Repository files navigation