Metadata-Version: 2.4
Name: victor-sdk
Version: 0.6.0
Summary: Victor SDK - Protocol definitions for vertical development
Author-email: Vijaykumar Singh <singhvjd@gmail.com>
Maintainer-email: Vijaykumar Singh <singhvjd@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/vjsingh1984/victor
Project-URL: Repository, https://github.com/vjsingh1984/victor
Project-URL: Documentation, https://docs.victor.dev/sdk
Project-URL: Issues, https://github.com/vjsingh1984/victor/issues
Keywords: ai,agents,llm,framework,sdk,protocols,verticals
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typing-extensions>=4.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: black==26.1.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"

# Victor SDK

Protocol and type definitions for building Victor verticals without pulling in
the Victor runtime.

## Overview

Use `victor-sdk` when you want to author or publish a vertical package. Use
`victor-ai` when you want to run a vertical inside the Victor host runtime.

The supported external authoring model is contract-first:

- vertical packages depend on `victor-sdk` only
- verticals declare tools, capabilities, prompts, teams, and workflow metadata through
  the SDK contract
- `victor-ai` remains responsible for runtime concerns such as agent creation,
  capability injection, and tool execution

## Installation

### SDK-only authoring

```bash
pip install victor-sdk
```

### Runtime usage

```bash
pip install victor-ai
```

## Stable SDK Surface

The core authoring surface is available from the top-level package:

```python
from victor_sdk import (
    CURRENT_DEFINITION_VERSION,
    CapabilityIds,
    CapabilityRequirement,
    ToolNames,
    ToolRequirement,
    VerticalBase,
    VerticalDefinition,
)
```

Key pieces:

- `VerticalBase`: SDK base class for external verticals
- `ToolNames`: canonical SDK-owned tool identifiers
- `CapabilityIds`: canonical SDK-owned runtime capability identifiers
- `ToolRequirement` / `CapabilityRequirement`: typed requirement declarations
- `VerticalDefinition`: validated serializable manifest returned by
  `get_definition()`

## Quick Start

```python
from victor_sdk import (
    CapabilityIds,
    CapabilityRequirement,
    ToolNames,
    ToolRequirement,
    VerticalBase,
)


class SecurityVertical(VerticalBase):
    name = "security"
    description = "Security analysis and audit workflows"
    version = "1.0.0"

    @classmethod
    def get_name(cls) -> str:
        return cls.name

    @classmethod
    def get_description(cls) -> str:
        return cls.description

    @classmethod
    def get_tool_requirements(cls) -> list[ToolRequirement]:
        return [
            ToolRequirement(ToolNames.READ, purpose="inspect code and configs"),
            ToolRequirement(ToolNames.GREP, purpose="search for vulnerable patterns"),
            ToolRequirement(ToolNames.SHELL, required=False, purpose="run scanners"),
            ToolRequirement(ToolNames.WEB_SEARCH, required=False, purpose="look up CVEs"),
        ]

    @classmethod
    def get_capability_requirements(cls) -> list[CapabilityRequirement]:
        return [
            CapabilityRequirement(
                capability_id=CapabilityIds.FILE_OPS,
                purpose="read repository contents",
            ),
            CapabilityRequirement(
                capability_id=CapabilityIds.WEB_ACCESS,
                optional=True,
                purpose="fetch external security references",
            ),
        ]

    @classmethod
    def get_system_prompt(cls) -> str:
        return "You are a security-focused assistant."

    @classmethod
    def get_prompt_templates(cls) -> dict[str, str]:
        return {
            "audit": "Audit the target for security issues and explain severity."
        }

    @classmethod
    def get_task_type_hints(cls) -> dict[str, dict[str, object]]:
        return {
            "audit": {
                "hint": "Start with read-first reconnaissance, then validate findings.",
                "tool_budget": 12,
                "priority_tools": [ToolNames.READ, ToolNames.GREP, ToolNames.SHELL],
            }
        }

    @classmethod
    def get_team_declarations(cls) -> dict[str, dict[str, object]]:
        return {
            "security_review_team": {
                "name": "Security Review Team",
                "formation": "pipeline",
                "members": [
                    {
                        "role": "researcher",
                        "goal": "Inspect the target and identify likely risks.",
                    },
                    {
                        "role": "reviewer",
                        "goal": "Validate findings before escalation.",
                    },
                ],
            }
        }


definition = SecurityVertical.get_definition()
assert definition.definition_version == "1.0"
assert definition.tools == [ToolNames.READ, ToolNames.GREP, ToolNames.SHELL, ToolNames.WEB_SEARCH]
assert definition.team_metadata.teams[0].team_id == "security_review_team"
```

## Definition Contract

`VerticalBase.get_definition()` is the preferred SDK contract. It returns a
validated `VerticalDefinition` manifest that contains:

- `definition_version`
- canonical tool identifiers
- typed tool and capability requirements
- system prompt text
- prompt metadata and task-type hints
- team metadata such as declarative team layouts and the default team identifier
- declarative stage definitions
- workflow metadata such as initial stage, provider hints, and evaluation criteria

Compatibility note:

- `get_config()` still exists as a bridge for current victor-ai integrations
- `VerticalDefinition.to_config()` / `from_config()` bridge the legacy config shape
- `VerticalDefinition.from_dict()` supports serialized manifest round-tripping

## Packaging

Register the vertical via the standard Victor entry point:

```toml
[project]
name = "victor-security"
version = "1.0.0"
dependencies = ["victor-sdk>=1.0.0"]

[project.entry-points."victor.verticals"]
security = "victor_security:SecurityVertical"
```

## Discovery

Victor discovers external verticals through Python entry points:

```python
from victor_sdk.discovery import get_global_registry

registry = get_global_registry()
verticals = registry.get_verticals()
```

## Guides And Examples

- [Vertical Development Guide](VERTICAL_DEVELOPMENT.md)
- [Migration Guide](MIGRATION_GUIDE.md)
- [Minimal SDK-only example](examples/minimal_vertical/README.md)
- [Repository external package example](../examples/external_vertical/README.md)

## Testing

```bash
pip install -e ".[dev]"
pytest victor-sdk/tests -q
```

To verify compatibility with the runtime as well:

```bash
pip install -e ".[dev]" victor-ai
pytest victor-sdk/tests/unit tests/integration/test_sdk_integration.py -q
```

## Versioning

The package follows semantic versioning, and the manifest contract is versioned
separately via `VerticalDefinition.definition_version`. External verticals
should treat the SDK contract as the source of truth for supported identifiers
and manifest fields.

## Links

- Repository: https://github.com/vjsingh1984/victor
- Issues: https://github.com/vjsingh1984/victor/issues
