v0.11.0

.gitignore

@@ -1,5 +1,8 @@
 __pycache__
+.pytest_cache
+agents
 .venv
 build
+plans
 audera.egg-info
 testing*.py

AGENTS.md

@@ -0,0 +1,100 @@
+# Audera Agent Guidelines
+
+## Build/Lint/Test Commands
+
+### Building
+- Install package: `pip install .`
+- Install in development mode: `pip install -e .`
+
+### Linting
+- Run flake8: `flake8`
+- Configuration: max-line-length = 129
+
+### Testing
+- Run test files: `python testing.py` or `python testing_2.py`
+- No formal test framework configured (pytest/unittest not in requirements)
+
+## Code Style Guidelines
+
+### Imports
+- Use absolute imports: `from audera import module`
+- Group imports: standard library, third-party, local
+- Use `from __future__ import annotations` for forward references
+
+### Type Hints
+- Use comprehensive type annotations
+- Use `Literal` for constrained values: `Literal[1, 2]`
+- Use `Union`/`Optional` for complex types
+- Type hint all function parameters and return values
+
+### Naming Conventions
+- Functions/variables: `snake_case`
+- Classes: `PascalCase`
+- Constants: `UPPER_CASE`
+- Private members: `_leading_underscore`
+
+### Documentation
+- Use Google-style docstrings
+- Document all classes, methods, and functions
+- Include parameter descriptions with types
+- Include return value descriptions
+
+### Code Structure
+- Use dataclasses for structured data: `@dataclass`
+- Implement `from_dict()` and `to_dict()` methods for serialization
+- Use `__post_init__()` for dataclass initialization logic
+- Implement `__repr__()` with JSON formatting
+- Implement `__eq__()` for comparison
+
+### Error Handling
+- Use specific exception types (TypeError, KeyError, ValueError)
+- Provide descriptive error messages
+- Validate input parameters
+
+### Formatting
+- Max line length: 129 characters
+- Use 4 spaces for indentation
+- Use single quotes for strings unless containing single quotes
+- Use f-strings for string formatting
+
+### Best Practices
+- Use type checking with `isinstance()`
+- Use list comprehensions for simple transformations
+- Use context managers where appropriate
+- Avoid global state when possible
+- Use meaningful variable names
+- Keep functions focused and single-purpose
+
+## Orchestrator Usage
+- **Import**: `from audera import orchestrator`
+- **Purpose**: Isolate critical tasks from blocking the main event loop
+- **Key Features**:
+  - Thread/process pool execution
+  - Automatic retry on failure
+  - Configurable timeouts
+  - Comprehensive logging
+- **Usage Patterns**:
+  - **Synchronous execution**:
+    ```python
+    orchestrator = audera.orchestrator.Orchestrator(logger=logger)
+    result = orchestrator.run(
+        task_id="unique_task_id",
+        func=critical_function,
+        restart_on_failure=True,
+        timeout=30.0,
+        pool_type="thread"
+    )
+    ```
+  - **Asynchronous execution** (for coroutines):
+    ```python
+    result = await orchestrator.arun(
+        task_id="unique_task_id",
+        coro_func=async_critical_function,
+        restart_on_failure=True,
+        timeout=30.0,
+        pool_type="thread"
+    )
+    ```
+- **Integration**:
+  - `streamer.py`: NTP synchronization, audio streaming, and timing-critical mDNS browsing with player synchronization (blocking I/O and precision timing)
+  - `player.py`: Audio playback, timing-critical streamer synchronization, mDNS broadcasting, audio stream receiving, and deprecated shairport-sync service monitoring (blocking I/O, precision timing, network I/O, and subprocess management)

audera/__init__.py

@@ -7,9 +7,23 @@
 from typing import List
 import errno
 
-from audera import platform, ap, netifaces, ntp, mdns, struct, dal, devices, sessions, logging
+from audera import models, dal
+from audera.services import ap, devices, logging, mdns, media, netifaces, ntp, orchestrator, platform, sessions
 
-__all__ = ['platform', 'ap', 'netifaces', 'ntp', 'mdns', 'struct', 'dal', 'devices', 'sessions', 'logging']
+__all__ = [
+    'platform',
+    'ap',
+    'netifaces',
+    'ntp',
+    'mdns',
+    'models',
+    'dal',
+    'devices',
+    'sessions',
+    'logging',
+    'orchestrator',
+    'media',
+]
 
 # Logo
 LOGO: List[str] = [

audera/cli/commands.py

@@ -2,7 +2,8 @@
 
 from typing import Literal
 import asyncio
-from audera import player, streamer, ui, netifaces
+from audera import player, streamer, ui
+from audera.services import netifaces
 
 
 # Define audera sub-command function(s)
@@ -59,7 +60,7 @@ def run(
     except KeyboardInterrupt:
 
         # Logging
-        service.logger.info("Shutting down the services.")
+        service.logger.info("Shutting down the services...")
 
     finally:
 

audera/dal/devices.py

@@ -3,7 +3,7 @@
 from typing import Union, Literal
 import os
 from pytensils import config
-from audera.struct import audio
+from audera.models import audio
 from audera.dal import path
 
 

audera/dal/groups.py

@@ -4,7 +4,7 @@
 import os
 import duckdb
 from pytensils import config, utils
-from audera.struct import player
+from audera.models import player
 from audera.dal import path, players
 
 

audera/dal/identities.py

@@ -3,7 +3,7 @@
 from typing import Union
 import os
 from pytensils import config
-from audera.struct import identity
+from audera.models import identity
 from audera.dal import path
 
 

audera/dal/interfaces.py

@@ -3,7 +3,7 @@
 from typing import Union
 import os
 from pytensils import config
-from audera.struct import audio
+from audera.models import audio
 from audera.dal import path
 
 

audera/dal/players.py

@@ -4,7 +4,7 @@
 import os
 import duckdb
 from pytensils import config, utils
-from audera.struct import identity, player
+from audera.models import identity, player
 from audera.dal import path
 
 

audera/dal/sessions.py

@@ -4,7 +4,7 @@
 import os
 import copy
 from pytensils import config, utils
-from audera.struct import session, player
+from audera.models import session, player
 from audera.dal import path, players, groups
 
 

audera/models/__init__.py

@@ -0,0 +1,8 @@
+""" Structures """
+
+from audera.models import identity
+from audera.models import audio
+from audera.models import player
+from audera.models import session
+
+__all__ = ['identity', 'audio', 'player', 'session']