Metadata-Version: 2.4
Name: synapse-code
Version: 0.2.0
Summary: Terminal AI coding agent
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: textual>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: keyring>=25.0
Requires-Dist: rich>=13.0
Requires-Dist: pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# Synapse AI

**Synapse AI** is a terminal-based AI coding assistant designed for pair programming, codebase exploration, and automated code editing inside your workspace.

Built with Python 3.11+, Textual, Rich, and HTTPX.

---

## Features

- **Terminal TUI**: Beautiful, responsive terminal user interface powered by [Textual](https://textual.textualize.io/).
- **Multi-Provider Support**:
  - Native Anthropic Messages API (`claude-3-7-sonnet`, `claude-3-5-sonnet`, etc.)
  - OpenAI-compatible endpoints: OpenAI, Google Gemini, DeepSeek, Groq, Mistral AI, Together AI, Fireworks, Cerebras, SambaNova, Cohere, Perplexity, OpenRouter, Experiential Labs.
- **Protected File Editing**:
  - Unified diffs previewed before any changes are written.
  - Granular permission control: Allow once, Allow for Session, or Deny.
  - Safe path resolution preventing directory traversal outside the workspace.
- **Granular Security Modes**:
  - `default`: Ask confirmation for file edits and shell commands.
  - `acceptEdits`: Automatically apply file edits; confirm commands.
  - `plan`: Read-only mode; prevents any file or command execution.
  - `bypass`: Autonomous mode without interactive confirmation prompts.
- **Transparent Execution**: Live tool call logs (`↳ read_file(...)`, `✓ completed`) in the activity feed.
- **Token Streaming**: Real-time token streaming from LLM providers (OpenAI-compatible and Anthropic Messages API) directly in the terminal interface.
- **Session Persistence**: Automatic saving of conversations, with `/sessions`, `/resume`, and `/export` commands.
- **Token & Cost Tracking**: Built-in `/usage` and `/context` reporting.

---

## Installation

### From Source (Development)

```bash
git clone https://github.com/yourusername/synapse-ai.git
cd synapse-ai

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies in editable mode
pip install -e ".[dev]"
```

---

## Quick Start

Launch Synapse in your current workspace:

```bash
synapse
```

Or open a specific workspace:

```bash
synapse -w /path/to/project
```

Check version or help:

```bash
synapse --version
synapse --help
```

---

## Configuring API Keys

You can configure API keys in two ways:

### 1. Via Environment Variables (Recommended)

Synapse automatically detects standard environment variables:

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."
export DEEPSEEK_API_KEY="sk-..."
export GROQ_API_KEY="gsk_..."
```

### 2. In the TUI Interface

Type `/keys` inside the Synapse prompt, pick your provider from the list, enter your API key, and press Enter. Keys are securely stored in your OS keyring (with local fallback).

---

## Commands

| Command | Description |
|---|---|
| `/init` | Initialize workspace metadata (`.synapse/workspace.json`) and trust |
| `/keys` | Configure provider API keys |
| `/model` | Select active model for the configured provider |
| `/mode [name]` | View or change permission mode (`default`, `acceptEdits`, `plan`, `bypass`) |
| `/clear` | Clear chat history and reset agent context |
| `/sessions` | List all saved conversation sessions in this workspace |
| `/resume <id>` | Restore a previous conversation session by ID |
| `/export [file]` | Export current conversation to a Markdown file |
| `/status` | Display workspace, provider, model, and permission status |
| `/usage` | Display token counts and estimated costs |
| `/context` | Display context window utilization |
| `/list [path]` | List files inside workspace |
| `/read <path>` | Read contents of a file |
| `/search <text>` | Search text across workspace files |
| `/write <path> :: <content>` | Create or overwrite a file |
| `/edit <path> :: <old> => <new>` | Replace exact text in a file |
| `/help` | Show command reference |

---

## Permission Modes

Switch modes at any time with `/mode <name>`:

```text
/mode plan         # Read-only exploration and architecture planning
/mode acceptEdits  # Fast coding without edit confirmations
/mode default      # Safe mode: confirm edits and commands
/mode bypass       # Full autonomous operation
```

---

## Running Tests

Run the test suite with `pytest`:

```bash
pytest tests -v
```

---

## Architecture

```
synapse/
├── agent/          # Agent loop, system prompt, context compaction
├── app/            # CLI entry point (argparse)
├── core/           # Data models (Message, Role, ToolCall, ChatResponse)
├── providers/      # LLM adapters (OpenAICompatible, Anthropic, Registry)
├── security/       # Permissions, Keyring/Env secrets, Config
├── session/        # Session manager & serialization
├── tools/          # Filesystem, Git, and Shell tools
├── ui/             # Textual TUI interface & Modal screens
└── usage.py        # Token counting, pricing, and context limits
```

---

## License

MIT
