Metadata-Version: 2.4
Name: substr8
Version: 0.6.3
Summary: Substr8 Platform CLI - Verifiable AI Infrastructure
Author-email: Substr8 Labs <hello@substr8labs.com>
License-Expression: MIT
Keywords: acc,agents,ai,capability,fdaa,gam,memory,verifiable
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: cryptography>=41.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: fdaa
Requires-Dist: anthropic>=0.18.0; extra == 'fdaa'
Requires-Dist: openai>=1.0.0; extra == 'fdaa'
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'fdaa'
Requires-Dist: opentelemetry-exporter-jaeger>=1.20.0; extra == 'fdaa'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'fdaa'
Provides-Extra: fdaa-server
Requires-Dist: fastapi>=0.100.0; extra == 'fdaa-server'
Requires-Dist: motor>=3.0.0; extra == 'fdaa-server'
Requires-Dist: uvicorn>=0.23.0; extra == 'fdaa-server'
Provides-Extra: full
Requires-Dist: anthropic>=0.18.0; extra == 'full'
Requires-Dist: cryptography>=41.0; extra == 'full'
Requires-Dist: openai>=1.0.0; extra == 'full'
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'full'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'full'
Requires-Dist: sentence-transformers>=2.0; extra == 'full'
Provides-Extra: retrieval
Requires-Dist: sentence-transformers>=2.0; extra == 'retrieval'
Description-Content-Type: text/markdown

# Substr8 CLI

[![PyPI version](https://badge.fury.io/py/substr8.svg)](https://pypi.org/project/substr8/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Verifiable AI Infrastructure** — The command-line interface for the Substr8 platform.

Substr8 provides provable, auditable, and deterministic infrastructure for AI agents. This CLI bundles our core tools:

- **GAM** — Git-Native Agent Memory (cryptographically verifiable memory)
- **FDAA** — File-Driven Agent Architecture (coming soon)
- **ACC** — Agent Capability Control (coming soon)

## Installation

```bash
pip install substr8
```

### Optional Dependencies

```bash
# With cryptographic signing (agent DIDs, GPG integration)
pip install substr8[crypto]

# With semantic search (embeddings-based recall)
pip install substr8[retrieval]

# Everything
pip install substr8[full]
```

## Quick Start

```bash
# Initialize GAM in your workspace
cd your-project
substr8 gam init

# Store a memory
substr8 gam remember "Raza exercises 4-5x per week" --tag health

# Search memories (semantic search)
substr8 gam recall "fitness routine"

# Verify provenance
substr8 gam verify mem_1234567890_abcd

# Show status
substr8 gam status
```

## GAM — Git-Native Agent Memory

GAM uses git's 20-year-old version control primitives to provide:

| Feature | How |
|---------|-----|
| **Cryptographic provenance** | Every memory has a commit SHA |
| **Tamper-evident history** | Merkle tree — change anything, hash breaks |
| **Human-auditable** | Plain Markdown files, `git blame` works |
| **Temporal awareness** | Decay scoring, point-in-time queries |
| **W^X permissions** | Path-based access control with HITL gates |

### Commands

```bash
# Core operations
substr8 gam init              # Initialize repository
substr8 gam remember <text>   # Store a memory
substr8 gam recall <query>    # Search memories
substr8 gam verify <id>       # Verify provenance
substr8 gam forget <id>       # Delete a memory
substr8 gam status            # Show repository status

# Identity management
substr8 gam identity create-agent <name>  # Create agent DID
substr8 gam identity list                 # List identities

# Permissions (W^X)
substr8 gam permissions list    # Show all path policies
substr8 gam permissions check   # Check a specific path
substr8 gam permissions hitl    # Show human-required paths

# Maintenance
substr8 gam import <path>     # Import existing .md files
substr8 gam reindex           # Rebuild indexes
```

### Memory File Format

Memories are stored as Markdown with YAML frontmatter:

```markdown
---
gam_version: 1
id: mem_2026021908001234
created: 2026-02-19T08:00:00Z
source: conversation
confidence: high
tags: [health, fitness]
---

# Raza's Fitness Goals

Raza exercises 4-5x/week and has quit alcohol.
```

### W^X Permissions

| Path | Permission | Signature Required |
|------|------------|-------------------|
| `SOUL.md` | HUMAN_SIGN | Human GPG |
| `AGENTS.md` | HUMAN_SIGN | Human GPG |
| `MEMORY.md` | AGENT_SIGN | Agent DID |
| `memory/daily/*` | OPEN | None |
| `memory/archive/*` | READONLY | N/A |

## Platform Status

```bash
substr8 info
```

```
┌─────────────────────────────────────┐
│         Substr8 Platform v1.0.0     │
├───────────┬──────────┬──────────────┤
│ Component │ Status   │ Description  │
├───────────┼──────────┼──────────────┤
│ GAM       │ ✅ v1.0.0│ Git Memory   │
│ FDAA      │ 🔜       │ File Agents  │
│ ACC       │ 🔜       │ Capabilities │
└───────────┴──────────┴──────────────┘
```

## Research

| Paper | DOI |
|-------|-----|
| GAM: Git-Native Agent Memory | [`10.5281/zenodo.18704573`](https://doi.org/10.5281/zenodo.18704573) |
| ACC: Agent Capability Control | [`10.5281/zenodo.18704577`](https://doi.org/10.5281/zenodo.18704577) |
| FDAA: File-Driven Agent Architecture | [`10.5281/zenodo.18675147`](https://doi.org/10.5281/zenodo.18675147) |

## Links

- **Website:** [substr8labs.com](https://substr8labs.com)
- **Substack:** [substr8labs.substack.com](https://substr8labs.substack.com)
- **GitHub:** [github.com/Substr8-Labs](https://github.com/Substr8-Labs)
- **Twitter:** [@substr8labs](https://twitter.com/substr8labs)

## License

MIT — [Substr8 Labs](https://substr8labs.com)

---

*AI systems should be provable, not just probable.*
