agent-devkit 0.2.0 → 0.3.1

package/runtime/cli/aikit/workflows.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import Any
 
-from cli.aikit.tasks import create_task
+from cli.aikit.runtime_paths import ROOT
+from cli.aikit.tasks import create_task, load_tasks, run_task
 
 
 WORKFLOW_SCHEMA_VERSION = "agent-devkit.workflows/v1"
@@ -28,22 +30,23 @@ BUILTIN_WORKFLOWS: dict[str, dict[str, Any]] = {
 }
 
 
-def workflow_list() -> dict[str, Any]:
+def workflow_list(root: Path | None = None) -> dict[str, Any]:
+    workflows = load_workflows(root or ROOT)
     return {
         "kind": "workflows",
         "schema_version": WORKFLOW_SCHEMA_VERSION,
         "status": "ok",
-        "items": [public_workflow(item) for item in BUILTIN_WORKFLOWS.values()],
+        "items": [public_workflow(item) for item in workflows.values()],
     }
 
 
-def workflow_show(workflow_id: str) -> dict[str, Any]:
-    workflow = require_workflow(workflow_id)
+def workflow_show(workflow_id: str, root: Path | None = None) -> dict[str, Any]:
+    workflow = require_workflow(workflow_id, root=root)
     return {"kind": "workflow", "schema_version": WORKFLOW_SCHEMA_VERSION, "status": "ok", "workflow": public_workflow(workflow)}
 
 
-def workflow_install(workflow_id: str, *, dry_run: bool = True, yes: bool = False) -> dict[str, Any]:
-    workflow = require_workflow(workflow_id)
+def workflow_install(workflow_id: str, *, dry_run: bool = True, yes: bool = False, root: Path | None = None) -> dict[str, Any]:
+    workflow = require_workflow(workflow_id, root=root)
     mode = "dry-run" if dry_run or not yes else "apply"
     task = workflow["task"]
     plan = {
@@ -85,20 +88,67 @@ def workflow_install(workflow_id: str, *, dry_run: bool = True, yes: bool = Fals
     }
 
 
-def workflow_run(workflow_id: str, *, dry_run: bool = True) -> dict[str, Any]:
-    workflow = require_workflow(workflow_id)
+def workflow_run(workflow_id: str, *, dry_run: bool = True, root: Path | None = None) -> dict[str, Any]:
+    workflow = require_workflow(workflow_id, root=root)
+    task = workflow["task"]
+    plan = {
+        "task": {
+            "id": workflow["id"],
+            "title": task["title"],
+            "schedule": workflow["schedule"],
+            "action": task["action"],
+            "permissions": task["permissions"],
+            "notifications": task["notifications"],
+        },
+        "writes": ["local task registry", "task history"] if not dry_run else [],
+        "stores_secret": False,
+    }
+    if dry_run:
+        return {
+            "kind": "workflow-run",
+            "schema_version": WORKFLOW_SCHEMA_VERSION,
+            "status": "planned",
+            "dry_run": True,
+            "workflow": public_workflow(workflow),
+            "plan": plan,
+            "next_steps": [f"Run `agent workflow run {workflow['id']} --yes` to execute through the local task runtime."],
+        }
+    installed = ensure_workflow_task(workflow)
+    task_run = run_task(workflow["id"], dry_run=False, origin="workflow")
     return {
         "kind": "workflow-run",
         "schema_version": WORKFLOW_SCHEMA_VERSION,
-        "status": "planned" if dry_run else "blocked",
-        "dry_run": dry_run,
+        "status": task_run.get("status") or "failed",
+        "ok": task_run.get("ok") is True,
+        "dry_run": False,
         "workflow": public_workflow(workflow),
-        "message": "Workflow MVP runs through installed tasks; use workflow install first.",
+        "task_installed": installed,
+        "task_run": task_run,
+        "exit_code": task_run.get("exit_code"),
     }
 
 
-def require_workflow(workflow_id: str) -> dict[str, Any]:
-    workflow = BUILTIN_WORKFLOWS.get(workflow_id or "")
+def ensure_workflow_task(workflow: dict[str, Any]) -> bool:
+    task_id = workflow["id"]
+    data = load_tasks()
+    for item in data.get("tasks") or []:
+        if isinstance(item, dict) and item.get("id") == task_id:
+            return False
+    task = workflow["task"]
+    create_task(
+        task_id=task_id,
+        title=task["title"],
+        prompt=task["prompt"],
+        schedule=workflow["schedule"],
+        action=task["action"],
+        permissions=task["permissions"],
+        notifications=task["notifications"],
+    )
+    return True
+
+
+def require_workflow(workflow_id: str, root: Path | None = None) -> dict[str, Any]:
+    workflow = load_workflows(root or ROOT).get(workflow_id or "")
     if not workflow:
         raise ValueError(f"workflow not found: {workflow_id}")
     return workflow
@@ -112,4 +162,55 @@ def public_workflow(workflow: dict[str, Any]) -> dict[str, Any]:
         "schedule": workflow["schedule"],
         "write_policy": workflow["write_policy"],
         "stores_secret": False,
+        "providers_required": workflow.get("providers") or workflow.get("providers_required") or [],
+        "permissions": workflow.get("permissions") or {},
+        "outputs": workflow.get("outputs") or [],
+        "risks": workflow.get("risks") or [],
+        "examples": workflow.get("examples") or [],
+        "path": workflow.get("path"),
+    }
+
+
+def load_workflows(root: Path) -> dict[str, dict[str, Any]]:
+    workflows = dict(BUILTIN_WORKFLOWS)
+    workflows_dir = root / "workflows"
+    if not workflows_dir.exists():
+        return workflows
+    for manifest in sorted(workflows_dir.glob("*/workflow.yaml")):
+        item = load_workflow_manifest(manifest)
+        if item:
+            workflows[item["id"]] = item
+    return workflows
+
+
+def load_workflow_manifest(path: Path) -> dict[str, Any] | None:
+    try:
+        import yaml  # type: ignore
+    except ImportError:
+        return None
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict) or not data.get("id"):
+        return None
+    workflow = dict(data)
+    workflow.setdefault("title", str(workflow["id"]))
+    workflow.setdefault("description", "")
+    workflow.setdefault("schedule", {"type": "manual"})
+    workflow.setdefault("permissions", {"mode": "report-only"})
+    workflow.setdefault("write_policy", "local_config_write")
+    workflow.setdefault("task", default_task(workflow))
+    workflow["path"] = str(path)
+    return workflow
+
+
+def default_task(workflow: dict[str, Any]) -> dict[str, Any]:
+    prompt = str(workflow.get("description") or workflow.get("title") or workflow.get("id"))
+    return {
+        "title": workflow.get("title") or workflow.get("id"),
+        "prompt": prompt,
+        "action": {"type": "prompt", "prompt": prompt, "external_writes": False},
+        "permissions": workflow.get("permissions") or {"mode": "report-only"},
+        "notifications": [{"type": "desktop", "events": ["task.completed", "task.blocked"]}],
     }

