Metadata-Version: 2.4
Name: stickforstats
Version: 0.2.1
Summary: Python SDK and CLI (sfs) for StickForStats — statistical analysis with automatic assumption validation (Guardian) and manuscript statistical verification
Project-URL: Homepage, https://github.com/visvikbharti/stickforstats_new
Project-URL: Documentation, https://github.com/visvikbharti/stickforstats_new/blob/main/docs/CLI_QUICKSTART.md
Project-URL: Repository, https://github.com/visvikbharti/stickforstats_new
Project-URL: Issues, https://github.com/visvikbharti/stickforstats_new/issues
Author: StickForStats Team
License-Expression: MIT
Keywords: analysis,guardian,hypothesis-testing,research,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Requires-Dist: rich>=13.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# StickForStats Python SDK

Python client for the **StickForStats** statistical analysis platform -- featuring
the Guardian Statistical Protection System, Autonomous Intelligence Layer, and
Manuscript Review Engine.

## Installation

```bash
pip install stickforstats
```

With CLI support (adds `sfs` command):

```bash
pip install stickforstats[cli]
```

## Quick Start

```python
from stickforstats import StickForStats

client = StickForStats(
    base_url="http://localhost:8000/api/v1",
    api_key="your-api-key",
)

# Run a t-test with Guardian protection
result = client.stats.ttest(
    data={"control": [23, 25, 28, 22, 27], "treatment": [30, 33, 29, 35, 31]},
    alpha=0.05,
)
print(f"t = {result.t_statistic}, p = {result.p_value}")
if result.guardian and not result.guardian.passed:
    print("Guardian violations:", result.guardian.violations)
```

Use as a context manager to ensure connections are cleaned up:

```python
with StickForStats(api_key="tok_abc123") as sfs:
    desc = sfs.stats.descriptive(data=[10, 20, 30, 40, 50])
    print(f"Mean: {desc.mean}, SD: {desc.std_dev}")
```

## Statistical Tests

### t-Test

```python
result = client.stats.ttest(
    data={"before": [5.1, 4.9, 5.3], "after": [6.2, 5.8, 6.5]},
    paired=True,
    alpha=0.05,
)
```

### ANOVA

```python
result = client.stats.anova(
    data={
        "group_a": [4.1, 3.9, 4.5, 4.2],
        "group_b": [5.2, 5.5, 5.1, 5.3],
        "group_c": [6.0, 6.3, 5.8, 6.1],
    },
    post_hoc="tukey",
)
```

### Correlation

```python
result = client.stats.correlation(
    x=[1, 2, 3, 4, 5],
    y=[2, 4, 5, 4, 5],
    method="pearson",
)
print(f"r = {result.correlation}, p = {result.p_value}")
```

### Regression

```python
result = client.stats.regression(
    data={"x1": [1, 2, 3], "x2": [4, 5, 6], "y": [7, 8, 9]},
    dependent="y",
    predictors=["x1", "x2"],
    regression_type="linear",
)
print(f"R-squared = {result.r_squared}")
```

### Descriptive Statistics

```python
result = client.stats.descriptive(data=[12, 15, 18, 22, 25, 30])
print(f"Mean: {result.mean}, Median: {result.median}, SD: {result.std_dev}")
```

## Power Analysis

```python
# Determine required sample size
result = client.power.ttest(effect_size=0.5, alpha=0.05, power=0.80)
print(f"Required n = {result.sample_size}")

# Comprehensive power report
report = client.power.report(
    data={"group1": [1, 2, 3], "group2": [4, 5, 6]},
    tests=["ttest", "anova"],
)
```

## Nonparametric Tests

```python
# Mann-Whitney U
result = client.nonparametric.mann_whitney(
    group1=[3.1, 2.5, 4.0, 3.8],
    group2=[5.2, 4.9, 6.1, 5.5],
)

# Kruskal-Wallis
result = client.nonparametric.kruskal_wallis(
    data={"a": [1, 2, 3], "b": [4, 5, 6], "c": [7, 8, 9]},
)
```

## Categorical Tests

```python
# Chi-square independence
result = client.categorical.chi_square_independence(
    observed=[[10, 20], [30, 40]],
)

# Fisher's exact test
result = client.categorical.fishers_exact(
    table=[[8, 2], [1, 5]],
)
```

## Autonomous Intelligence

```python
# Smart profiling
profile = client.autonomous.profile(
    data={"age": [25, 30, 35], "score": [80, 85, 90], "group": [1, 2, 1]},
)
print(profile.recommendations)

# Natural-language query
answer = client.autonomous.query(
    question="Is there a significant difference between groups?",
    data={"group1": [1, 2, 3], "group2": [4, 5, 6]},
)
print(answer.narrative)

# Guardian cascade (auto-fallback to nonparametric if assumptions violated)
cascade = client.autonomous.cascade(
    data={"control": [1, 1, 2], "treatment": [10, 50, 100]},
    test="ttest",
)
if cascade.fallback_used:
    print(f"Guardian redirected to: {cascade.executed_test}")
```

## Manuscript Review

```python
# Full manuscript analysis
report = client.manuscript.analyze(
    "paper.pdf",
    field="psychology",
    alpha=0.05,
)
print(f"Score: {report.overall_score}")
for claim in report.claims:
    status = "PASS" if claim.verified else "FAIL"
    print(f"  [{status}] {claim.text}")

# Check consistency
consistency = client.manuscript.check_consistency("paper.pdf")
if not consistency.consistent:
    for issue in consistency.inconsistencies:
        print(f"  Inconsistency: {issue}")
```

## Platform Usage

```python
# Check your quota
usage = client.platform.usage()
print(f"Tier: {usage.tier}, Remaining: {usage.remaining_quota}")

# List available tiers
tiers = client.platform.tiers()
for tier in tiers:
    print(f"{tier.name}: {tier.monthly_requests} requests/month")
```

## CLI Usage

Configure your connection once:

```bash
sfs config --api-key YOUR_API_KEY --base-url http://localhost:8000/api/v1
```

Run analyses from the terminal:

```bash
# Run a t-test
sfs analyze --file data.csv --test ttest --alpha 0.05

# Descriptive statistics
sfs analyze --file data.csv --test descriptive

# Regression
sfs analyze --file data.csv --test regression --dependent y --predictors "x1,x2"

# Smart profiling
sfs profile --file data.csv

# Natural-language query
sfs query "compare groups" --file data.csv

# Manuscript review
sfs manuscript --file paper.pdf --field psychology

# Check usage
sfs usage
```

## Authentication

The SDK supports two authentication methods:

**User token** (default):

```python
client = StickForStats(api_key="tok_abc123")
# Sends: Authorization: Token tok_abc123
```

**Platform key** (for server-to-server integration):

```python
client = StickForStats(api_key="pk_live_xyz", platform_key=True)
# Sends: X-API-Key: pk_live_xyz
```

## Error Handling

```python
from stickforstats import StickForStats, AuthenticationError, ValidationError, APIError

client = StickForStats(api_key="bad-key")

try:
    result = client.stats.ttest(data={"a": [1], "b": [2]})
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Bad input: {e.field_errors}")
except APIError as e:
    print(f"Server error [{e.status_code}]: {e.message}")
```

## Requirements

- Python 3.8+
- httpx >= 0.24
- pydantic >= 2.0
- click >= 8.0 and rich >= 13.0 (optional, for CLI)

## License

MIT
