FamilyCLI 👨‍👩‍👧‍👦

A warm, child-safe AI family chat experience in your terminal

🚧 Beta Release Notice

Welcome to Family AI CLI v1.1.0! 🎉

This is our initial beta release and we're thrilled to have you as part of our testing community! Your feedback and contributions are invaluable in making this the best family-friendly AI experience possible.

🐛 Found a bug or have suggestions? We'd love to hear from you!

• Report Issues: GitHub Issues
• Request Features: Feature Requests
• General Discussion: GitHub Discussions

Thank you for helping us improve Family AI CLI! 🙏

About Family AI CLI

FamilyCLI brings AI-powered family members to life in your command line. Chat with loving personas like Grandma Rose, Uncle Joe, Dad Mike, and more - each with unique personalities, memories, and caring responses designed for children and families.

✨ Features

v1.1 New Features 🎉

• 🧠 Memory & Continuity - Personas remember conversations and preferences across sessions
• 🎭 Rich Persona Templates - Advanced personality traits, tones, knowledge domains, and quirks
• 👨‍👩‍👧‍👦 Family Tree View - Visual family relationships and tree navigation
• 📦 Persona Packs - Pre-built persona collections and community sharing
• 🎭 Scene Mode - Immersive storytelling with multi-persona roleplay
• 📊 User Feedback Loop - Rate responses and continuous improvement
• 🔄 Configuration Reload - Update settings without restart
• 🏗️ Production Architecture - Enhanced error handling and scalability

Core Features

• 🏠 6 Unique Family Members - Each with distinct personalities and LLM providers
• 💭 Conversation Memory - Personas remember and reference previous messages
• 🛡️ Child-Safe Responses - Carefully engineered prompts for appropriate, caring interactions
• 🔐 Secure API Storage - Encrypted API key management in ~/.familyai
• 🔄 Multi-Provider Support - Groq, OpenAI, Anthropic, Cerebras, Google
• 📱 WhatsApp-like Interface - Familiar chat experience with recent conversations
• 🎨 Rich UI - Beautiful terminal interface with markdown support
• ⚡ Retry & Fallback - Robust error handling and graceful degradation

🚀 Quick Start

Installation

Option 1: Install from PyPI (Recommended)

pip install familycli

Option 2: Install from Source

# Clone the repository
git clone https://github.com/AIMLDev726/ai-family-cli.git
cd ai-family-cli

# Install in development mode
pip install -e .

# PyPI Project URL
https://pypi.org/project/familycli/1.0.0/

First Run

# Start the Family AI CLI
familycli

# Or if installed from source
python -m familycli.main

Setup API Keys

1. Choose option 4 (Settings & Management)
2. Select API Key Management
3. Add keys for your preferred providers (Groq recommended for speed)

📋 CLI Commands

# Main command
familycli                    # Start the family chat interface

# New v1.1 Commands
familycli tree              # Display family tree visualization
familycli add-pack          # Install persona packs
familycli scene             # Start immersive scene mode
familycli feedback          # View feedback statistics
familycli memory            # View persona memories
familycli reload            # Reload configuration

# Alternative (if installed from source)
python -m familycli.main          # Direct module execution

Usage

1. Initialize the database:

   python -m familycli.main
   

2. Register a user and login via CLI prompts.
3. Create personas, start chat sessions, and interact with AI family members.

Configuration Management

• All configuration is managed via JSON files in the familycli/config/ directory and can be overridden by environment variables.
• Use familycli/config/config_manager.py to load, get, and reload config at runtime.
• Example:

  from familycli.config.config_manager import ConfigManager
  config = ConfigManager().load('llm_providers')
  value = ConfigManager().get('llm_providers', 'default_provider')
  ConfigManager().reload('llm_providers')
  

• Environment variable override: set LLM_PROVIDERS_OPENAI_API_KEY to override OpenAI key in config.

Performance Optimization

• Database uses connection pooling and batch commit for high throughput.
• LLM responses are cached (LRU) and API usage is tracked for cost management.

Error Handling

• All critical operations have robust error handling and failover logic.
• LLM manager supports rate limit handling and provider failover.
• Streaming and chat modules recover from deadlocks and interruptions.

Runtime Reload

• You can reload configuration at runtime using the reload method in ConfigManager and UniversalLLMManager.

Project Structure

familycli/
├── familycli/
│   ├── auth/
│   ├── personas/
│   ├── chat/
│   ├── llm/
│   ├── database/
│   ├── ui/
│   ├── config/
│   └── main.py
├── examples/
├── requirements.txt
├── README.md
├── pyproject.toml
├── MANIFEST.in
└── LICENCE

Security

• All sensitive data is encrypted at rest.
• API keys are stored securely and never exposed in logs.

Testing

• Run unit and integration tests with pytest:

  pytest
  

Extending

• Add new LLM providers by implementing a subclass of BaseLLMProvider.
• Add new UI features in familycli/ui/.

👨‍💻 Creator

Created by AIMLDev726

• Email: aistudentlearn4@gmail.com
• GitHub: @AIMLDev726

🐛 Reporting Issues & Getting Help

How to Report a Bug

1. Check Existing Issues: Browse current issues to see if it's already reported
2. Create New Issue: Report a new bug
3. Provide Details: Include the following information:

Bug Description A clear description of what went wrong

Steps to Reproduce

1. Go to '...'
2. Click on '...'
3. See error

Expected Behavior What you expected to happen

Environment

• OS: [e.g., Windows 11, macOS 13, Ubuntu 22.04]
• Python Version: [e.g., 3.11.5]
• Family CLI Version: [e.g., 1.0.0]

Error Messages Any error messages or logs (check ~/.familyai/logs/familycli.log)

Screenshots If applicable, add screenshots to help explain the problem

Request a Feature

Have an idea to make Family AI CLI better? Request a feature and include:

• Feature Description: What you'd like to see added
• Use Case: How this would help families
• Child Safety: How this maintains our family-friendly focus

Beta Testing Feedback

As a beta tester, your feedback is especially valuable! Please share:

• What works well: Features you love and find useful
• What's confusing: Areas that need better documentation or UX
• Performance issues: Slow responses, crashes, or errors
• Family experience: How your family interacts with the AI personas
• Safety concerns: Any responses that seem inappropriate for children

Get Help

• GitHub Discussions: Ask questions and share ideas
• Documentation: Check our Contributing Guide
• Email: aistudentlearn4@gmail.com for private matters

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• How to submit bug reports and feature requests
• Development setup and coding standards
• Pull request process
• Code of conduct

Quick Contributing Steps

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

📄 License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

See the LICENSE file for details.

What this means:

• ✅ You can use this software for any purpose
• ✅ You can modify and distribute the software
• ✅ You can use it in proprietary software
• ⚠️ If you modify MPL-licensed files, you must share those modifications
• ⚠️ You must include the original license and copyright notices

🙏 Acknowledgments

• Built with ❤️ for families who want safe AI interactions
• Powered by multiple LLM providers for the best experience
• Inspired by the need for child-safe AI conversations

Family AI CLI - Bringing AI family members to life in your terminal! 👨‍👩‍👧‍👦