# quark-agent

**Git for AI agents.** Cognitive fingerprinting CLI for [Quark-AI](https://quark-ai.cordee.ovh).

```bash
pip install quark-agent
```

## Quickstart

```bash
quark init                                       # initialize repo
quark login                                      # authenticate

quark snapshot --agent gpt-4o \
  --prompt "You are a customer support agent"    # capture a fossil

quark list                                       # list fossils

quark diff abc12345 def67890                     # compare two versions

quark restore abc12345 --to behavior_v1.md       # export behavior card
```

## How it works

Each `quark snapshot` runs your agent description through **7 calibrated cognitive probes** and captures the behavioral fingerprint — its reasoning patterns, invariants, and stability score — as an immutable fossil.

```
quark snapshot --agent my_agent --prompt "…"
  │
  ├─ 7 probes: direct · rephrased · abstract · concrete
  │            adversarial · minimal · contextual
  │
  ├─ Embedding matrix (7 × 256) → cosine similarity
  │
  ├─ stability_score σ   (0 → 1, higher = more consistent)
  ├─ behavioral_invariants  (persistent patterns)
  ├─ cognitive_signature    (fingerprint string)
  └─ sensitive_zones        (instability hotspots)
```

## Commands

| Command | Description |
|---|---|
| `quark init` | Initialize `.quark/config.toml` in current directory |
| `quark login` | Authenticate (saves token to config) |
| `quark snapshot` | Capture a cognitive fossil |
| `quark list` | List fossils |
| `quark diff A B` | Compare two fossils — drift, stability delta, invariant changes |
| `quark restore ID` | Export behavior card (markdown / prompt / json) |

## CI integration

```yaml
# .github/workflows/quark.yml
- name: Snapshot agent
  env:
    QUARK_TOKEN: ${{ secrets.QUARK_TOKEN }}
    QUARK_API_URL: https://quark-ai.cordee.ovh
  run: |
    pip install quark-agent
    quark snapshot \
      --agent "${{ github.repository }}" \
      --prompt-file system_prompt.txt \
      --tag "${{ github.ref_name }}" \
      --json > fossil.json
```

## Options

All options can be set via env vars:

| Env var | Description |
|---|---|
| `QUARK_TOKEN` | JWT auth token (overrides config file) |
| `QUARK_API_URL` | API base URL (default: `https://quark-ai.cordee.ovh`) |

---

Built on [Quark-AI](https://quark-ai.cordee.ovh) — infrastructure de fossiles cognitifs.
