Romantic Companion AI - Project Structure and Setup Guide

Complete Project Structure

romantic-companion-ai/
├── CLAUDE.md              # Main instruction document for Claude Code
├── setting.json           # Configuration and personality settings
├── README.md              # Project overview and setup guide
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables template
├── _doc/                 # Implementation documentation
│   ├── TEMPLATE_LOG.md   # Template for implementation logs
│   ├── TEMPLATE_EVAL.md  # Template for self-evaluation
│   ├── TEMPLATE_PLAN.md  # Template for action planning
│   ├── logs/             # Implementation logs with timestamps
│   ├── evaluations/      # Self-evaluation reports
│   └── plans/            # Action plans for sessions
├── src/
│   ├── __init__.py
│   ├── main.py           # Entry point
│   ├── core/
│   │   ├── __init__.py
│   │   ├── affinity_engine.py      # Enhanced affinity system
│   │   ├── emotion_processor.py    # Emotional state management
│   │   ├── memory_system.py        # Long-term memory
│   │   ├── personality_core.py     # Dynamic personality
│   │   └── response_generator.py   # Advanced response generation
│   ├── ai/
│   │   ├── __init__.py
│   │   ├── sentiment_analyzer.py   # Multi-layer sentiment analysis
│   │   ├── context_manager.py      # Conversation context
│   │   ├── language_model.py       # Natural language processing
│   │   └── learning_engine.py      # Adaptive learning system
│   ├── personality/
│   │   ├── __init__.py
│   │   ├── traits.py              # Personality trait definitions
│   │   ├── moods.py               # Mood state management
│   │   ├── interests.py           # Interest tracking
│   │   └── relationship_model.py  # Relationship dynamics
│   ├── data/
│   │   ├── __init__.py
│   │   ├── storage.py             # Persistent data management
│   │   ├── encryption.py          # Data security
│   │   └── models.py              # Data models
│   ├── interface/
│   │   ├── __init__.py
│   │   ├── cli.py                 # Command line interface
│   │   ├── commands.py            # Command handlers
│   │   └── display.py             # UI formatting
│   └── utils/
│       ├── __init__.py
│       ├── validators.py          # Input validation
│       ├── decorators.py          # Utility decorators
│       └── helpers.py             # Helper functions
├── tests/
│   ├── __init__.py
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── data/
│   ├── templates/               # Response templates
│   ├── personalities/           # Personality presets
│   └── knowledge/              # Knowledge base
└── logs/                       # Runtime logs

Setup Instructions

Initial Setup

1. Create Project Directory

   mkdir romantic-companion-ai
   cd romantic-companion-ai

2. Initialize Git Repository

   git init
   echo "# Romantic Companion AI" > README.md
   git add README.md
   git commit -m "Initial commit"

3. Create Directory Structure

   # Create all directories
   mkdir -p src/{core,ai,personality,data,interface,utils}
   mkdir -p tests/{unit,integration,fixtures}
   mkdir -p data/{templates,personalities,knowledge}
   mkdir -p _doc/{logs,evaluations,plans}
   mkdir logs
   
   # Create __init__.py files
   touch src/__init__.py
   touch src/core/__init__.py
   touch src/ai/__init__.py
   touch src/personality/__init__.py
   touch src/data/__init__.py
   touch src/interface/__init__.py
   touch src/utils/__init__.py
   touch tests/__init__.py

4. Copy Configuration Files

   • Place CLAUDE.md in the root directory
   • Place setting.json in the root directory
   • Copy all template files to _doc/ directory

5. Create Python Environment

   python -m venv venv
   
   # Activate virtual environment
   # On macOS/Linux:
   source venv/bin/activate
   
   # On Windows:
   venv\Scripts\activate
   
   # Upgrade pip
   pip install --upgrade pip

6. Install Initial Dependencies

   pip install python-dotenv
   pip install typing-extensions
   pip install pydantic
   pip install rich  # For beautiful CLI output
   pip install pytest pytest-cov  # For testing
   pip install cryptography  # For data encryption
   pip install aiofiles  # For async file operations
   pip freeze > requirements.txt

7. Create Environment Files

   # Create .env.example
   cat > .env.example << EOF
   # Application Settings
   APP_NAME=Romantic Companion AI
   APP_VERSION=2.0.0
   
   # Security
   ENCRYPTION_KEY=your-encryption-key-here
   
   # Development
   DEBUG=false
   LOG_LEVEL=INFO
   
   # Data Storage
   DATA_PATH=./data
   USER_DATA_PATH=./data/users
   EOF
   
   # Create actual .env (don't commit this)
   cp .env.example .env
   # Edit .env with your actual values

8. Initialize Documentation

   # Copy templates to _doc directory
   # Create first planning document
   cp _doc/TEMPLATE_PLAN.md "_doc/plans/$(date +%Y%m%d-%H%M%S)-initial-plan.md"
   # Edit the plan with your initial session goals

Development Workflow

1. Before Each Session:

   • Read all previous documents in _doc/logs/, _doc/evaluations/, and _doc/plans/
   • Create new action plan using TEMPLATE_PLAN.md
   • Review CLAUDE.md for implementation guidelines
   • Check current project status

2. During Development:

   • Follow the implementation strategy in your action plan
   • Commit changes frequently with descriptive messages
   • Run tests continuously
   • Update documentation as you go
   • Take notes for your implementation log

3. After Each Session:

   • Create implementation log using TEMPLATE_LOG.md with timestamp
   • Complete self-evaluation using TEMPLATE_EVAL.md
   • Draft next action plan while insights are fresh
   • Commit all documentation to git
   • Backup your work

Testing Strategy

# Run all tests
pytest

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

# Run specific test file
pytest tests/unit/test_affinity_engine.py

# Run with verbose output
pytest -v

# Run only marked tests
pytest -m "unit"

# Watch mode (requires pytest-watch)
pip install pytest-watch
ptw

Code Quality Tools

# Install code quality tools
pip install black flake8 mypy isort

# Format code
black src/

# Check code style
flake8 src/

# Type checking
mypy src/

# Sort imports
isort src/

Git Workflow

# Feature branch workflow
git checkout -b feature/emotional-state-machine
# ... make changes ...
git add .
git commit -m "feat: implement emotional state machine with mood persistence"
git push origin feature/emotional-state-machine

# Commit message format
# feat: new feature
# fix: bug fix
# docs: documentation update
# style: code style update
# refactor: code refactoring
# test: test updates
# chore: build/config updates

Important Notes

1. Documentation is Mandatory: Every coding session MUST include:

   • Implementation log in _doc/logs/
   • Self-evaluation in _doc/evaluations/
   • Next action plan in _doc/plans/

2. Read Previous Work: Always start by reading all previous documentation to understand context and learn from past sessions.

3. Quality Over Speed: Focus on creating a genuine, emotionally intelligent AI rather than rushing features.

4. User Privacy: All user data must be encrypted and stored locally only.

5. Continuous Learning: Each session should build upon previous learnings and improvements.