Metadata-Version: 2.4
Name: toothfairy-cli
Version: 1.1.0
Summary: Command-line interface for ToothFairyAI API
Home-page: https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli
Author: ToothFairyAI
Author-email: ToothFairyAI <support@toothfairyai.com>
License: MIT
Project-URL: Homepage, https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli
Project-URL: Repository, https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli
Project-URL: Documentation, https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli#readme
Project-URL: Issues, https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli/issues
Project-URL: Releases, https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli/releases
Keywords: toothfairy,ai,cli,api,chatbot,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: click>=8.0.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: rich>=12.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: httpx-sse>=0.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: build>=0.8.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: bump2version>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# ToothFairyAI CLI Tools

**Command-line interfaces for interacting with ToothFairyAI agents.** Available in both Python and Node.js versions with identical functionality.

**Quick access**: Use either `tf` or `toothfairy` commands!

## 📦 Installation

### Python CLI (PyPI)
```bash
pip install toothfairy-cli
```

### Node.js CLI (npm)
```bash
npm install -g @toothfairyai/cli
```

Both packages provide the same commands: `toothfairy` and `tf`

## 🚀 Getting Started

### 1. Configure your credentials
```bash
tf configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE
```

### 2. Send a message to an agent
```bash
tf send "Hello, I need help" --agent-id YOUR_AGENT_ID
```

### 3. Search the knowledge hub
```bash
tf search "AI configuration help"
```

### 4. Explore your workspace
```bash
tf chats                    # List all conversations
tf config-show              # View current settings
```

## ✨ Features

- **💬 Agent Communication**: Send messages to ToothFairyAI agents
- **🔍 Knowledge Hub Search**: Search documents with advanced filtering
- **📋 Chat Management**: List and view chat conversations  
- **⚙️ Configuration**: Flexible credential and settings management
- **🎨 Rich Output**: Beautiful terminal interface with colors and tables
- **📊 Multiple Formats**: JSON and text output for both interactive and scripted use
- **🔐 Secure**: Safe credential storage and validation
- **📱 Cross-Platform**: Works on Windows, macOS, and Linux

## 💬 Agent Communication Examples

| Use Case | Command |
|----------|---------|
| Simple message | `tf send "What are your hours?" --agent-id "info-agent"` |
| With customer info | `tf send "Schedule appointment" --agent-id "scheduler" --customer-info '{"name": "John"}'` |
| Verbose output | `tf send "Hello" --agent-id "agent-123" --verbose` |
| JSON for scripting | `tf send "Help" --agent-id "agent-123" --output json` |

### Advanced Agent Communication
```bash
# Send message with detailed customer information
tf send "Check my insurance coverage" \
  --agent-id "insurance-agent" \
  --customer-info '{
    "name": "Sarah Johnson",
    "dateOfBirth": "1985-03-15",
    "insurance": {
      "provider": "BlueCross BlueShield",
      "policyNumber": "BC123456789"
    }
  }'
```

## 🔍 Knowledge Hub Search Examples

| Use Case | Command |
|----------|---------|
| Basic search | `tf search "AI agent configuration"` |
| Filter by status | `tf search "machine learning" --status published` |
| Limit results | `tf search "troubleshooting" --top-k 3` |
| Topic filtering | `tf search "automation" --topics "topic_123,topic_456"` |
| Specific document | `tf search "settings" --document-id "doc_550..."` |
| Verbose details | `tf search "deployment" --verbose` |
| JSON output | `tf search "API docs" --output json` |

### Search Filtering Guide

Knowledge Hub search supports powerful filtering options:

- **`--status`**: Filter documents by 'published' or 'suspended' status
- **`--topics`**: Use topic IDs from ToothFairyAI (comma-separated)
- **`--document-id`**: Search within a specific document
- **`--top-k`**: Control number of results (1-50)
- **`--verbose`**: Show relevance scores and metadata

## 📋 Workspace Management Examples

| Use Case | Command |
|----------|---------|
| List all chats | `tf chats` |
| View chat details | `tf chat CHAT_ID` |
| Show config | `tf config-show` |
| Detailed help | `tf help-guide` |

## ⚙️ Configuration

Both CLIs support multiple configuration methods (in order of priority):

### Configuration Methods

| Method | Description | Example |
|--------|-------------|---------|
| Environment | Set environment variables | `export TF_API_KEY=your_key` |
| Config file | Use ~/.toothfairy/config.yml | `api_key: your_key`<br/>`workspace_id: your_workspace` |
| CLI arguments | Pass config file path | `tf --config /path/to/config.yml send ...` |

### Setting up configuration

#### Interactive Configuration
```bash
tf configure \
  --api-key "your-api-key" \
  --workspace-id "your-workspace-id"

# View current configuration
tf config-show
```

#### Environment Variables
```bash
# Required
export TF_API_KEY="your-api-key"
export TF_WORKSPACE_ID="your-workspace-id"

# Optional (defaults to production)
export TF_BASE_URL="https://api.toothfairyai.com"
export TF_AI_URL="https://ai.toothfairyai.com"
```

#### Config File Format
Create `~/.toothfairy/config.yml`:
```yaml
# Required
api_key: "your-api-key"
workspace_id: "your-workspace-id"

# Optional (defaults to production)
base_url: "https://api.toothfairyai.com"
ai_url: "https://ai.toothfairyai.com"
```

## 📊 Output Formats

Both CLIs support `--output` or `-o` flag:

- **`text`** (default): Pretty formatted tables and panels
- **`json`**: Raw JSON output for scripting

