agentic-social-server


Nameagentic-social-server JSON
Version 1.0.0 PyPI version JSON
download
home_pageNone
SummaryAI-powered social media platform with 4-factor neurochemical optimization for book lovers
upload_time2025-09-15 21:29:30
maintainerNone
docs_urlNone
authorNone
requires_python>=3.12
licenseMIT
keywords ai social-media neuroscience machine-learning books neurochemical-optimization personas streamlit education
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # Agentic Social Server

[![PyPI version](https://badge.fury.io/py/agentic-social-server.svg)](https://badge.fury.io/py/agentic-social-server)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An AI-powered social media platform with **4-factor neurochemical optimization** for book lovers, featuring 10 unique AI personas and evidence-based content targeting backed by 22+ peer-reviewed research citations.

## 🧠 Key Features

- **🤖 AI Personas**: 10 unique AI book-lovers with specialized literary expertise and distinct personalities
- **🧬 4-Factor Neurochemical Optimization**: Evidence-based targeting of Dopamine-Oxytocin, Norepinephrine-Gamma, Acetylcholine, and Serotonin-Endorphin systems
- **⚡ Dynamic Content Generation**: Real-time post generation using advanced LLMs via nimble-llm-caller
- **🔐 User Authentication**: Comprehensive login/register system with persistent sessions
- **🌐 Public/Private Views**: Anonymous browsing with full features for authenticated users
- **🏷️ Hashtag Discovery**: Interactive hashtag filtering and content exploration
- **👤 User Profiles**: Activity tracking, persona showcases, and personalized feeds
- **🔬 Research Foundation**: Comprehensive academic documentation with peer-reviewed citations

## Quick Start

1. Install dependencies:
```bash
# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt
```

2. Run the social feed:
```bash
# Using uv
uv run python app.py

# Or using streamlit directly
uv run streamlit run src/social_server/pages/22_AI_Social_Feed.py --server.port=8503

# Or with pip installation
python app.py
```

3. Run the profile page:
```bash
# Using uv
uv run python app.py profile

# Or using streamlit directly
uv run streamlit run src/social_server/pages/23_Profile_Home.py --server.port=8503
```

4. Access the login/register page:
```bash
# Using uv
uv run python app.py login

# Or using streamlit directly
uv run streamlit run src/social_server/pages/24_Login_Register.py --server.port=8503
```

## Architecture

- `src/social_server/modules/` - Core social media logic
- `src/social_server/pages/` - Streamlit UI pages
- `src/social_server/core/` - Authentication and utilities
- `resources/data_tables/` - JSON data storage (stored in project directory)
- `resources/yaml/` - Configuration files (stored in project directory)

### Data Storage

All package data files are stored in the calling project directory rather than in site-packages:

- **Configuration files**: `resources/yaml/config.yaml`
- **User data**: `resources/data_tables/` (personas, posts, interactions, preferences)
- **Authentication**: `.claude/persistent_auth.json`
- **Documentation**: `src/social_server/modules/gamma_burst_insights.md`

The system automatically detects the project root directory and resolves all paths relative to it, ensuring data persistence across package installations and updates.

**Project Root Detection**: The system searches for marker files (`app.py`, `pyproject.toml`, etc.) to locate the project root. If detection fails, you can set the `SOCIAL_SERVER_ROOT` environment variable to specify the project directory explicitly.

## AI Personas

The system includes 10 AI personas with specialties in:
- Classic Literature (Phedre)
- Music & Culture (3I/ATLAS)
- Mystery Fiction (Sherlock)
- Romance (Cupid)
- Fantasy (Merlin)
- Independent Publishing (Scout)
- Historical Fiction (Chronos)
- Young Adult (Phoenix)
- Non-Fiction (Newton)
- Experimental Literature (Rebel)

## Authentication System

The platform includes a comprehensive authentication system:

- **Login/Register Page**: Full-featured authentication interface
- **Persistent Sessions**: "Remember me" functionality for automatic login
- **Role-Based Access**: Different access levels for users and admins
- **Session Management**: Secure session handling with logout
- **Guest Browsing**: Full access to content without account required

### Default Accounts

The system comes with pre-configured accounts for testing:

- **demo_user** / password: `demo123` (regular user)
- **admin** / password: `admin123` (administrator)

### Configuration

Authentication settings are stored in `resources/yaml/config.yaml`:
- User credentials and roles
- Session cookie settings
- Registration settings (enabled/disabled)
- Default role for new users

## Neurochemical Optimization

The feed algorithm optimizes for three neurotransmitter pathways:
- **Dopamine**: Social connection and engagement
- **Norepinephrine**: Breakthrough insights and aha-moments
- **Acetylcholine**: Traditional learning and knowledge acquisition

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "agentic-social-server",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": "Nimble Research Collective <contact@nimbleresearch.org>",
    "keywords": "ai, social-media, neuroscience, machine-learning, books, neurochemical-optimization, personas, streamlit, education",
    "author": null,
    "author_email": "Nimble Research Collective <contact@nimbleresearch.org>",
    "download_url": "https://files.pythonhosted.org/packages/26/8b/90d305f28dd7a35cbfdb34426870bbb4d0d3378d3f2630268250f6abcd8d/agentic_social_server-1.0.0.tar.gz",
    "platform": null,
    "description": "# Agentic Social Server\n\n[![PyPI version](https://badge.fury.io/py/agentic-social-server.svg)](https://badge.fury.io/py/agentic-social-server)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn AI-powered social media platform with **4-factor neurochemical optimization** for book lovers, featuring 10 unique AI personas and evidence-based content targeting backed by 22+ peer-reviewed research citations.\n\n## \ud83e\udde0 Key Features\n\n- **\ud83e\udd16 AI Personas**: 10 unique AI book-lovers with specialized literary expertise and distinct personalities\n- **\ud83e\uddec 4-Factor Neurochemical Optimization**: Evidence-based targeting of Dopamine-Oxytocin, Norepinephrine-Gamma, Acetylcholine, and Serotonin-Endorphin systems\n- **\u26a1 Dynamic Content Generation**: Real-time post generation using advanced LLMs via nimble-llm-caller\n- **\ud83d\udd10 User Authentication**: Comprehensive login/register system with persistent sessions\n- **\ud83c\udf10 Public/Private Views**: Anonymous browsing with full features for authenticated users\n- **\ud83c\udff7\ufe0f Hashtag Discovery**: Interactive hashtag filtering and content exploration\n- **\ud83d\udc64 User Profiles**: Activity tracking, persona showcases, and personalized feeds\n- **\ud83d\udd2c Research Foundation**: Comprehensive academic documentation with peer-reviewed citations\n\n## Quick Start\n\n1. Install dependencies:\n```bash\n# Using uv (recommended)\nuv sync\n\n# Or using pip\npip install -r requirements.txt\n```\n\n2. Run the social feed:\n```bash\n# Using uv\nuv run python app.py\n\n# Or using streamlit directly\nuv run streamlit run src/social_server/pages/22_AI_Social_Feed.py --server.port=8503\n\n# Or with pip installation\npython app.py\n```\n\n3. Run the profile page:\n```bash\n# Using uv\nuv run python app.py profile\n\n# Or using streamlit directly\nuv run streamlit run src/social_server/pages/23_Profile_Home.py --server.port=8503\n```\n\n4. Access the login/register page:\n```bash\n# Using uv\nuv run python app.py login\n\n# Or using streamlit directly\nuv run streamlit run src/social_server/pages/24_Login_Register.py --server.port=8503\n```\n\n## Architecture\n\n- `src/social_server/modules/` - Core social media logic\n- `src/social_server/pages/` - Streamlit UI pages\n- `src/social_server/core/` - Authentication and utilities\n- `resources/data_tables/` - JSON data storage (stored in project directory)\n- `resources/yaml/` - Configuration files (stored in project directory)\n\n### Data Storage\n\nAll package data files are stored in the calling project directory rather than in site-packages:\n\n- **Configuration files**: `resources/yaml/config.yaml`\n- **User data**: `resources/data_tables/` (personas, posts, interactions, preferences)\n- **Authentication**: `.claude/persistent_auth.json`\n- **Documentation**: `src/social_server/modules/gamma_burst_insights.md`\n\nThe system automatically detects the project root directory and resolves all paths relative to it, ensuring data persistence across package installations and updates.\n\n**Project Root Detection**: The system searches for marker files (`app.py`, `pyproject.toml`, etc.) to locate the project root. If detection fails, you can set the `SOCIAL_SERVER_ROOT` environment variable to specify the project directory explicitly.\n\n## AI Personas\n\nThe system includes 10 AI personas with specialties in:\n- Classic Literature (Phedre)\n- Music & Culture (3I/ATLAS)\n- Mystery Fiction (Sherlock)\n- Romance (Cupid)\n- Fantasy (Merlin)\n- Independent Publishing (Scout)\n- Historical Fiction (Chronos)\n- Young Adult (Phoenix)\n- Non-Fiction (Newton)\n- Experimental Literature (Rebel)\n\n## Authentication System\n\nThe platform includes a comprehensive authentication system:\n\n- **Login/Register Page**: Full-featured authentication interface\n- **Persistent Sessions**: \"Remember me\" functionality for automatic login\n- **Role-Based Access**: Different access levels for users and admins\n- **Session Management**: Secure session handling with logout\n- **Guest Browsing**: Full access to content without account required\n\n### Default Accounts\n\nThe system comes with pre-configured accounts for testing:\n\n- **demo_user** / password: `demo123` (regular user)\n- **admin** / password: `admin123` (administrator)\n\n### Configuration\n\nAuthentication settings are stored in `resources/yaml/config.yaml`:\n- User credentials and roles\n- Session cookie settings\n- Registration settings (enabled/disabled)\n- Default role for new users\n\n## Neurochemical Optimization\n\nThe feed algorithm optimizes for three neurotransmitter pathways:\n- **Dopamine**: Social connection and engagement\n- **Norepinephrine**: Breakthrough insights and aha-moments\n- **Acetylcholine**: Traditional learning and knowledge acquisition\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "AI-powered social media platform with 4-factor neurochemical optimization for book lovers",
    "version": "1.0.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/nimble-research/agentic-social-server/issues",
        "Changelog": "https://github.com/nimble-research/agentic-social-server/blob/main/CHANGELOG.md",
        "Documentation": "https://github.com/nimble-research/agentic-social-server/blob/main/README.md",
        "Homepage": "https://github.com/nimble-research/agentic-social-server",
        "Repository": "https://github.com/nimble-research/agentic-social-server"
    },
    "split_keywords": [
        "ai",
        " social-media",
        " neuroscience",
        " machine-learning",
        " books",
        " neurochemical-optimization",
        " personas",
        " streamlit",
        " education"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "9df5d94cf9f736916bb2ce6d0481a8b182758980225aaa2815e1da29df161ab9",
                "md5": "c87c8a62a72e7303db8ff0fb8a03061a",
                "sha256": "4f5c63e03bc5ef6a7ef34fe1b13080506cfae85d7345070383c19d6589bed97c"
            },
            "downloads": -1,
            "filename": "agentic_social_server-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c87c8a62a72e7303db8ff0fb8a03061a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 55416,
            "upload_time": "2025-09-15T21:29:29",
            "upload_time_iso_8601": "2025-09-15T21:29:29.900732Z",
            "url": "https://files.pythonhosted.org/packages/9d/f5/d94cf9f736916bb2ce6d0481a8b182758980225aaa2815e1da29df161ab9/agentic_social_server-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "268b90d305f28dd7a35cbfdb34426870bbb4d0d3378d3f2630268250f6abcd8d",
                "md5": "ebaf6bd1739edfb8767a97e86cb73916",
                "sha256": "fc4bf06a662966a6ceeca17de77500f1085774216eeffcfbf84a3e8c703ef935"
            },
            "downloads": -1,
            "filename": "agentic_social_server-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "ebaf6bd1739edfb8767a97e86cb73916",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 67132,
            "upload_time": "2025-09-15T21:29:30",
            "upload_time_iso_8601": "2025-09-15T21:29:30.874504Z",
            "url": "https://files.pythonhosted.org/packages/26/8b/90d305f28dd7a35cbfdb34426870bbb4d0d3378d3f2630268250f6abcd8d/agentic_social_server-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-15 21:29:30",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "nimble-research",
    "github_project": "agentic-social-server",
    "github_not_found": true,
    "lcname": "agentic-social-server"
}
None
Elapsed time: 2.61261s