# cognitive-signal

Extract orthogonal cognitive signals from journal entries.

## Installation

```bash
pip install cognitive-signal
```

Download the spaCy model:

```bash
python -m spacy download en_core_web_sm
```

## Quick Start

```python
from datetime import datetime
from cognitive_signal import SignalDetectionPipeline, JournalEntry

# Create journal entries
entries = [
    JournalEntry(
        text="I felt empowered today. Made a big decision at work.",
        timestamp=datetime(2024, 1, 1),
        entry_id="1"
    ),
    JournalEntry(
        text="Worried about the consequences. Maybe I was too hasty.",
        timestamp=datetime(2024, 1, 2),
        entry_id="2"
    ),
    JournalEntry(
        text="Talked to my team and we aligned on the approach.",
        timestamp=datetime(2024, 1, 3),
        entry_id="3"
    ),
]

# Run the pipeline
pipeline = SignalDetectionPipeline()
result = pipeline.process_journal(entries)

# Access signal values
for entry_id, signal in result.signals.items():
    print(f"Entry {entry_id}:")
    print(f"  Valence: {signal.valence:.2f}")
    print(f"  Arousal: {signal.arousal:.2f}")
    print(f"  Agency: {signal.agency:.2f}")

# Temporal trends
for signal_name, trend in result.temporal_trends.items():
    print(f"{signal_name}: slope={trend.slope:.3f}, direction={trend.direction}")

# HMM states
print(f"States: {result.segmentation.states}")
print(f"Phases: {result.segmentation.phases}")

# Change points
for cp in result.change_points:
    print(f"Change at index {cp.index}: {cp.signals_changed}")
```

## The 7 Signals

| Signal | Description |
|--------|-------------|
| **Valence** | Emotional polarity from negative (-1) to positive (+1) |
| **Arousal** | Activation level from calm (0) to excited (1) |
| **Agency** | Internal locus of control vs. external attribution |
| **Self-Focus** | First-person singular pronoun density |
| **Social Orientation** | References to others and relationships |
| **Temporal Orientation** | Focus on past, present, or future |
| **Action Ratio** | Verb density indicating action vs. reflection |

## Processing Layers

1. **Signal Extraction** - Extract 7 orthogonal cognitive signals from raw text
2. **Temporal Analysis** - Detect trends, slopes, and momentum in signals over time
3. **Semantic Motion** - Track drift in embedding space and identify thematic shifts
4. **HMM Segmentation** - Discover latent psychological states using Hidden Markov Models
5. **Change Point Detection** - Identify structural breaks in signal patterns

### Layer 1.5: Dissonance Detection

Between signal extraction and temporal analysis, dissonance detection identifies contradictions:

- **Valence-Agency Dissonance**: Positive emotions but low agency (or vice versa)
- **Self-Social Dissonance**: High self-focus combined with high social orientation
- **Temporal Dissonance**: Conflicting temporal orientations within same entry
- **Action-Reflection Dissonance**: High action words but reflective/uncertain tone

## License

MIT
