Metadata-Version: 2.4
Name: devantis-sdk
Version: 0.3.7
Summary: Python SDK and MCP server for the Devantis AI development platform
Author-email: Encode IT <info@encodeit.ro>
License-Expression: MIT
Project-URL: Homepage, https://github.com/encode-it-srl/devantis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Requires-Dist: websockets>=12.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# devantis-sdk

Python SDK and MCP server for the [Devantis](https://devantis.dev) AI development platform. Connect Claude CLI, Claude Desktop, or any MCP-compatible client to your Devantis projects with **90 tools** for managing source code, tickets, requirements, architecture, designs, AI chat, knowledge graph, deployments, and more.

## Installation

```bash
pip install devantis-sdk[mcp]
```

This installs the SDK with MCP server support and WebSocket chat. For the core SDK without MCP:

```bash
pip install devantis-sdk
```

**Requirements:** Python 3.11+

## Setup

### 1. Login

```bash
devantis login
```

Opens your browser for Keycloak authentication. Saves the token to `~/.devantis_token.json`. The token auto-refreshes — you only need to login once.

### 2. Configure your context

```bash
devantis config
```

Interactive picker for your organisation, project, and application. Saves to `~/.devantis.yaml`.

Or set via environment variables:

```bash
export DEVANTIS_ORG=my-org
export DEVANTIS_PROJECT=my-project
export DEVANTIS_APP=my-app
```

### 3. Connect to services

The SDK defaults to the **development platform** at `https://devantis.dev.encodeit.ro`. No extra configuration needed after login + config.

**Override the API URL** for other environments:

| Environment | How it works | Config |
|---|---|---|
| **Development** (default) | Gateway mode — all services behind `devantis.dev.encodeit.ro` | No config needed |
| **Local** (docker-compose) | Each service on its own localhost port | `export DEVANTIS_API_URL=""` |
| **Docker** (inside container) | Docker-internal hostnames | `INTERNAL_SERVICE_KEY` env var (auto-detected) |
| **Custom** | Any other gateway URL | `export DEVANTIS_API_URL=https://your-instance.example.com` |

You can also set the URL permanently in `~/.devantis-mcp.yaml`:

```yaml
api_url: https://devantis.dev.encodeit.ro   # or any custom URL
```

**Priority order:** `DEVANTIS_API_URL` env var > `~/.devantis-mcp.yaml` `api_url` > built-in default

## Use as MCP Server (Claude CLI)

### Register

```bash
claude mcp add devantis -- devantis-mcp
```

Or with a specific Python path:

```bash
claude mcp add devantis -- /path/to/venv/bin/python -m devantis
```

### Verify

```bash
claude mcp list
# devantis: ... - Connected
```

### Start using

Open Claude CLI and ask anything:

```
> List all open tickets

> Search the codebase for authentication

> Create a requirement for user registration

> Ask the AI assistant to implement the login page

> What does the brain know about our API design?

> Show me the kanban board
```

All 90 tools are available automatically. Claude picks the right tool based on your request.

### Chat sessions

The MCP server manages chat sessions with the platform's AI assistant:

- First `devantis_chat_send` creates a new session automatically
- Subsequent calls reuse the same session (multi-turn conversation)
- When the AI pauses for approval, Claude shows you the question and you approve/deny normally
- Switching context (`devantis_switch_context`) clears the session

You can also manage sessions explicitly with `devantis_chat_session`.

## Use as MCP Server (Claude Desktop)

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "devantis": {
      "command": "devantis-mcp",
      "env": {
        "DEVANTIS_ORG": "my-org",
        "DEVANTIS_PROJECT": "my-project",
        "DEVANTIS_APP": "my-app"
      }
    }
  }
}
```

## Use as Python SDK

```python
import asyncio
from devantis import DevantisClient

async def main():
    client = await DevantisClient.connect()

    # Source code
    files = await client.source.list()
    content = await client.source.read("src/main.py")
    matches = await client.source.grep("def login", glob="*.py")
    await client.source.write("src/hello.py", "print('hello')")
    await client.source.batch_write([
        {"path": "src/a.py", "content": "# file a"},
        {"path": "src/b.py", "content": "# file b"},
    ])

    # Tickets
    tickets = await client.tickets.list(status="open", priority="high")
    ticket = await client.tickets.create(
        title="Implement OAuth2",
        description="Add OAuth2 login flow",
        feature="authentication",
    )
    await client.tickets.transition(ticket["id"], "start")
    await client.tickets.add_comment(ticket["id"], "Working on this now")

    # Sprints and epics
    sprints = await client.tickets.list_sprints(status="active")
    epics = await client.tickets.list_epics()
    board = await client.tickets.get_board("kanban")
    stats = await client.tickets.get_stats()

    # Requirements
    reqs = await client.requirements.list(status="approved")
    await client.requirements.create(
        title="User Registration",
        description="Users must be able to register...",
        feature="authentication",
    )

    # Architecture and designs
    docs = await client.architecture.list()
    designs = await client.designs.list(file_type="html")

    # Chat with AI assistant
    result = await client.chat.send("How does the auth system work?")
    print(result["content"])

    # If the assistant pauses for approval:
    if result["status"] == "waiting_for_input":
        result = await client.chat.answer(result["session_id"], "Yes, proceed")

    # Knowledge graph (AI brain)
    entities = await client.knowledge_graph.search("auth")
    await client.knowledge_graph.create_entity(
        name="auth-service",
        entity_type="service",
        observations=[{"content": "Uses JWT with 15min expiry", "kind": "fact"}],
    )
    answer = await client.knowledge_graph.reason("How does authentication work?")
    vitals = await client.knowledge_graph.vitals()

    # Cross-entity search
    results = await client.search("authentication")

    # Team management
    members = await client.projects.list_members(level="app")
    me = await client.users.me()

    # Analytics
    usage = await client.analytics.token_usage(view="summary")

    # Billing & Licensing
    plan = await client.billing.get_plan()
    entitlements = await client.billing.get_entitlements()
    credits = await client.billing.get_credits()
    invoices = await client.billing.list_invoices(month="2026-04")
    usage_summary = await client.billing.get_usage()
    seat_cost = await client.billing.get_seat_cost()
    packs = await client.billing.list_credit_packs()
    tax = await client.billing.get_tax_summary()

    # Switch context
    await client.switch_context(app="other-app")

    await client.close()