package/runtime/models/qwen2.5-0.5b-instruct/manifest.json

@@ -0,0 +1,30 @@
+{
+  "schema_version": "agent-devkit.embedded-model/v1",
+  "model_id": "Qwen/Qwen2.5-0.5B-Instruct",
+  "model_name": "qwen2.5-0.5b-instruct",
+  "artifact": {
+    "filename": "qwen2.5-0.5b-instruct-q2_k.gguf",
+    "format": "gguf",
+    "quantization": "q2_k",
+    "size_bytes": 415182688,
+    "sha256": "9ee36184e616dfc76df4f5dd66f908dbde6979524ae36e6cefb67f532f798cb8",
+    "source": "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q2_k.gguf"
+  },
+  "provider": "embedded-mini-brain",
+  "license": "apache-2.0",
+  "runtime": "llama-cpp-python",
+  "purpose": [
+    "setup_help",
+    "wizard_conversation",
+    "intent_classification",
+    "command_explanation",
+    "short_error_summary"
+  ],
+  "guardrails": [
+    "no_secrets",
+    "low_risk_only",
+    "no_external_writes",
+    "coordinator_review_required"
+  ],
+  "notes": "This manifest declares the embedded mini-brain artifact downloaded on demand into .agent-devkit/models. Ollama remains an optional local worker pool for additional models."
+}

package/runtime/providers/knowledge-github.yaml

@@ -0,0 +1,40 @@
+id: knowledge-github
+name: Knowledge GitHub
+kind: knowledge-storage-provider
+status: draft
+description: Provider GitHub para versionar knowledge bases file-first em repositorios remotos.
+auth_methods:
+  - id: gh-auth
+    label: GitHub CLI auth
+    native: true
+    secret_fields: []
+  - id: token
+    label: GitHub token
+    secret_fields:
+      - GITHUB_TOKEN
+config_fields:
+  - name: GITHUB_TOKEN
+    required: false
+    secret: true
+  - name: GITHUB_REPOSITORY
+    required: false
+    secret: false
+  - name: AGENT_DEVKIT_KNOWLEDGE_LOCATION
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge-base.create
+    - knowledge.snapshot.submit
+health_check:
+  command: gh auth status
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps
+  - blocked