```bash
# Get JSON output for scripting
tf send "Hello" --agent-id "agent-123" --output json | jq '.agentResponse.contents.content'

# Search with JSON output
tf search "documentation" --output json | jq '.[].title'
```

## 🔧 Command Reference

### Global Options
- `--config`, `-c`: Path to configuration file
- `--verbose`, `-v`: Enable verbose logging and API debugging

### Commands

#### `configure`
Set up CLI credentials and configuration.

**Options:**
- `--api-key`: API key (required)
- `--workspace-id`: Workspace ID (required)
- `--base-url`: ToothFairy API base URL (optional)
- `--ai-url`: ToothFairyAI URL (optional)
- `--config-path`: Custom path to save config file

#### `send <message>`
Send a message to a ToothFairyAI agent.

**Arguments:**
- `message`: The message text to send

**Options:**
- `--agent-id`: Agent ID to send message to (required)
- `--phone-number`: Phone number for SMS channel (optional)
- `--customer-id`: Customer ID (optional)
- `--provider-id`: SMS provider ID (optional)
- `--customer-info`: Customer info as JSON string (optional)
- `--output`, `-o`: Output format (json|text)
- `--verbose`, `-v`: Show detailed response information

#### `search <query>`
Search for documents in the knowledge hub.

**Arguments:**
- `query`: The search query text

**Options:**
- `--top-k`, `-k`: Number of documents to retrieve (1-50, default: 10)
- `--status`: Filter by document status (published|suspended)
- `--document-id`: Search within specific document ID
- `--topics`: Comma-separated topic IDs to filter by
- `--output`, `-o`: Output format (json|text)
- `--verbose`, `-v`: Show detailed search information

#### `chats`
List all chats in the workspace.

**Options:**
- `--output`, `-o`: Output format (json|text)

#### `chat <chat-id>`
Get details of a specific chat.

**Arguments:**
- `chat-id`: The chat ID to retrieve

**Options:**
- `--output`, `-o`: Output format (json|text)

#### `config-show`
Display current configuration (with masked API key).

#### `help-guide`
Show detailed help with examples, common issues, and pro tips.

## 💡 Usage Examples

### Basic Workflow
```bash
# Configure once
tf configure --api-key "tf-key-abc123" --workspace-id "workspace-456"

# Send messages to agents
tf send "I'd like to schedule a session" --agent-id "my-scheduler"

# Search for relevant information
tf search "appointment scheduling help"

# Manage conversations
tf chats
tf chat chat-abc123
```

### Scripting Examples
```bash
#!/bin/bash

# Send message and extract agent response
RESPONSE=$(tf send "What are your hours?" \
  --agent-id "info-agent" \
  --output json)

# Extract the agent's text response
AGENT_TEXT=$(echo "$RESPONSE" | jq -r '.agentResponse.contents.content')
echo "Agent said: $AGENT_TEXT"

# Search documents and extract relevant content
SEARCH_RESULTS=$(tf search "office hours" --output json)
TOP_RESULT=$(echo "$SEARCH_RESULTS" | jq -r '.[0].raw_text')
echo "Found documentation: $TOP_RESULT"

# Get chat ID for follow-up
CHAT_ID=$(echo "$RESPONSE" | jq -r '.chatId')
echo "Chat ID: $CHAT_ID"
```

## ⚠️ Common Issues & Solutions

| Issue | Solution |
|-------|----------|
| Configuration incomplete | Run: `tf configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE` |
| No text response found | Use `--verbose` flag to see full response details |
| Agent not responding | Check agent-id is correct and agent is active |
| Network errors | Verify API endpoints are accessible and credentials are valid |

## 🐛 Troubleshooting

### Debug Mode
Use the `--verbose` flag to see detailed API request/response information:

```bash
tf --verbose send "test message" --agent-id "agent-123"
tf search "test" --verbose
```

### Configuration Issues
1. **Check current configuration:**
   ```bash
   tf config-show
   ```

2. **Verify credentials:**
   ```bash
   tf configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE
   ```

3. **Test connection:**
   ```bash
   tf chats --verbose
   ```

## 📖 More Help

- **Command-specific help**: `tf COMMAND --help`
- **Detailed examples**: `tf help-guide`
- **Verbose debugging**: Use `--verbose` flag
- **JSON output**: Use `--output json` for machine-readable output
- **Configuration priority**: Environment variables → ~/.toothfairy/config.yml → CLI args

## ✨ Pro Tips

💾 **Save time**: Configure once with `tf configure`, then just use `tf send` and `tf search`

🔍 **Debug issues**: Use `--verbose` to see full API responses and troubleshoot

📝 **Scripting**: Use `--output json` and tools like `jq` to parse responses

⚡ **Quick tests**: Only `--agent-id` is required for send, only query for search

🎯 **Better search**: Use `--status`, `--topics`, and `--document-id` for targeted results

🔧 **Multiple environments**: Use different config files with `--config` flag

## 📄 License

MIT License - see LICENSE file for details.

## 🔗 Links

- **Repository**: [ToothFairy CLI on Gitea](https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli)
- **Python Package**: [toothfairy-cli on PyPI](https://pypi.org/project/toothfairy-cli/)
- **Node.js Package**: [@toothfairyai/cli on npm](https://www.npmjs.com/package/@toothfairyai/cli)
- **Issues**: [Report bugs and feature requests](https://gitea.toothfairyai.com/ToothFairyAI/tooth-fairy-website/toothfairy-cli/issues)
