Metadata-Version: 2.4
Name: taocore-human
Version: 0.3.0
Summary: Image & video pipelines for human behavior and emotion signals using TaoCore
Project-URL: Homepage, https://github.com/daidaitaotao/taocore-human
Project-URL: Repository, https://github.com/daidaitaotao/taocore-human
Author: Xianglong Tao
License: MIT
Keywords: analysis,behavior,emotion,equilibrium,human,image,signals,taocore,video
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Requires-Dist: numpy>=1.24.0
Requires-Dist: taocore>=0.1.0
Provides-Extra: clip
Requires-Dist: torch>=2.0.0; extra == 'clip'
Requires-Dist: transformers>=4.30.0; extra == 'clip'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: image
Requires-Dist: pillow>=9.0.0; extra == 'image'
Provides-Extra: mediapipe
Requires-Dist: mediapipe>=0.10.0; extra == 'mediapipe'
Provides-Extra: ml
Requires-Dist: opencv-python>=4.5.0; extra == 'ml'
Requires-Dist: pillow>=9.0.0; extra == 'ml'
Requires-Dist: torch>=2.0.0; extra == 'ml'
Requires-Dist: torchvision>=0.15.0; extra == 'ml'
Requires-Dist: transformers>=4.30.0; extra == 'ml'
Provides-Extra: video
Requires-Dist: opencv-python>=4.5.0; extra == 'video'
Requires-Dist: pillow>=9.0.0; extra == 'video'
Description-Content-Type: text/markdown

# taocore-human

Image & video pipelines for human behavior and emotion signals using [TaoCore](https://github.com/daidaitaotao/taocore).

## Philosophy

This package processes photos and videos into **interpretable, bounded claims** about behavior and emotion *signals*. It does **not** claim to read minds or determine truth about internal states.

**Key principles:**
- Outputs are "signals" and "patterns", not definitive judgments
- Uncertainty is always explicit
- Non-convergence is meaningful (signals may conflict)
- Conservative by default for human/emotion inference

## Installation

```bash
# Basic (stub extractors only)
pip install taocore-human

# With image support
pip install taocore-human[image]

# With video support
pip install taocore-human[video]

# With ML models (PyTorch)
pip install taocore-human[ml]
```

## Quick Start

### Photo Folder Analysis

```python
from taocore_human import PhotoFolderPipeline

# Process a folder of photos
pipeline = PhotoFolderPipeline("/path/to/photos")
result = pipeline.run()

# Check if interpretation is allowed
if result.interpretation_allowed:
    print(result.report.summary)
    print(result.report.behavioral_summary)
else:
    print("Interpretation declined:", result.rejection_reasons)
    print(result.report.structural_summary)  # Still available

# Export to JSON
print(pipeline.to_json(result))
```

### Video Interaction Analysis

```python
from taocore_human import VideoInteractionPipeline

# Process a video
pipeline = VideoInteractionPipeline("/path/to/video.mp4")
result = pipeline.run()

# Temporal patterns
print(result.temporal_patterns)

# Report
print(result.report.summary)
```

## Architecture

```
Media → Feature Extraction → Nodes/Edges → Graph(s)
                                              ↓
                            Metrics (balance/flow/clusters/hubs)
                                              ↓
                                    Equilibrium Solver
                                              ↓
                                      Decider Rules
                                              ↓
                                  Uncertainty-Aware Report
```

## What This System Does NOT Do

- Diagnose mental health or medical conditions
- Produce definitive judgments about personality or intent
- Act as a lie detector or "truth machine"
- Replace human interpretation in sensitive contexts

## Components

### Nodes
- `PersonNode` - Tracked individual with aggregated features
- `FrameNode` / `WindowNode` - Time slices for temporal analysis
- `ContextNode` - Scene context (lighting, quality, etc.)

### Extractors (Pluggable)
- `FaceExtractor` - Face detection and expression signals
- `PoseExtractor` - Body pose estimation
- `GazeExtractor` - Attention/gaze estimation
- `SceneExtractor` - Scene-level features
- `StubExtractor` - Random data for testing

### Pipelines
- `PhotoFolderPipeline` - Process folder of images
- `VideoInteractionPipeline` - Process video with temporal analysis

## Output Example

```json
{
  "interpretation_allowed": true,
  "confidence_level": "moderate",
  "num_persons_analyzed": 3,
  "summary": "Analysis of 3 individuals completed with moderate confidence. Signal patterns show convergent stability.",
  "limitations": [
    "Expression and emotion signals are probabilistic estimates, not ground truth about internal states."
  ],
  "recommendations": [
    "Findings may inform further investigation but should not be treated as definitive.",
    "Never use these signals for high-stakes decisions without human oversight."
  ]
}
```

## License

MIT
## CLI Quick Start

1. Install editable (dev):
```bash
cd /Users/dadatoto/taocore-human
python -m pip install -e .
```

2. Analyze a folder of photos:
```bash
taocore-human photo-folder /path/to/photos
```

3. Analyze a video:
```bash
taocore-human video /path/to/video.mp4
```

4. Save JSON output to a file:
```bash
taocore-human photo-folder /path/to/photos --output /tmp/taocore_result.json
```

