Metadata-Version: 2.4
Name: deepstrain
Version: 1.0.1
Summary: Terminal-native AI engineering agent - 59 tools, 19 capability domains, DAG orchestration, DeepSeek powered
Author-email: DeepStrain Developers <dev@deepstrain.org>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: zeroconf>=0.38
Dynamic: license-file

# deepstrain

**Terminal-native AI engineering assistant. 57 tools, 19 capability domains, topology-aware DAG orchestration, IMAP email, DeepSeek powered.**

Bring your own key. Your code never leaves your machine. Works offline after first activation.

```bash
pip install deepstrain
deepstrain          # first run: guided setup → straight into chat
```

That's it. deepstrain detects the first run, walks you through getting a free DeepSeek API key, validates it, does a live handshake with the model, then drops you into the agent.

---

## Table of Contents

- [What Is deepstrain](#what-is-deepstrain)
- [Installation](#installation)
- [First Run Experience](#first-run-experience)
- [Configuration](#configuration)
- [Settings GUI](#settings-gui)
- [License Activation](#license-activation)
- [CLI Reference](#cli-reference)
- [Agent Tools — All 57](#agent-tools--all-57)
- [Topology-Aware Orchestration](#topology-aware-orchestration)
- [Session Features](#session-features)
- [Automation & Scripting](#automation--scripting)
- [Architecture](#architecture)

---

## What Is deepstrain

deepstrain is a pip-installable AI agent that runs entirely in your terminal. It connects directly to the DeepSeek API using your own key — no proxy, no data collection, no hidden cloud. The model has access to 57 built-in tools: it can read and write files, analyse entire projects, run git commands, execute tests, spawn parallel sub-agents, read your email via IMAP, execute multi-step DAG pipelines across 19 capability domains — all with your explicit permission.

| Property | Value |
|----------|-------|
| Runtime | Local-only — your data never leaves your machine |
| Model | DeepSeek Chat / R1 via your own API key |
| Install | `pip install deepstrain` |
| Tools | 57 built-in + 19 capability domains |
| Orchestration | Topology-aware DAG engine with event-sourced state |
| Languages | English (default) · Türkçe |
| Price | $9/mo monthly · $6/mo annual |

---

## Installation

### Windows

```powershell
pip install deepstrain --user
deepstrain        # guided first-run setup
```

### Linux / macOS

```bash
pip install deepstrain --user
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
deepstrain        # guided first-run setup
```

### From Source (dev)

```bash
git clone https://github.com/mete-dotcom/deepstrain.git
cd deepstrain
pip install -e .
```

---

## First Run Experience

When you run `deepstrain` for the first time (no config file found), it shows a welcoming setup guide:

```
  ┌──────────────────────────────────────────────────────────────┐
  │    d e e p  S T R A I N   — just installed ✓               │
  │    terminal-native AI engineering assistant                  │
  │    57 tools  ·  19 capability domains  ·  DeepSeek powered  ·  your data stays local  │
  └──────────────────────────────────────────────────────────────┘

  To get started you need a FREE DeepSeek API key:
    1.  Go to  →  platform.deepseek.com/api_keys
    2.  Sign up (free) and create a key
    3.  Paste it below — it stays on your machine only

  Your API key: ••••••••••••••••••••••••••••••••••••
  ✓  Connected  ·  $5.00 USD

  deepstrain: Ready! I'm your terminal-native AI engineering
  assistant...
```

The key is validated against the DeepSeek API immediately. After a successful key, the model sends its own greeting, and the chat session opens automatically.

---

## Configuration

Config is stored at `~/.deepstrain/config.toml`.

```toml
# ~/.deepstrain/config.toml
[default]
api_key      = "sk-..."          # your DeepSeek API key
model        = "deepstrain"      # deepstrain · deepstrain-r1 · deepseek-chat · deepseek-reasoner
theme        = "green"           # green · blue · purple · amber · arctic · matrix · mono
sounds       = "true"            # true · false
sound_volume = "soft"            # soft · standart · yüksek
language     = "en"              # en · tr
budget_limit = "0"               # monthly USD cap (0 = unlimited)
```

**Environment variable override:**

```bash
export DEEPSEEK_API_KEY="sk-..."   # takes precedence over config file
```

**Model aliases:**

| Alias | Maps to |
|-------|---------|
| `deepstrain` | `deepseek-chat` (default) |
| `deepstrain-r1` | `deepseek-reasoner` (step-by-step reasoning) |

---

## Settings GUI

```bash
deepstrain settings
```

Opens a graphical panel (tkinter) where you can configure everything visually: API key, model, terminal theme (7 colour swatches with live preview), sounds, language, monthly budget, and license status.

---

## License Activation

```bash
deepstrain activate DSTR-XXXXX-XXXXX-XXXXX-XXXXX
deepstrain status       # show tier, expiry, grace period
deepstrain deactivate   # remove license (for machine transfer)
```

**Get a key:** [deepstrain.vercel.app](https://deepstrain.vercel.app)

**Grace period:** Expired licenses have a 7-day grace period before lockout.

---

## CLI Reference

```bash
deepstrain                    # smart entry: first-run setup or direct chat
deepstrain <command> [args]
```

| Command | Description |
|---------|-------------|
| `chat` | Start interactive AI agent session |
| `resume` | Pick a recent session and continue it |
| `logs` | List recent session logs (newest first) |
| `eval 'task'` | One-shot AI task — run agent on a prompt and exit |
| `exec <tool>` | Run a single tool directly and print result |
| `serve` | Start HTTP API server (POST /exec, POST /eval) |
| `configure` | Set API key and model interactively |
| `settings` | Graphical settings panel (tkinter) |
| `why` | Why DeepSeek + why deepstrain? Terminal handshake |
| `hello` | Onboarding wizard |
| `init` | Create default `~/.deepstrain/config.toml` |
| `activate KEY` | Activate with a license key |
| `deactivate` | Remove local license token |
| `status` | Show license status (tier, expiry, grace) |
| `doctor` | Full health check (config, license, git, workers) |
| `version` | Show version |

### eval flags

```bash
deepstrain eval "task" --loop --max-iter 5 --max-turns 20 --json
```

---

## Agent Tools — All 57

Once inside `deepstrain chat`, the AI picks the right tool for each step automatically. The `capability` tool unlocks 18 specialised domains — use it when no dedicated tool fits. The `execute_multi` tool chains multiple capabilities into a DAG with automatic dependency resolution and parallel execution.

### File Reading

| Tool | What it does |
|------|-------------|
| `read_file` | Read a file, optional line range |
| `chunk_read` | Read large files in 80-line chunks |
| `file_outline` | Fast structure view: class/def/import lines |
| `surgical_read` | Extract ONLY the target function/class — 95% token savings |

### File Writing & Editing

| Tool | What it does |
|------|-------------|
| `write_file` | Write (overwrite) a file |
| `patch_file` | Surgical text replacement — auto syntax-check + rollback for `.py` |
| `smart_patch` | `patch_file` with fuzzy fallback (difflib ≥72%) |
| `surgical_patch` | AST-based symbol replacement — finds by name, auto-adjusts indentation, validates syntax |

### Navigation & Search

| Tool | What it does |
|------|-------------|
| `list_dir` | List files and folders |
| `find_files` | Find by glob pattern |
| `search_in_files` | Regex search across Python files |
| `grep_files` | Regex search across any file type |
| `find_definition` | Find where a function/class is defined |
| `find_usages` | Find all call sites |
| `verify_symbol` | Quick existence check |

### Code Analysis

| Tool | What it does |
|------|-------------|
| `find_symbols` | List all `def`/`class` in a file (AST, zero-token) |
| `detect_duplicates` | Find copy-paste code blocks |
| `read_patterns` | Extract code conventions |
| `interface_check` | Find missing methods between abstract class and implementation |
| `dead_code` | Find defined-but-never-used functions and classes |
| `circular_deps` | Detect circular import cycles |
| `import_graph` | Show what a file imports, or who imports it |
| `detect_stack` | Auto-detect tech stack |
| `schema_check` | Compare migration SQL vs schema |

### Composite Analysis

| Tool | What it does |
|------|-------------|
| `project_context` | ~1500-token project snapshot |
| `project_summary` | Directory tree with file/line counts |
| `strain_project` | Single-pass composite: stack + map + style + circular deps + dead code |

### Execution & Git

| Tool | What it does |
|------|-------------|
| `run_command` | Run a shell command (timeout, dangerous pattern blocking, permission required) |
| `run_tests` | Run pytest |
| `git_diff` | Show unstaged or staged changes |
| `git_log` | Show recent commits |
| `git_commit` | Stage all + commit with message |

### Memory

| Tool | What it does |
|------|-------------|
| `remember` / `recall` | Session RAM key-value store |
| `save_note` / `read_notes` | Persistent global notes |
| `save_project_note` / `read_project_notes` | Per-project notes |
| `audit_md_notes` | Scan and analyse markdown notes |

### Planning & Control

| Tool | What it does |
|------|-------------|
| `make_plan` | Display a numbered plan before multi-step edits |
| `checkpoint` | Log a progress milestone |
| `ask_user` | Pause and ask a clarifying question |
| `grant_permission` / `list_permissions` | Session permission management |

### Plugins & Workers

| Tool | What it does |
|------|-------------|
| `plugin_tool` | Run a custom plugin from `agent_tools/` |
| `worker` | Run a worker function from `agent_workers.py` |

### Sub-Agents

| Tool | What it does |
|------|-------------|
| `list_agent_types` | List available specialist roles |
| `delegate` | Delegate a task to a read-only specialist sub-agent |
| `spawn_agents` | Run multiple tasks in parallel sub-agents |
| `link_project` | Register an external project by alias |
| `cross_project` | Send a read-only task to a linked project |

**Built-in roles:** `analyst`, `security`, `performance`, `test`, `docs`, `refactor`

### Capability Domains (single tool — 18 domains)

| Tool | What it does |
|------|-------------|
| `capability` | Run an operation in any of 18 specialised domains |

**18 domains:** browser, cloud, config, database, document, execution, filesystem, git, governance, infra, math, media, network, nlp, notification, package, security, verification

### DAG Orchestration

| Tool | What it does |
|------|-------------|
| `execute_multi` | Execute multiple capability operations as a DAG. Automatic dependency resolution, parallel execution, trust-based rerouting on failure, timeout enforcement, retry with backoff |

---

## Topology-Aware Orchestration

deepstrain includes a built-in topology-aware DAG orchestration engine that sits between the agent and the capability domains as the central runtime authority.

### How it works

```
                      ┌──────────────────────────┐
                      │     FermionKernel         │
                      │   (central runtime auth)  │
                      │                           │
  Agent ──tasks──▶   │  DagEngine                 │
                      │  ├─ build_graph()          │
                      │  ├─ resolve_order()        │
                      │  ├─ execute_level()  ◀─ async TaskGroup
                      │  ├─ handle_failure()  ◀─ trust-based reroute
                      │  └─ compensate()           │
                      │                           │
                      │  PolicyEngine · Guard     │
                      │  RuntimeState · TrustStore │
                      └──────────────────────────┘
                               │
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
              Capability  Capability  Capability
              Node (DAG)  Node (DAG)  Node (DAG)
```

### Key design decisions

| Principle | Detail |
|-----------|--------|
| **Immutable nodes** | `CapabilityNode` is fully frozen — all state lives in the event-sourced `RuntimeState` |
| **Deterministic order** | Execution order is determined solely by dependency topology + runtime state, **not** by trust scores |
| **Trust → rerouting** | Trust scores influence rerouting, fallback, and risk evaluation — never scheduling order |
| **Event sourcing** | All state changes are append-only `NodeEvent`s. Same events → same state, every time |
| **Async by default** | Parallel levels execute via `asyncio.TaskGroup`. Horizontal scalability from the start |
| **Timeout** | Every node has a configurable timeout enforced by `asyncio.wait_for` |
| **Retry with backoff** | Exponential backoff on transient failures. Circuit breaker prevents cascading |

### Execution flow

1. **Build graph** — `execute_multi` receives tasks with dependency declarations
2. **Topological sort** — Kahn's algorithm produces parallel-safe execution levels
3. **Level-by-level execution** — each level runs concurrently via `TaskGroup`
4. **Failure handling** — failed nodes trigger trust-based rerouting to alternate domains
5. **Event recording** — every state transition is recorded as an immutable event

### Example: CI pipeline as DAG

```python
# Inside chat, tell deepstrain:
"run security scan, then run tests in parallel with linting,
then deploy if both pass"
```

The agent calls `execute_multi` with:

```json
{
  "tasks": [
    {"node_id": "scan",  "domain": "security",     "operation": "sast_scan"},
    {"node_id": "lint",  "domain": "verification", "operation": "ruff_check", "deps": ["scan"]},
    {"node_id": "test",  "domain": "verification", "operation": "pytest",     "deps": ["scan"]},
    {"node_id": "deploy","domain": "cloud",        "operation": "vercel_deploy", "deps": ["lint", "test"]}
  ]
}
```

This executes as:
- Level 0: `scan` (alone)
- Level 1: `lint` + `test` (parallel — both depend on `scan`)
- Level 2: `deploy` (depends on both `lint` and `test`)

If `scan` fails, `lint` and `test` are blocked. The rerouter checks trust scores and may fall back to an alternate security tool.

---

## Session Features

### Permission system

Every write/execute operation triggers a permission prompt:

```
  [permission]  deepstrain → dosya yaz: src/auth.py
  [y] yes   [n] no   [always] always allow   [never] never allow  → 
```

### Session logging

```bash
deepstrain logs      # list recent sessions
deepstrain resume    # interactive picker → continue where you left off
```

### Project notes

deepstrain writes `DEEPSTRAIN_NOTES.md` inside your project. Next session: notes are auto-injected into context.

### Budget tracking

Set a monthly USD cap. At 80%: warning. At 100%: asks whether to continue.

### Themes

7 colour themes: `green` (default), `blue`, `purple`, `amber`, `arctic`, `matrix`, `mono`.

### Sounds

Permission requests and completed tasks play brief notification tones.

---

## Automation & Scripting

### One-shot task

```bash
deepstrain eval "audit src/ for security issues"
```

### CI repair loop

```bash
deepstrain eval "run tests and fix any failures" --loop --max-iter 5
```

### Pre-commit hook

```bash
# .git/hooks/pre-commit
STAGED=$(git diff --cached --name-only --diff-filter=AM | grep "\.py$")
if [ -n "$STAGED" ]; then
  deepstrain eval "security audit: $STAGED"
fi
```

### HTTP API server

```bash
deepstrain serve --port 8765

# Single tool
curl -X POST http://localhost:8765/exec \
  -H "Content-Type: application/json" \
  -d '{"tool": "read_file", "args": {"path": "src/main.py"}}'

# Agent eval
curl -X POST http://localhost:8765/eval \
  -H "Content-Type: application/json" \
  -d '{"prompt": "find all TODO comments", "max_turns": 8}'
```

### Shortcut prefixes

```
review auth.py, debug TypeError, plan add JWT, docs UserService,
test _parse_token, refactor database.py, security api/routes.py
```

---

## Architecture

```
deepstrain/
├── __init__.py              exports chat_loop, __version__
├── chat.py                  agent loop, 57 tools, 19 capability domains,
│                            permission system, session logging, budget tracking
├── cli.py                   argparse entry points, first-run flow, settings GUI
├── i18n.py                  EN/TR string table
├── config.py                load_config()
├── license.py               license mask/activate helpers
├── verify.py                offline license verification
│
├── orchestration/           ★ NEW: topology-aware DAG orchestration
│   ├── __init__.py          module root, get_kernel() singleton
│   ├── kernel.py            FermionKernel (central runtime authority)
│   ├── engine.py            DagEngine (async, TaskGroup-based execution)
│   ├── graph.py             CapabilityNode, GraphTopology (topo sort,
│   │                        cycle detection, critical path)
│   ├── state.py             RuntimeState (event-sourced, SQLite persistence)
│   ├── events.py            NodeEvent, EventStream (transition validation)
│   └── trust.py             TrustWeight, WeightedRerouter
│
├── capability/              18 domain implementations
│   ├── notification.py      email, Slack, Discord, webhook, push, SMS
│   ├── nlp.py               summarization, sentiment, entities, classification
│   ├── math.py              sympy evaluate/simplify/solve/diff/integrate
│   ├── media.py             Pillow resize/convert, ffmpeg transcode, OCR
│   ├── document.py          Markdown→HTML/PDF, DOCX, spreadsheet
│   ├── network.py           HTTP, ping, DNS, TCP, traceroute
│   ├── config.py            TOML/YAML/JSON/INI read/write/validate
│   ├── database.py          SQLite queries, migrations, backup/restore
│   ├── security.py          SAST, secret scan, dep audit, SBOM
│   ├── verification.py      pytest, mypy, ruff, coverage, bandit
│   ├── cloud.py             AWS, GCP, Azure, Cloudflare, Vercel, Netlify
│   ├── browser.py           Playwright/Selenium automation
│   ├── execution.py         Shell command execution
│   ├── filesystem.py        File operations
│   ├── git.py               Git operations
│   ├── infra.py             Docker/K8s operations
│   ├── package.py           pip/npm package management
│   └── governance/          Policy enforcement, audit trail
│
├── runtime/                 → backward-compat re-export to orchestration
│
└── tests/
    ├── test_orchestration.py    57 tests (events, graph, state, trust,
    │                             engine, kernel, replay)
    ├── test_runtime_kernel.py   11 backward-compat tests
    ├── test_capability_*.py     domain-specific capability tests
    └── ...

~/.deepstrain/
├── config.toml              user settings
├── notes.md                 persistent global notes
├── budget.json              monthly token spend tracker
└── logs/
    └── YYYYMMDD_HHMMSS.json  one file per session (auto-saved)
```

### How tools work

The agent calls DeepSeek's function-calling API. deepstrain registers 57 tool schemas. DeepSeek picks the right tool(s) for each step. deepstrain executes them locally and returns results. The loop continues until DeepSeek returns a final text answer.

### Crash resilience

deepstrain is designed to never show a raw Python traceback:
- `_agent_turn()` catches every network error and returns a friendly message
- `chat_loop()` catches unexpected exceptions per turn, logs them, and keeps the session alive
- `main()` wraps the entire process in a top-level handler

---

## Building from Source

```bash
git clone https://github.com/mete-dotcom/deepstrain.git
cd deepstrain
pip install build
python -m build
pip install dist/deepstrain-*.whl
```

---

## License

Commercial — requires activation. See [deepstrain.vercel.app](https://deepstrain.vercel.app) for pricing.

Free mode (no activation): basic chat without tools.

---

*deepstrain v0.7.0*
