slide-narrator 0.4.0__tar.gz → 1.0.1__tar.gz

{slide_narrator-0.4.0 → slide_narrator-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide-narrator
-Version: 0.4.0
+Version: 1.0.1
 Summary: Thread and file storage components for conversational AI - the companion to Tyler AI framework
 Project-URL: Homepage, https://github.com/adamwdraper/slide
 Project-URL: Repository, https://github.com/adamwdraper/slide
@@ -74,19 +74,72 @@ pip install slide-narrator
 
 ## Setup
 
+### Docker Setup (Recommended for Development)
+
+For local development with PostgreSQL, Narrator includes built-in Docker commands:
+
+```bash
+# One-command setup: starts PostgreSQL and initializes tables
+uv run narrator docker-setup
+
+# This will:
+# 1. Start a PostgreSQL container
+# 2. Wait for it to be ready  
+# 3. Initialize the database tables
+# 4. Show you the connection string
+
+# The database will be available at:
+# postgresql+asyncpg://narrator:narrator_dev@localhost:5432/narrator
+```
+
+To manage the Docker container:
+
+```bash
+# Stop container (preserves data)
+uv run narrator docker-stop
+
+# Stop and remove all data
+uv run narrator docker-stop --remove-volumes
+
+# Start container again
+uv run narrator docker-start
+
+# Check database status
+uv run narrator status
+```
+
+For custom configurations, the Docker commands respect environment variables:
+
+```bash
+# Use a different port
+uv run narrator docker-setup --port 5433
+
+# Or set environment variables (matching docker-compose.yml)
+export NARRATOR_DB_NAME=mydb
+export NARRATOR_DB_USER=myuser
+export NARRATOR_DB_PASSWORD=mypassword
+export NARRATOR_DB_PORT=5433
+
+# Then run docker-setup
+uv run narrator docker-setup
+
+# This will create:
+# postgresql+asyncpg://myuser:mypassword@localhost:5433/mydb
+```
+
 ### Database Setup
 
 For production use with PostgreSQL or SQLite persistence, you'll need to initialize the database tables:
 
 ```bash
 # Initialize database tables (PostgreSQL)
-narrator-db init --database-url "postgresql+asyncpg://user:password@localhost/dbname"
+uv run narrator init --database-url "postgresql+asyncpg://user:password@localhost/dbname"
 
 # Initialize database tables (SQLite)
-narrator-db init --database-url "sqlite+aiosqlite:///path/to/your/database.db"
+uv run narrator init --database-url "sqlite+aiosqlite:///path/to/your/database.db"
 
 # Check database status
-narrator-db status --database-url "postgresql+asyncpg://user:password@localhost/dbname"
+uv run narrator status --database-url "postgresql+asyncpg://user:password@localhost/dbname"
 ```
 
 You can also use environment variables instead of passing the database URL:
@@ -96,8 +149,8 @@ You can also use environment variables instead of passing the database URL:
 export NARRATOR_DATABASE_URL="postgresql+asyncpg://user:password@localhost/dbname"
 
 # Then run without --database-url flag
-narrator-db init
-narrator-db status
+uv run narrator init
+uv run narrator status
 ```
 
 ### Environment Variables
@@ -382,22 +435,22 @@ The Narrator includes a CLI tool for database management:
 
 ```bash
 # Initialize database tables
-narrator-db init --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
+uv run narrator init --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
 
 # Initialize using environment variable
 export NARRATOR_DATABASE_URL="postgresql+asyncpg://user:pass@localhost/dbname"
-narrator-db init
+uv run narrator init
 
 # Check database status
-narrator-db status --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
+uv run narrator status --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
 
 # Check status using environment variable
-narrator-db status
+uv run narrator status
 ```
 
 Available commands:
-- `narrator-db init` - Initialize database tables
-- `narrator-db status` - Check database connection and basic statistics
+- `uv run narrator init` - Initialize database tables
+- `uv run narrator status` - Check database connection and basic statistics
 
 ## Key Design Principles
 

{slide_narrator-0.4.0 → slide_narrator-1.0.1}/README.md

@@ -39,19 +39,72 @@ pip install slide-narrator
 
 ## Setup
 
+### Docker Setup (Recommended for Development)
+
+For local development with PostgreSQL, Narrator includes built-in Docker commands:
+
+```bash
+# One-command setup: starts PostgreSQL and initializes tables
+uv run narrator docker-setup
+
+# This will:
+# 1. Start a PostgreSQL container
+# 2. Wait for it to be ready  
+# 3. Initialize the database tables
+# 4. Show you the connection string
+
+# The database will be available at:
+# postgresql+asyncpg://narrator:narrator_dev@localhost:5432/narrator
+```
+
+To manage the Docker container:
+
+```bash
+# Stop container (preserves data)
+uv run narrator docker-stop
+
+# Stop and remove all data
+uv run narrator docker-stop --remove-volumes
+
+# Start container again
+uv run narrator docker-start
+
+# Check database status
+uv run narrator status
+```
+
+For custom configurations, the Docker commands respect environment variables:
+
+```bash
+# Use a different port
+uv run narrator docker-setup --port 5433
+
+# Or set environment variables (matching docker-compose.yml)
+export NARRATOR_DB_NAME=mydb
+export NARRATOR_DB_USER=myuser
+export NARRATOR_DB_PASSWORD=mypassword
+export NARRATOR_DB_PORT=5433
+
+# Then run docker-setup
+uv run narrator docker-setup
+
+# This will create:
+# postgresql+asyncpg://myuser:mypassword@localhost:5433/mydb
+```
+
 ### Database Setup
 
 For production use with PostgreSQL or SQLite persistence, you'll need to initialize the database tables:
 
 ```bash
 # Initialize database tables (PostgreSQL)
-narrator-db init --database-url "postgresql+asyncpg://user:password@localhost/dbname"
+uv run narrator init --database-url "postgresql+asyncpg://user:password@localhost/dbname"
 
 # Initialize database tables (SQLite)
-narrator-db init --database-url "sqlite+aiosqlite:///path/to/your/database.db"
+uv run narrator init --database-url "sqlite+aiosqlite:///path/to/your/database.db"
 
 # Check database status
-narrator-db status --database-url "postgresql+asyncpg://user:password@localhost/dbname"
+uv run narrator status --database-url "postgresql+asyncpg://user:password@localhost/dbname"
 ```
 
 You can also use environment variables instead of passing the database URL:
@@ -61,8 +114,8 @@ You can also use environment variables instead of passing the database URL:
 export NARRATOR_DATABASE_URL="postgresql+asyncpg://user:password@localhost/dbname"
 
 # Then run without --database-url flag
-narrator-db init
-narrator-db status
+uv run narrator init
+uv run narrator status
 ```
 
 ### Environment Variables
@@ -347,22 +400,22 @@ The Narrator includes a CLI tool for database management:
 
 ```bash
 # Initialize database tables
-narrator-db init --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
+uv run narrator init --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
 
 # Initialize using environment variable
 export NARRATOR_DATABASE_URL="postgresql+asyncpg://user:pass@localhost/dbname"
-narrator-db init
+uv run narrator init
 
 # Check database status
-narrator-db status --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
+uv run narrator status --database-url "postgresql+asyncpg://user:pass@localhost/dbname"
 
 # Check status using environment variable
-narrator-db status
+uv run narrator status
 ```
 
 Available commands:
-- `narrator-db init` - Initialize database tables
-- `narrator-db status` - Check database connection and basic statistics
+- `uv run narrator init` - Initialize database tables
+- `uv run narrator status` - Check database connection and basic statistics
 
 ## Key Design Principles
 

{slide_narrator-0.4.0 → slide_narrator-1.0.1}/narrator/__init__.py

@@ -8,7 +8,7 @@ from .models.thread import Thread
 from .models.message import Message
 from .models.attachment import Attachment
 
-__version__ = "0.4.0"
+__version__ = "1.0.1"
 __all__ = [
     "ThreadStore",
     "FileStore", 

slide_narrator-1.0.1/narrator/database/cli.py

@@ -0,0 +1,222 @@
+"""Database CLI for Tyler Stores"""
+import asyncio
+import os
+import click
+import functools
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from .thread_store import ThreadStore
+from ..utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+@click.group()
+def main():
+    """Narrator CLI - Database management commands"""
+    pass
+
+@main.command()
+@click.option('--database-url', help='Database URL for initialization')
+def init(database_url):
+    """Initialize database tables"""
+    async def _init():
+        try:
+            # Use provided URL or check environment variable
+            url = database_url or os.environ.get('NARRATOR_DATABASE_URL')
+            
+            if url:
+                store = await ThreadStore.create(url)
+            else:
+                # Use in-memory storage
+                store = await ThreadStore.create()
+            
+            logger.info("Database initialized successfully")
+            click.echo("Database initialized successfully")
+        except Exception as e:
+            logger.error(f"Failed to initialize database: {e}")
+            click.echo(f"Error: Failed to initialize database: {e}")
+            raise click.Abort()
+    
+    asyncio.run(_init())
+
+@main.command()
+@click.option('--database-url', help='Database URL')
+def status(database_url):
+    """Check database status"""
+    async def _status():
+        try:
+            # Use provided URL or check environment variable
+            url = database_url or os.environ.get('NARRATOR_DATABASE_URL')
+            
+            if url:
+                store = await ThreadStore.create(url)
+            else:
+                store = await ThreadStore.create()
+            
+            # Get some basic stats
+            threads = await store.list_recent(limit=5)
+            click.echo(f"Database connection: OK")
+            click.echo(f"Recent threads count: {len(threads)}")
+            
+        except Exception as e:
+            logger.error(f"Database status check failed: {e}")
+            click.echo(f"Error: Database status check failed: {e}")
+            raise click.Abort()
+    
+    asyncio.run(_status())
+
+@main.command()
+@click.option('--port', help='Port to expose PostgreSQL on (default: 5432 or NARRATOR_DB_PORT)')
+@click.option('--detach/--no-detach', default=True, help='Run container in background (default: True)')
+def docker_start(port, detach):
+    """Start a PostgreSQL container for Narrator"""
+    # Use environment variables with defaults matching docker-compose.yml
+    db_name = os.environ.get('NARRATOR_DB_NAME', 'narrator')
+    db_user = os.environ.get('NARRATOR_DB_USER', 'narrator')
+    db_password = os.environ.get('NARRATOR_DB_PASSWORD', 'narrator_dev')
+    db_port = port or os.environ.get('NARRATOR_DB_PORT', '5432')
+    
+    docker_compose_content = f"""services:
+  postgres:
+    image: postgres:16
+    container_name: narrator-postgres
+    environment:
+      POSTGRES_DB: {db_name}
+      POSTGRES_USER: {db_user}
+      POSTGRES_PASSWORD: {db_password}
+    ports:
+      - "{db_port}:5432"
+    volumes:
+      - narrator_postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {db_user}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  narrator_postgres_data:
+"""
+    
+    # Create a temporary directory for docker-compose.yml
+    with tempfile.TemporaryDirectory() as tmpdir:
+        compose_file = Path(tmpdir) / "docker-compose.yml"
+        compose_file.write_text(docker_compose_content)
+        
+        # Check if docker is available
+        try:
+            subprocess.run(["docker", "--version"], capture_output=True, check=True)
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            click.echo("❌ Docker is not installed or not available in PATH")
+            raise click.Abort()
+        
+        # Check if docker-compose or docker compose is available
+        compose_cmd = None
+        try:
+            subprocess.run(["docker", "compose", "version"], capture_output=True, check=True)
+            compose_cmd = ["docker", "compose"]
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            try:
+                subprocess.run(["docker-compose", "version"], capture_output=True, check=True)
+                compose_cmd = ["docker-compose"]
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                click.echo("❌ Docker Compose is not installed")
+                raise click.Abort()
+        
+        # Start the container
+        click.echo("📦 Starting PostgreSQL container...")
+        cmd = compose_cmd + ["up"]
+        if detach:
+            cmd.append("-d")
+        
+        result = subprocess.run(cmd, cwd=tmpdir)
+        
+        if result.returncode != 0:
+            click.echo("❌ Failed to start PostgreSQL container")
+            raise click.Abort()
+        
+        if detach:
+            # Wait for PostgreSQL to be ready
+            click.echo("⏳ Waiting for PostgreSQL to be ready...")
+            for i in range(30):
+                result = subprocess.run(
+                    ["docker", "exec", "narrator-postgres", "pg_isready", "-U", db_user],
+                    capture_output=True
+                )
+                if result.returncode == 0:
+                    click.echo("✅ PostgreSQL is ready!")
+                    click.echo(f"\n🎉 Database available at:")
+                    click.echo(f"   postgresql+asyncpg://{db_user}:{db_password}@localhost:{db_port}/{db_name}")
+                    return
+                time.sleep(1)
+            
+            click.echo("❌ PostgreSQL failed to start after 30 seconds")
+            raise click.Abort()
+
+@main.command()
+@click.option('--remove-volumes', is_flag=True, help='Remove data volumes (destroys all data)')
+def docker_stop(remove_volumes):
+    """Stop the PostgreSQL container"""
+    # Check if docker is available
+    try:
+        subprocess.run(["docker", "--version"], capture_output=True, check=True)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        click.echo("❌ Docker is not installed or not available in PATH")
+        raise click.Abort()
+    
+    # Check if container exists
+    result = subprocess.run(
+        ["docker", "ps", "-a", "--format", "{{.Names}}"],
+        capture_output=True,
+        text=True
+    )
+    
+    if "narrator-postgres" not in result.stdout:
+        click.echo("ℹ️  No Narrator PostgreSQL container found")
+        return
+    
+    click.echo("🛑 Stopping PostgreSQL container...")
+    
+    # Stop the container
+    subprocess.run(["docker", "stop", "narrator-postgres"], check=False)
+    subprocess.run(["docker", "rm", "narrator-postgres"], check=False)
+    
+    if remove_volumes:
+        click.echo("🗑️  Removing data volume...")
+        subprocess.run(["docker", "volume", "rm", "narrator_postgres_data"], check=False)
+        click.echo("✅ Container and data removed")
+    else:
+        click.echo("✅ Container stopped (data preserved)")
+
+@main.command()
+@click.option('--port', help='Port to expose PostgreSQL on (default: 5432 or NARRATOR_DB_PORT)')
+def docker_setup(port):
+    """One-command Docker setup: start PostgreSQL and initialize tables"""
+    # Start PostgreSQL
+    ctx = click.get_current_context()
+    ctx.invoke(docker_start, port=port, detach=True)
+    
+    # Get database configuration from environment or defaults
+    db_name = os.environ.get('NARRATOR_DB_NAME', 'narrator')
+    db_user = os.environ.get('NARRATOR_DB_USER', 'narrator')
+    db_password = os.environ.get('NARRATOR_DB_PASSWORD', 'narrator_dev')
+    db_port = port or os.environ.get('NARRATOR_DB_PORT', '5432')
+    
+    # Set up database URL
+    database_url = f"postgresql+asyncpg://{db_user}:{db_password}@localhost:{db_port}/{db_name}"
+    os.environ['NARRATOR_DATABASE_URL'] = database_url
+    
+    # Initialize tables
+    click.echo("\n🔧 Initializing database tables...")
+    ctx.invoke(init, database_url=database_url)
+    
+    click.echo("\n🎉 Setup complete! Your database is ready.")
+    click.echo("\nTo use in your code:")
+    click.echo(f'export NARRATOR_DATABASE_URL="{database_url}"')
+    click.echo("\nTo stop the container: narrator docker-stop")
+    click.echo("To remove all data: narrator docker-stop --remove-volumes")
+
+if __name__ == '__main__':
+    main() 

{slide_narrator-0.4.0 → slide_narrator-1.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "slide-narrator"
-version = "0.4.0"
+version = "1.0.1"
 description = "Thread and file storage components for conversational AI - the companion to Tyler AI framework"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -48,7 +48,7 @@ Repository = "https://github.com/adamwdraper/slide"
 "Bug Tracker" = "https://github.com/adamwdraper/slide/issues"
 
 [project.scripts]
-narrator-db = "narrator.database.cli:main"
+narrator = "narrator.database.cli:main"
 
 [tool.uv.sources]
 # No workspace dependencies for narrator currently

slide_narrator-0.4.0/narrator/database/cli.py

@@ -1,66 +0,0 @@
-"""Database CLI for Tyler Stores"""
-import asyncio
-import click
-from .thread_store import ThreadStore
-from ..utils.logging import get_logger
-
-logger = get_logger(__name__)
-
-@click.group()
-def main():
-    """Tyler Stores Database CLI"""
-    pass
-
-@click.command()
-@click.option('--database-url', help='Database URL for initialization')
-async def init(database_url):
-    """Initialize database tables"""
-    try:
-        if database_url:
-            store = await ThreadStore.create(database_url)
-        else:
-            # Use environment variables or default
-            store = await ThreadStore.create()
-        
-        logger.info("Database initialized successfully")
-        click.echo("Database initialized successfully")
-    except Exception as e:
-        logger.error(f"Failed to initialize database: {e}")
-        click.echo(f"Error: Failed to initialize database: {e}")
-        raise click.Abort()
-
-@click.command()
-@click.option('--database-url', help='Database URL')
-async def status(database_url):
-    """Check database status"""
-    try:
-        if database_url:
-            store = await ThreadStore.create(database_url)
-        else:
-            store = await ThreadStore.create()
-        
-        # Get some basic stats
-        threads = await store.list_recent(limit=5)
-        click.echo(f"Database connection: OK")
-        click.echo(f"Recent threads count: {len(threads)}")
-        
-    except Exception as e:
-        logger.error(f"Database status check failed: {e}")
-        click.echo(f"Error: Database status check failed: {e}")
-        raise click.Abort()
-
-# Add async wrapper for commands
-def async_command(f):
-    def wrapper(*args, **kwargs):
-        return asyncio.run(f(*args, **kwargs))
-    return wrapper
-
-# Apply async wrapper to commands
-init = click.command()(async_command(init))
-status = click.command()(async_command(status))
-
-main.add_command(init)
-main.add_command(status)
-
-if __name__ == '__main__':
-    main()