package/runtime/providers/knowledge-google-drive.yaml

@@ -0,0 +1,32 @@
+id: knowledge-google-drive
+name: Knowledge Google Drive
+kind: knowledge-storage-provider
+status: draft
+description: Provider Google Drive para armazenar knowledge bases file-first em pastas compartilhadas.
+auth_methods:
+  - id: oauth
+    label: Google OAuth
+    native: true
+    secret_fields: []
+config_fields:
+  - name: GOOGLE_APPLICATION_CREDENTIALS
+    required: false
+    secret: true
+  - name: AGENT_DEVKIT_KNOWLEDGE_DRIVE_FOLDER_ID
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge.snapshot.submit
+health_check:
+  command: agent provider doctor knowledge-google-drive
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps
+  - blocked

package/runtime/providers/knowledge-local.yaml

@@ -0,0 +1,26 @@
+id: knowledge-local
+name: Knowledge Local
+kind: knowledge-storage-provider
+status: active
+description: Storage file-first local para knowledge bases em diretorios Markdown, JSON e YAML.
+auth_methods: []
+config_fields:
+  - name: AGENT_DEVKIT_KNOWLEDGE_ROOT
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge.search
+    - knowledge-base.status
+  write:
+    - knowledge-base.create
+    - knowledge.snapshot.create
+    - knowledge.publish
+health_check:
+  command: agent knowledge doctor
+risk:
+  default: local
+  writes: true
+fallbacks:
+  - manual_steps
+  - plan_only

package/runtime/providers/knowledge-notion.yaml

@@ -0,0 +1,32 @@
+id: knowledge-notion
+name: Knowledge Notion
+kind: knowledge-storage-provider
+status: draft
+description: Provider Notion para espelhar knowledge base file-first em paginas ou databases autorizadas.
+auth_methods:
+  - id: notion-token
+    label: Notion integration token
+    secret_fields:
+      - NOTION_TOKEN
+config_fields:
+  - name: NOTION_TOKEN
+    required: false
+    secret: true
+  - name: AGENT_DEVKIT_KNOWLEDGE_NOTION_DATABASE_ID
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge.snapshot.submit
+health_check:
+  command: agent provider doctor knowledge-notion
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps
+  - blocked

package/runtime/providers/knowledge-obsidian.yaml

@@ -0,0 +1,24 @@
+id: knowledge-obsidian
+name: Knowledge Obsidian
+kind: knowledge-storage-provider
+status: draft
+description: Provider Obsidian para usar um vault local ou sincronizado como storage file-first.
+auth_methods: []
+config_fields:
+  - name: AGENT_DEVKIT_KNOWLEDGE_OBSIDIAN_VAULT
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge.snapshot.submit
+health_check:
+  command: agent provider doctor knowledge-obsidian
+risk:
+  default: local
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps

package/runtime/providers/knowledge-onedrive.yaml

@@ -0,0 +1,36 @@
+id: knowledge-onedrive
+name: Knowledge OneDrive
+kind: knowledge-storage-provider
+status: draft
+description: Provider OneDrive para sincronizar knowledge bases file-first em pastas autorizadas.
+auth_methods:
+  - id: microsoft-oauth
+    label: Microsoft OAuth
+    native: true
+    secret_fields: []
+  - id: graph-token
+    label: Microsoft Graph token
+    secret_fields:
+      - MICROSOFT_GRAPH_TOKEN
+config_fields:
+  - name: MICROSOFT_GRAPH_TOKEN
+    required: false
+    secret: true
+  - name: AGENT_DEVKIT_KNOWLEDGE_ONEDRIVE_LOCATION
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge.snapshot.submit
+health_check:
+  command: agent provider doctor knowledge-onedrive
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps
+  - blocked

package/runtime/providers/knowledge-s3.yaml

