apsimo 1.3.0__py3-none-any.whl

apsimo/turns/audio.py

@@ -0,0 +1,134 @@
+"""Bounded supplied audio and fallible transcript segments, never remote fetches."""
+from __future__ import annotations
+
+import base64
+from datetime import datetime
+import hashlib
+import io
+import math
+import wave
+
+MAX_AUDIO_BYTES = 4 * 1024 * 1024
+MAX_AUDIO_SECONDS = 60
+
+
+def decode_audio(block):
+    item = block.get('input_audio')
+    if (not isinstance(item, dict) or set(item) != {'data', 'format'}
+            or item['format'] != 'wav' or not isinstance(item['data'], str)
+            or len(item['data']) > MAX_AUDIO_BYTES * 4 // 3 + 16):
+        raise ValueError('unsupported_or_oversized_audio')
+    data = base64.b64decode(item['data'], validate=True)
+    if len(data) > MAX_AUDIO_BYTES:
+        raise ValueError('oversized_audio')
+    with wave.open(io.BytesIO(data), 'rb') as clip:
+        rate, frames = clip.getframerate(), clip.getnframes()
+        if (clip.getnchannels() != 1 or clip.getsampwidth() != 2 or clip.getcomptype() != 'NONE'
+                or not 8000 <= rate <= 48000 or not 0 < frames <= rate * MAX_AUDIO_SECONDS
+                or len(clip.readframes(frames + 1)) != frames * 2):
+            raise ValueError('unsupported_audio_encoding_or_duration')
+    return data, {'sample_rate': rate, 'channels': 1, 'sample_width_bytes': 2,
+                  'duration_ms': frames * 1000 / rate, 'frame_count': frames}
+
+
+def transcript(block, data, duration_ms):
+    """Validate supplied recognition lineage; clocks are not inferred from text."""
+    if (not isinstance(block, dict) or set(block) != {'type', 'audio_sha256', 'segments',
+            'recognizer', 'received_at', 'captured_at'} or block['type'] != 'audio_transcript'
+            or block['audio_sha256'] != hashlib.sha256(data).hexdigest()):
+        raise ValueError('audio_transcript_parent_mismatch')
+    segments = block['segments']
+    if not isinstance(segments, list) or not 1 <= len(segments) <= 32:
+        raise ValueError('unsupported_transcript_segments')
+    previous = 0
+    for segment in segments:
+        if (not isinstance(segment, dict) or set(segment) != {'start_ms', 'end_ms', 'text'}
+                or not isinstance(segment['text'], str) or not 1 <= len(segment['text']) <= 12000
+                or any(type(segment[key]) not in (int, float) or not math.isfinite(segment[key])
+                       for key in ('start_ms', 'end_ms'))
+                or not previous <= segment['start_ms'] < segment['end_ms'] <= duration_ms + .001):
+            raise ValueError('invalid_transcript_segment')
+        previous = segment['end_ms']
+    for key in ('received_at', 'captured_at'):
+        value = block[key]
+        if value is None and key == 'captured_at':
+            continue
+        if not isinstance(value, str) or len(value) > 64 or datetime.fromisoformat(value.replace('Z', '+00:00')).tzinfo is None:
+            raise ValueError('invalid_audio_clock')
+    model = block['recognizer']
+    if (not isinstance(model, dict) or set(model) != {'model_id', 'model_revision'}
+            or any(not isinstance(value, str) or not 1 <= len(value) <= 256 for value in model.values())):
+        raise ValueError('invalid_recognizer_provenance')
+    return {**block, 'asset_id': 'sha256:' + block['audio_sha256'],
+            'epistemic_state': 'derived_unverified', 'timing_basis': 'supplied_clip_offsets',
+            'confidence': None}
+
+
+def _render(content):
+    """One rendering for source indexing, exact claim spans and recall."""
+    if isinstance(content, str):
+        return content, []
+    parts, segments, length = [], [], 0
+
+    def append(text):
+        nonlocal length
+        start = length + bool(parts)
+        parts.append(text)
+        length = start + len(text)
+        return start
+
+    blocks = content if isinstance(content, list) else []
+    for index, block in enumerate(blocks):
+        if not isinstance(block, dict):
+            continue
+        if block.get('type') in {'text', 'input_text', 'output_text'} and isinstance(block.get('text'), str):
+            append(block['text'])
+        elif block.get('type') == 'audio_transcript' and block.get('epistemic_state') == 'derived_unverified':
+            parent = blocks[index - 1] if index else {}
+            owned = (isinstance(parent, dict) and parent.get('type') == 'audio'
+                     and parent.get('asset_id') == block['asset_id'])
+            for segment_index, segment in enumerate(block.get('segments', [])):
+                prefix = (f"Unverified machine transcript [{segment['start_ms'] / 1000:.3f}.."
+                          f"{segment['end_ms'] / 1000:.3f}s of {block['asset_id']}]: ")
+                start = append(prefix + segment['text']) + len(prefix)
+                if owned:
+                    segments.append({'block_index': index, 'segment_index': segment_index,
+                        'asset_id': block['asset_id'], 'start_ms': segment['start_ms'], 'end_ms': segment['end_ms'],
+                        'source_start': start, 'source_end': start + len(segment['text']),
+                        **{key: block[key] for key in ('recognizer', 'received_at', 'captured_at',
+                                                      'timing_basis', 'confidence')}})
+    return '\n'.join(parts), segments
+
+
+def source_text(content):
+    """Text-only recall of retained evidence; raw audio never enters prompts."""
+    return _render(content)[0]
+
+
+def claim_message(message):
+    """An internal extraction view, never a second canonical user message.
+
+    Complete surrounding text remains available to interpret narrative scope.
+    Only retained, paired ASR word ranges become eligible derived evidence.
+    """
+    if isinstance(message.get('content'), str):
+        return message
+    text, segments = _render(message.get('content'))
+    return {**message, 'content': text, '_audio_segments': segments} if segments else None
+
+
+def claim_basis(message, start, end):
+    for segment in message.get('_audio_segments', []):
+        if segment['source_start'] <= start < end <= segment['source_end']:
+            return {'epistemic_state': 'derived_unverified', 'source_modality': 'audio_transcript',
+                    'segment': {**segment, 'evidence_start': start - segment['source_start'],
+                                'evidence_end': end - segment['source_start']}}
+    return None
+
+
+def evidence_metadata(message):
+    content = message.get('content')
+    if isinstance(content, list) and any(isinstance(block, dict) and block.get('type') == 'audio_transcript'
+            and block.get('epistemic_state') == 'derived_unverified' for block in content):
+        return {'epistemic_state': 'derived_unverified', 'source_modality': 'audio_transcript'}
+    return {}

apsimo/turns/documents.py

@@ -0,0 +1,235 @@
+"""Bounded PDF extraction from owned bytes, never paths supplied by a caller.
+
+This file also runs as a standalone isolated child. Keep imports at module load
+in the standard library so resource limits precede loading the PDF parser.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import io
+import json
+import logging
+from pathlib import Path
+import sys
+
+MAX_DOCUMENT_BYTES = 4 * 1024 * 1024
+MAX_PAGES = 64
+MAX_PAGE_STREAM_BYTES = 2 * 1024 * 1024
+MAX_PAGE_CHARS = 32000
+MAX_TEXT_CHARS = 200000
+MAX_RESULT_BYTES = 6 * MAX_TEXT_CHARS + 65536
+MAX_PARSE_SECONDS = 15
+MAX_MEMORY_BYTES = 384 * 1024 * 1024
+MEMORY_SAMPLE_INTERVAL_MS = 25
+VERSION = 'source-pdf-text-v1'
+
+
+def decode_document(block):
+    """Only explicit inline PDF bytes are supported by this ingestion contract."""
+    item = block.get('input_document')
+    if (set(block) != {'type', 'input_document'} or not isinstance(item, dict)
+            or set(item) != {'mime_type', 'data'} or item.get('mime_type') != 'application/pdf'
+            or not isinstance(item.get('data'), str)):
+        raise ValueError('unsupported_document_input')
+    if len(item['data']) > ((MAX_DOCUMENT_BYTES + 2) // 3) * 4:
+        raise ValueError('document_bytes_exceed_limit')
+    try:
+        data = base64.b64decode(item['data'], validate=True)
+    except (ValueError, TypeError):
+        raise ValueError('invalid_document_encoding') from None
+    if len(data) > MAX_DOCUMENT_BYTES:
+        raise ValueError('document_bytes_exceed_limit')
+    # This is a bounded admission signature check, not a PDF parser. Malformed
+    # PDF-looking originals remain retained with an honest extraction failure.
+    if not data.startswith(b'%PDF-'):
+        raise ValueError('unsupported_document_format')
+    return data
+
+
+def disposition(status, reason=None, *, parser_version=None, page_count=None, pages=None):
+    return {'version': VERSION, 'parser': 'pypdf', 'parser_version': parser_version,
+            'status': status, 'reason': reason, 'page_count': page_count,
+            'pages': pages or [], 'ocr_performed': False,
+            'epistemic_state': 'derived_unverified'}
+
+
+def _extract(data):
+    """Called only inside the resource-limited child, including in tests."""
+    try:
+        import pypdf
+    except ImportError:
+        return disposition('failed', 'parser_unavailable')
+    version = pypdf.__version__
+    if not data.startswith(b'%PDF-') or len(data) > MAX_DOCUMENT_BYTES:
+        return disposition('failed', 'invalid_retained_document', parser_version=version)
+    try:
+        reader = pypdf.PdfReader(io.BytesIO(data), strict=True)
+        if reader.is_encrypted:
+            return disposition('unsupported', 'encrypted_pdf', parser_version=version)
+        count = len(reader.pages)
+        if not 0 < count <= MAX_PAGES:
+            return disposition('unsupported', 'page_count_exceeds_limit' if count else 'empty_pdf',
+                               parser_version=version, page_count=count)
+        pages, total = [], 0
+        for number, page in enumerate(reader.pages, 1):
+            contents = page.get_contents()
+            # Decompression itself is inside the memory/CPU fence.
+            if contents is not None and len(contents.get_data()) > MAX_PAGE_STREAM_BYTES:
+                return disposition('unsupported', 'page_stream_exceeds_limit', parser_version=version,
+                                   page_count=count)
+            text = page.extract_text() or ''
+            total += len(text)
+            if len(text) > MAX_PAGE_CHARS or total > MAX_TEXT_CHARS:
+                return disposition('unsupported', 'extracted_text_exceeds_limit', parser_version=version,
+                                   page_count=count)
+            pages.append({'page': number, 'text': text,
+                          'status': 'text' if text.strip() else 'no_extractable_text'})
+        text_pages = sum(page['status'] == 'text' for page in pages)
+        return disposition('complete' if text_pages == count else 'partial' if text_pages else 'unsupported',
+                           None if text_pages == count else 'no_extractable_text_on_some_pages' if text_pages
+                           else 'no_extractable_text', parser_version=version, page_count=count, pages=pages)
+    except MemoryError:
+        return disposition('unsupported', 'parser_memory_limit', parser_version=version)
+    except Exception:
+        # Parser errors can contain document text. Persist a code, not that text.
+        return disposition('failed', 'invalid_or_unreadable_pdf', parser_version=version)
+
+
+def _child():
+    logging.disable(logging.CRITICAL)
+    memory_control = 'address_space'
+    try:
+        import resource
+        resource.setrlimit(resource.RLIMIT_CPU, (10, 10))
+        resource.setrlimit(resource.RLIMIT_CORE, (0, 0))
+        try:
+            resource.setrlimit(resource.RLIMIT_AS, (MAX_MEMORY_BYTES, MAX_MEMORY_BYTES))
+        except (ValueError, OSError):
+            if sys.platform != 'darwin' or sys.argv[1:] != ['--rss-guarded']:
+                raise
+            memory_control = 'sampled_rss'
+    except (ImportError, ValueError, OSError):
+        result = disposition('unsupported', 'parser_resource_limits_unavailable')
+    else:
+        # The guarded parent samples this PID before sending stdin. No parser
+        # import or PDF decoding starts until that parent closes the pipe.
+        result = _extract(sys.stdin.buffer.read(MAX_DOCUMENT_BYTES + 1))
+        result.update(_memory_metadata(memory_control))
+    sys.stdout.buffer.write(json.dumps(result, ensure_ascii=True).encode())
+
+
+def _memory_metadata(control):
+    return {'memory_control': control, 'memory_limit_bytes': MAX_MEMORY_BYTES,
+            'memory_sample_interval_ms': MEMORY_SAMPLE_INTERVAL_MS if control == 'sampled_rss' else None,
+            'hard_limit': control == 'address_space'}
+
+
+class _MemoryGuardError(RuntimeError):
+    pass
+
+
+def _sample_rss(target):
+    import psutil
+    try:
+        if not target.is_running():
+            raise psutil.NoSuchProcess(target.pid)
+        rss = target.memory_info().rss
+        if type(rss) is not int or rss < 0:
+            raise ValueError('invalid RSS')
+    except psutil.NoSuchProcess as exc:
+        raise _MemoryGuardError('parser_memory_monitor_exited') from exc
+    except Exception as exc:
+        raise _MemoryGuardError('parser_memory_monitor_failed') from exc
+    if rss > MAX_MEMORY_BYTES:
+        raise _MemoryGuardError('parser_memory_limit')
+
+
+async def _watch_rss(process, target):
+    # Best-effort resident memory samples; scheduling and allocations can
+    # exceed this interval/threshold. This is not an OS memory allocation cap.
+    while process.returncode is None:
+        try:
+            _sample_rss(target)
+        except _MemoryGuardError as exc:
+            if str(exc) == 'parser_memory_monitor_exited':
+                await asyncio.sleep(0)  # Let a genuine exit notification settle.
+                if process.returncode is not None:
+                    return
+            raise
+        await asyncio.sleep(MEMORY_SAMPLE_INTERVAL_MS / 1000)
+
+
+async def extract_document(data):
+    """No model, OCR, fetch, embedded action, or file reference is executed."""
+    guarded = sys.platform == 'darwin'
+    if guarded:
+        try:
+            import psutil
+        except ImportError:
+            return disposition('unsupported', 'parser_memory_monitor_unavailable')
+    process = await asyncio.create_subprocess_exec(
+        sys.executable, '-I', str(Path(__file__).resolve()),
+        *(['--rss-guarded'] if guarded else []),
+        stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL)
+    communication = watcher = target = None
+    guard_metadata = {}
+    try:
+        async with asyncio.timeout(MAX_PARSE_SECONDS):
+            if guarded:
+                try:
+                    target = psutil.Process(process.pid)
+                except Exception as exc:
+                    raise _MemoryGuardError('parser_memory_monitor_unavailable') from exc
+                guard_metadata = _memory_metadata('sampled_rss')
+                _sample_rss(target)  # Must succeed before any PDF bytes go in.
+                watcher = asyncio.create_task(_watch_rss(process, target))
+            communication = asyncio.create_task(process.communicate(data))
+            if watcher is not None:
+                await asyncio.wait((communication, watcher), return_when=asyncio.FIRST_COMPLETED)
+                if watcher.done():
+                    watcher.result()  # A breach takes precedence over output.
+            output, _ = await asyncio.shield(communication)
+        if process.returncode:
+            return disposition('failed', 'parser_process_failed_or_resource_limit') | guard_metadata
+        if len(output) > MAX_RESULT_BYTES:
+            return disposition('failed', 'parser_output_exceeds_limit') | guard_metadata
+        result = json.loads(output)
+        if result.get('version') != VERSION or result.get('status') not in {'complete', 'partial', 'unsupported', 'failed'}:
+            raise ValueError('invalid parser result')
+        return result
+    except asyncio.TimeoutError:
+        return disposition('failed', 'parser_time_limit') | guard_metadata
+    except _MemoryGuardError as exc:
+        reason = 'parser_memory_monitor_failed' if str(exc) == 'parser_memory_monitor_exited' else str(exc)
+        return disposition('unsupported', reason) | guard_metadata
+    except (ValueError, TypeError):
+        return disposition('failed', 'invalid_parser_result') | guard_metadata
+    finally:
+        try:
+            if process.returncode is None:
+                try:
+                    if target is None:
+                        process.kill()
+                    else:
+                        try:
+                            target.kill()  # Checks this bound PID's identity.
+                        except psutil.NoSuchProcess:
+                            pass
+                        except psutil.Error:
+                            process.kill()  # Owned-child Popen also polls first.
+                except ProcessLookupError:
+                    pass
+        finally:
+            if watcher is not None:
+                watcher.cancel()
+            if communication is None:
+                communication = asyncio.create_task(process.communicate())
+            # Drain pipes while reaping, including cancellation during output.
+            await asyncio.gather(communication, *([watcher] if watcher is not None else []), return_exceptions=True)
+            await process.wait()
+
+
+if __name__ == '__main__':
+    _child()