asyncio.run(main())
```

## Available Services

| Service | Access via | Description |
|---|---|---|
| `source` | `client.source` | File read/write/edit/delete, grep, glob, batch operations |
| `tickets` | `client.tickets` | Full ticket lifecycle, labels, subtasks, links, sprints, epics, boards, charts |
| `requirements` | `client.requirements` | Requirement CRUD, search, feature listing |
| `architecture` | `client.architecture` | Architecture documents and diagrams |
| `designs` | `client.designs` | Design files (HTML, CSS, tokens) |
| `chat` | `client.chat` | AI assistant messaging with pause/resume support |
| `knowledge_graph` | `client.knowledge_graph` | AI brain — entities, observations, relations, reasoning |
| `executors` | `client.executors` | Remote shell commands, Kubernetes deployments |
| `projects` | `client.projects` | Org/project/app management, members, config |
| `analytics` | `client.analytics` | Token usage, cost forecast, alerts |
| `users` | `client.users` | User search and profiles |
| `notifications` | `client.notifications` | Notification channels and subscriptions |
| `billing` | `client.billing` | Invoices, credits, plans, quotas, subscriptions, tax, cost breakdowns |
| `memory` | `client.memory` | Persistent key-value project memory |
| `docs` | `client.docs` | Platform documentation |

## MCP Tools (90 total)

### Source Code (9 tools)

| Tool | Description |
|---|---|
| `devantis_read_file` | Read a source code file |
| `devantis_write_file` | Create or overwrite a file |
| `devantis_edit_file` | Targeted find-and-replace with fuzzy matching |
| `devantis_delete_file` | Delete a file |
| `devantis_move_file` | Move or rename a file |
| `devantis_list_files` | List files, optionally by folder |
| `devantis_glob_files` | Find files by glob pattern |
| `devantis_grep` | Regex search inside file contents |
| `devantis_batch_files` | Write/delete/edit up to 20 files at once |

### Tickets (23 tools)

| Tool | Description |
|---|---|
| `devantis_list_tickets` | List with filters (status, priority, sprint, epic) |
| `devantis_get_ticket` | Full ticket details |
| `devantis_create_ticket` | Create a ticket |
| `devantis_update_ticket` | Update ticket fields |
| `devantis_delete_ticket` | Delete a ticket |
| `devantis_transition_ticket` | Move through workflow (start, review, done, block) |
| `devantis_search_tickets` | Full-text search |
| `devantis_add_ticket_comment` | Add a comment |
| `devantis_list_ticket_comments` | List comments |
| `devantis_manage_labels` | Label CRUD and ticket assignment |
| `devantis_manage_subtasks` | Subtask CRUD |
| `devantis_manage_links` | Link tickets (blocks, duplicates, relates_to) |
| `devantis_ticket_watch` | Watch/unwatch tickets |
| `devantis_ticket_vote` | Vote on tickets |
| `devantis_ticket_timelog` | Log time on tickets |
| `devantis_manage_milestones` | Milestone CRUD and ticket assignment |
| `devantis_manage_components` | Component CRUD and ticket assignment |
| `devantis_manage_filters` | Saved filter CRUD and execution |
| `devantis_get_board` | Kanban, by-assignee, by-feature, by-priority boards |
| `devantis_get_chart` | Burndown, burnup, cumulative flow, velocity charts |
| `devantis_ticket_stats` | Aggregate statistics |
| `devantis_manage_sprints` | Sprint lifecycle and ticket management |
| `devantis_manage_epics` | Epic CRUD and ticket management |

### Requirements (5 tools)

| Tool | Description |
|---|---|
| `devantis_list_requirements` | List with filters |
| `devantis_get_requirement` | Full requirement details |
| `devantis_create_requirement` | Create a requirement |
| `devantis_update_requirement` | Update fields |
| `devantis_delete_requirement` | Delete a requirement |

### Architecture (6 tools)

| Tool | Description |
|---|---|
| `devantis_list_architecture` | List documents and diagrams |
| `devantis_read_architecture` | Read document content |
| `devantis_create_architecture` | Create document or diagram |
| `devantis_update_architecture` | Update content |
| `devantis_delete_architecture` | Delete a document |
| `devantis_search_architecture` | Search by name |

### Designs (6 tools)

| Tool | Description |
|---|---|
| `devantis_list_designs` | List design files (HTML, CSS, tokens) |
| `devantis_read_design` | Read file content |
| `devantis_create_design` | Create a design file |
| `devantis_update_design` | Update content |
| `devantis_delete_design` | Delete a file |
| `devantis_search_designs` | Search designs |

### AI Assistant Chat (8 tools)

| Tool | Description |
|---|---|
| `devantis_chat_session` | Manage active session (set, start, clear, get) |
| `devantis_chat_send` | Send message and collect response |
| `devantis_chat_answer` | Answer a paused workflow's question |
| `devantis_chat_confirm` | Approve/reject a workflow proposal |
| `devantis_chat_history` | Get conversation history |
| `devantis_chat_sessions` | List recent sessions |
| `devantis_chat_stop` | Cancel running workflow |
| `devantis_chat_delete` | Delete a session |

### Knowledge Graph / AI Brain (12 tools)

| Tool | Description |
|---|---|
| `devantis_kg_search` | Search entities and observations |
| `devantis_kg_get_entity` | Get entity with all observations |
| `devantis_kg_add` | Create entity with observations |
| `devantis_kg_add_observation` | Add observation to existing entity |
| `devantis_kg_remove` | Delete entity, observation, or relation |
| `devantis_kg_relations` | Manage entity relations |
| `devantis_kg_reason` | LLM reasoning over stored knowledge |
| `devantis_kg_stats` | Graph statistics |
| `devantis_kg_vitals` | Brain health and intelligence score |
| `devantis_kg_impact` | Impact analysis (what depends on this?) |
| `devantis_kg_confirm_observation` | Mark observation as still valid |
| `devantis_kg_dependencies` | Recursive dependency traversal |

### Executors and Deployment (3 tools)

| Tool | Description |
|---|---|
| `devantis_executor_shell` | Run shell commands on remote agents |
| `devantis_deploy_k8s` | Kubernetes operations via MCP |
| `devantis_list_executors` | List executor agents and status |

### Analytics (2 tools)

| Tool | Description |
|---|---|
| `devantis_token_usage` | Token usage and cost analytics |
| `devantis_cost_forecast` | Cost predictions and spending alerts |

### Users and Team (4 tools)

| Tool | Description |
|---|---|
| `devantis_users_search` | Find users by name or email |
| `devantis_users_me` | Current user profile |
| `devantis_list_members` | List members at org/project/app level |
| `devantis_manage_members` | Add, update, or remove members |

### Billing & Licensing (1 tool, 27 actions)

| Tool | Description |
|---|---|
| `devantis_billing` | Unified billing tool with `action` parameter |

**Plan & Quotas:** `get_plan`, `list_plans`, `get_entitlements`, `get_usage`, `get_overage_rates`
**Invoices:** `list_invoices`, `get_invoice`, `upcoming_invoice`, `retry_invoice`
**Credits:** `get_credits`, `list_transactions`, `list_credit_packs`, `purchase_credits`, `allocate_credits`
**Subscription:** `cancel_subscription`, `reactivate_subscription`
**Payment Methods:** `list_payment_methods`, `remove_payment_method`, `set_default_payment_method`
**Tax:** `get_tax_summary`, `list_tax_ids`, `add_tax_id`, `remove_tax_id`, `get_tax_types`
**Cost Breakdown:** `get_seat_cost`, `get_executor_cost`, `get_k8s_cost`, `get_registry_cost`

### Platform (11 tools)

| Tool | Description |
|---|---|
| `devantis_search` | Cross-entity parallel search |
| `devantis_memory` | Persistent project memory |
| `devantis_switch_context` | Switch org/project/app |
| `devantis_list_projects` | List orgs, projects, or apps |
| `devantis_get_config` | Get app configuration |
| `devantis_update_config` | Update configuration |
| `devantis_manage_notifications` | Notification channels and subscriptions |
| `devantis_bulk_tickets` | Batch ticket operations |
| `devantis_list_docs` | List documentation pages |
| `devantis_read_doc` | Read a documentation page |
| `devantis_search_docs` | Search documentation |

## Authentication Modes

| Mode | Use case | Configuration |
|---|---|---|
| **User token** | Local dev, Claude CLI | `devantis login` (saves to `~/.devantis_token.json`) |
| **Internal key** | Docker containers, workers | `INTERNAL_SERVICE_KEY` env var |
| **Service account** | Server-to-server | Keycloak client credentials |

Auto-detected based on environment. No manual selection needed.

## Links

- **Platform**: [devantis.dev](https://devantis.dev)
- **Source**: [github.com/encode-it-srl/devantis](https://github.com/encode-it-srl/devantis)

## License

MIT