@@ -0,0 +1,45 @@
+id: knowledge-s3
+name: Knowledge S3
+kind: knowledge-storage-provider
+status: draft
+description: Provider S3 para armazenar knowledge bases file-first em buckets autorizados.
+auth_methods:
+  - id: aws-profile
+    label: AWS profile
+    native: true
+    secret_fields: []
+  - id: access-key
+    label: AWS access key
+    secret_fields:
+      - AWS_ACCESS_KEY_ID
+      - AWS_SECRET_ACCESS_KEY
+      - AWS_SESSION_TOKEN
+config_fields:
+  - name: AWS_PROFILE
+    required: false
+    secret: false
+  - name: AWS_REGION
+    required: false
+    secret: false
+  - name: AGENT_DEVKIT_KNOWLEDGE_S3_BUCKET
+    required: false
+    secret: false
+  - name: AGENT_DEVKIT_KNOWLEDGE_S3_PREFIX
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge-base.create
+    - knowledge.snapshot.submit
+health_check:
+  command: aws sts get-caller-identity
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps
+  - blocked

package/runtime/providers/knowledge-sharepoint.yaml

@@ -0,0 +1,39 @@
+id: knowledge-sharepoint
+name: Knowledge SharePoint
+kind: knowledge-storage-provider
+status: draft
+description: Provider SharePoint para armazenar knowledge bases file-first em bibliotecas documentais.
+auth_methods:
+  - id: microsoft-oauth
+    label: Microsoft OAuth
+    native: true
+    secret_fields: []
+  - id: graph-token
+    label: Microsoft Graph token
+    secret_fields:
+      - MICROSOFT_GRAPH_TOKEN
+config_fields:
+  - name: MICROSOFT_GRAPH_TOKEN
+    required: false
+    secret: true
+  - name: AGENT_DEVKIT_KNOWLEDGE_SHAREPOINT_SITE
+    required: false
+    secret: false
+  - name: AGENT_DEVKIT_KNOWLEDGE_SHAREPOINT_LOCATION
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge.snapshot.submit
+health_check:
+  command: agent provider doctor knowledge-sharepoint
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps
+  - blocked

package/runtime/providers/knowledge-supabase.yaml

@@ -0,0 +1,43 @@
+id: knowledge-supabase
+name: Knowledge Supabase Storage
+kind: knowledge-storage-provider
+status: draft
+description: Provider Supabase Storage para sincronizar knowledge bases file-first com buckets do projeto.
+auth_methods:
+  - id: supabase-cli
+    label: Supabase CLI auth
+    native: true
+    secret_fields: []
+  - id: access-token
+    label: Supabase access token
+    secret_fields:
+      - SUPABASE_ACCESS_TOKEN
+      - SUPABASE_SERVICE_ROLE_KEY
+config_fields:
+  - name: SUPABASE_PROJECT_REF
+    required: false
+    secret: false
+  - name: SUPABASE_ACCESS_TOKEN
+    required: false
+    secret: true
+  - name: SUPABASE_SERVICE_ROLE_KEY
+    required: false
+    secret: true
+  - name: AGENT_DEVKIT_KNOWLEDGE_BUCKET
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge-base.join
+    - knowledge.search
+  write:
+    - knowledge.snapshot.submit
+health_check:
+  command: supabase projects list
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - plan_only
+  - manual_steps
+  - blocked

package/runtime/providers/knowledge-vector.yaml

@@ -0,0 +1,39 @@
+id: knowledge-vector
+name: Knowledge Vector Index
+kind: knowledge-index-provider
+status: draft
+description: Provider de indice vetorial derivado; nunca e fonte canonica da knowledge base.
+auth_methods:
+  - id: local-vector
+    label: Local vector index
+    native: true
+    secret_fields: []
+  - id: external-vector
+    label: External vector service
+    secret_fields:
+      - VECTOR_DB_API_KEY
+      - VECTOR_DB_URL
+config_fields:
+  - name: VECTOR_DB_URL
+    required: false
+    secret: true
+  - name: VECTOR_DB_API_KEY
+    required: false
+    secret: true
+  - name: AGENT_DEVKIT_KNOWLEDGE_VECTOR_PROVIDER
+    required: false
+    secret: false
+capabilities:
+  read:
+    - knowledge.search
+  write:
+    - knowledge.reindex
+health_check:
+  command: agent knowledge doctor
+risk:
+  default: derived-index
+  writes: true
+fallbacks:
+  - skip_provider
+  - plan_only
+  - manual_steps

package/runtime/requirements.txt

@@ -0,0 +1,6 @@
+pypdf>=4.0
+beautifulsoup4>=4.12
+PyYAML>=6.0
+jsonschema>=4.0
+reportlab>=4.0
+pyodbc>=5.0