arckit-cli 6.1.1__py3-none-any.whl

arckit_cli-6.1.1.data/data/share/arckit/.arckit/templates/agent-design-template.md

@@ -0,0 +1,390 @@
+---
+title: "Agent Architecture Specification"
+docType: AAGR
+templateVersion: "1.0"
+---
+
+# Agent Architecture Specification
+
+## Document Control
+
+<!-- DOC-CONTROL-HEADER -->
+<!-- Resolved at command-execution time to _partials/document-control-uk.md or _partials/document-control-uae.md based on plugin userConfig classification_scheme + governance_framework. See _partials/RENDERING.md (when present). -->
+
+## Revision History
+
+| Version | Date | Author | Changes | Approved By | Approval Date |
+|---------|------|--------|---------|-------------|---------------|
+| [VERSION] | [DATE] | ArcKit AI | Initial creation from `/arckit:agent-design` command | [PENDING] | [PENDING] |
+
+---
+
+## 1. Agent Architecture Overview
+
+### 1.1 Architecture Pattern
+
+| Pattern | Description | When to Use |
+|---------|-------------|-------------|
+| Single Agent | [Description] | [Simple tasks, single domain] |
+| Chain | [Sequential pipeline] | [Multi-step reasoning] |
+| Multi-Agent | [Parallel workers] | [Complex domains, parallelization] |
+| Hierarchical | [Supervisor + workers] | [Coordinated multi-agent] |
+
+**Selected Pattern**: [Pattern name]
+
+**Justification**: [Why this pattern was chosen over alternatives, with reference to requirements and domain complexity]
+
+### 1.2 Component Diagram
+
+```mermaid
+C4Component
+    title Agent Architecture — Component Diagram
+    Person(user, "User", "End user")
+    System_Boundary(agent, "[Agent Name]")
+        Component(llm, "LLM Core", "[Model]")
+        Component(tools, "Tool Layer", "[MCP servers]")
+        Component(memory, "Memory", "[Session/Durable/Vector]")
+        Component(guardrails, "Guardrails", "[Safety layer]")
+    Rel(user, llm, "Sends prompts")
+    Rel(llm, tools, "Calls tools")
+    Rel(llm, memory, "Reads/writes")
+    Rel(llm, guardrails, "Subject to")
+```
+
+### 1.3 Agent Capabilities
+
+| Capability | Description | Priority |
+|------------|-------------|----------|
+| [C-001] | [Description] | [Must/Should/Could] |
+| [C-002] | [Description] | [Must/Should/Could] |
+| [C-003] | [Description] | [Must/Should/Could] |
+
+### 1.4 LLM Configuration
+
+| Setting | Value | Rationale |
+|---------|-------|-----------|
+| **Model** | [Model name and version] | [Why this model] |
+| **Temperature** | [0.0 – 1.0] | [Balancing creativity vs determinism] |
+| **Max Tokens** | [Number] | [Output length constraint] |
+| **Context Window** | [Tokens] | [Memory capacity requirement] |
+
+---
+
+## 2. Tool Contracts
+
+| Tool ID | Name | Type | Permissions | Input Schema | Output Schema |
+|---------|------|------|------------|-------------|---------------|
+| T-001 | [Name] | [MCP/REST/Function] | [Read/Write/Execute] | [Schema] | [Schema] |
+
+### 2.1 Tool Details
+
+#### T-001: [Tool Name]
+
+**Type**: [MCP / REST / Function Call / Database]
+
+**Permissions**: [Read / Write / Execute / Admin]
+
+**Description**: [What this tool does and why the agent needs it]
+
+**Input Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "[parameter]": {
+      "type": "[string/number/object]",
+      "description": "[Description]",
+      "required": [true/false]
+    }
+  }
+}
+```
+
+**Output Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "[result]": {
+      "type": "[string/number/object]",
+      "description": "[Description]"
+    }
+  }
+}
+```
+
+**Error Handling**: [How the agent handles tool failures, retries, timeouts]
+
+**Rate Limits**: [Request limits, burst limits, quotas]
+
+### 2.2 Tool Dependency Graph
+
+```mermaid
+flowchart LR
+    AGENT[Agent] --> T001[Tool 1]
+    AGENT --> T002[Tool 2]
+    AGENT --> T003[Tool 3]
+    T001 --> T002
+    T002 --> T003
+```
+
+---
+
+## 3. Memory Architecture
+
+| Layer | Type | Storage | Retention | Access |
+|-------|------|---------|-----------|--------|
+| Session | Ephemeral | In-memory | Session only | Read/Write |
+| Durable | Persistent | [DB] | [Indefinite] | Read/Write |
+| Vector | Semantic | [Vector DB] | [Configurable] | Search |
+
+### 3.1 Session Memory
+
+**Purpose**: Short-term context within a single conversation
+
+**Storage**: In-memory context window
+
+**Capacity**: [Max tokens/messages in context window]
+
+**Scope**: Single session, cleared on disconnect
+
+**Access Pattern**: LRU eviction when context limit reached
+
+### 3.2 Durable Memory
+
+**Purpose**: Cross-session persistence of preferences, decisions, and learned behaviors
+
+**Storage**: [Database technology — e.g., SQLite, PostgreSQL, Redis]
+
+**Schema**:
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Unique memory entry |
+| `agent_id` | String | Agent this memory belongs to |
+| `key` | String | Memory key/label |
+| `value` | JSON | Memory content |
+| `created_at` | Timestamp | When stored |
+| `updated_at` | Timestamp | Last modified |
+| `expires_at` | Timestamp | TTL or null for permanent |
+
+**Retention Policy**: [e.g., 90 days, indefinite, user-controlled]
+
+### 3.3 Vector Memory
+
+**Purpose**: Semantic search and retrieval of relevant information
+
+**Storage**: [Vector database — e.g., Chroma, Pinecone, Weaviate]
+
+**Embedding Model**: [Model name and dimensions]
+
+**Index Type**: [HNSW / IVF / Flat]
+
+**Retrieval Strategy**: [Top-K, similarity threshold, MMR]
+
+**Retrieval Schema**:
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `top_k` | [Number] | Results returned per query |
+| `similarity_threshold` | [0.0–1.0] | Minimum relevance score |
+| `namespace` | [Scope] | Query scope (session/project/global) |
+
+### 3.4 Memory Flow Diagram
+
+```mermaid
+flowchart LR
+    subgraph Session
+        S1[Context Window]
+        S2[Conversation History]
+    end
+    subgraph Durable
+        D1[Preferences]
+        D2[Learned Patterns]
+    end
+    subgraph Vector
+        V1[Document Index]
+        V2[Embedding Store]
+    end
+    AGENT --> S1
+    AGENT --> D1
+    AGENT --> V1
+    S2 -->|Summarize| D2
+    V2 -->|Retrieve| S1
+```
+
+---
+
+## 4. Orchestration Design
+
+| Component | Framework | Role | Handoff |
+|-----------|-----------|------|--------|
+| [Node 1] | [LangGraph/CrewAI/etc] | [Role] | [To Node 2] |
+
+### 4.1 Orchestration Flow
+
+```mermaid
+flowchart TD
+    START --> N1[Node 1: Input]
+    N1 --> N2[Node 2: Process]
+    N2 --> N3[Node 3: Output]
+    N3 --> END
+```
+
+### 4.2 Node Definitions
+
+#### Node 1: [Name]
+
+**Role**: [Input validation, prompt construction, task routing]
+
+**Inputs**: [User query, context, tool results]
+
+**Outputs**: [Validated request, structured task]
+
+**Guardrails**: [Input checks applied here]
+
+#### Node 2: [Name]
+
+**Role**: [Tool invocation, reasoning, knowledge retrieval]
+
+**Inputs**: [Task from Node 1, memory context]
+
+**Outputs**: [Results, intermediate findings]
+
+**Guardrails**: [Tool output validation]
+
+#### Node 3: [Name]
+
+**Role**: [Response formatting, quality check, output delivery]
+
+**Inputs**: [Results from Node 2]
+
+**Outputs**: [Final response to user]
+
+**Guardrails**: [Output validation, safety check]
+
+### 4.3 State Management
+
+| State Variable | Type | Persistence | Description |
+|----------------|------|-------------|-------------|
+| `task_id` | String | Session | Current task identifier |
+| `context` | Object | Session | Current context window |
+| `tool_history` | Array | Session | Recent tool calls and results |
+| `preferences` | Object | Durable | User preferences |
+| `metrics` | Object | Durable | Performance tracking |
+
+### 4.4 Error Handling and Retries
+
+| Error Type | Strategy | Max Retries | Backoff |
+|------------|----------|------------|---------|
+| Tool failure | Retry with exponential backoff | [3] | [1s, 2s, 4s] |
+| Rate limit | Wait and retry | [5] | [5s, 15s, 30s] |
+| LLM timeout | Retry with reduced context | [2] | [Immediate, 1s] |
+| Guardrail block | Fallback response | [0] | [None] |
+
+---
+
+## 5. Guardrail Configuration
+
+| Guardrail | Type | Threshold | Action |
+|-----------|------|-----------|--------|
+| Output validation | [Regex/LLM/Heuristic] | [Threshold] | [Block/Flag/Reroute] |
+
+### 5.1 Input Guardrails
+
+| Guardrail | Check | Pattern | Action |
+|-----------|-------|---------|--------|
+| Prompt injection | Semantic + regex | [Patterns] | Block and log |
+| Input length | Heuristic | [Max tokens] | Truncate or reject |
+| Sensitive data | Regex | [PII patterns] | Redact and proceed |
+| Malformed input | Schema validation | [JSON schema] | Request correction |
+
+### 5.2 Output Guardrails
+
+| Guardrail | Check | Pattern | Action |
+|-----------|-------|---------|--------|
+| Content safety | LLM classifier | [Policy] | Block and report |
+| Format compliance | Schema validation | [Expected schema] | Reroute to regeneration |
+| Hallucination check | Confidence scoring | [Threshold] | Flag and request source |
+| PII leakage | Regex detection | [PII patterns] | Redact output |
+
+### 5.3 Safety Pipeline
+
+```mermaid
+flowchart LR
+    INPUT --> G1[Input Sanitization]
+    G1 --> G2[Policy Check]
+    G2 --> AGENT[Agent Processing]
+    AGENT --> G3[Output Validation]
+    G3 --> G4[Content Safety]
+    G4 --> OUTPUT
+    G1 -->|Blocked| LOG1[Log & Alert]
+    G2 -->|Blocked| LOG2[Log & Alert]
+    G3 -->|Blocked| REGEN[Regenerate]
+    G4 -->|Blocked| LOG3[Log & Alert]
+```
+
+---
+
+## 6. Testing Strategy
+
+| Test Type | Coverage | Tool |
+|-----------|----------|------|
+| Unit | Tool contracts | pytest |
+| Integration | Agent flow | [Framework] |
+| Security | Prompt injection | [Tool] |
+
+### 6.1 Unit Tests
+
+| Test ID | Target | Input | Expected Output |
+|---------|--------|-------|-----------------|
+| UT-001 | T-001 tool | [Valid input] | [Expected schema] |
+| UT-002 | T-001 tool | [Invalid input] | [Error handling] |
+| UT-003 | Memory write | [Key-value pair] | [Persisted] |
+| UT-004 | Memory search | [Query] | [Relevant results] |
+
+### 6.2 Integration Tests
+
+| Test ID | Scenario | Steps | Expected Result |
+|---------|----------|-------|-----------------|
+| IT-001 | Full agent flow | [User query → Agent → Tool → Response] | [Correct answer with source] |
+| IT-002 | Multi-turn conversation | [Query → Follow-up → Resolution] | [Context maintained] |
+| IT-003 | Tool failure recovery | [Valid → Failed → Retry → Success] | [Graceful handling] |
+
+### 6.3 Security Tests
+
+| Test ID | Attack Vector | Method | Expected Result |
+|---------|---------------|--------|-----------------|
+| ST-001 | Prompt injection | [Direct injection] | [Blocked] |
+| ST-002 | Indirect injection | [Data poisoning] | [Detected] |
+| ST-003 | Tool abuse | [Permission escalation] | [Blocked] |
+| ST-004 | Data exfiltration | [Query engineering] | [Redacted] |
+
+### 6.4 Performance Tests
+
+| Test ID | Metric | Target | Measurement |
+|---------|--------|--------|-------------|
+| PT-001 | Response latency | < [X]s p95 | [Tool] |
+| PT-002 | Throughput | > [Y] req/min | [Tool] |
+| PT-003 | Context utilization | < [Z]% window | [Monitoring] |
+
+---
+
+## 7. Traceability
+
+| Source Artifact | Reference | How It Informs This Design |
+|-----------------|-----------|------------------------------|
+| AAGI (Agent Inventory) | ARC-{P}-AAGI-v{VERSION} | [Existing agents, capabilities, and operational context referenced] |
+| REQ (Requirements) | ARC-{P}-REQ-v{VERSION} | [FR-xxx, NFR-xxx mapped to capabilities] |
+| RISK (Risk Register) | ARC-{P}-RISK-v{VERSION} | [R-xxx risks addressed by guardrails] |
+| PRIN (Architecture Principles) | ARC-000-PRIN-v{VERSION} | [Principles influencing design choices] |
+| STKE (Stakeholder Analysis) | ARC-{P}-STKE-v{VERSION} | [Stakeholder needs driving agent design] |
+
+---
+
+> **Generated by**: ArcKit `/arckit:agent-design` command
+> **Generated on**: [DATE] [TIME] GMT
+> **ArcKit Version**: [VERSION]
+> **Project**: [PROJECT_NAME] (Project [PROJECT_ID])
+> **AI Model**: [MODEL_NAME]
+> **Generation Context**: [SOURCE_DOCUMENTS]

arckit_cli-6.1.1.data/data/share/arckit/.arckit/templates/agent-governance-template.md

@@ -0,0 +1,90 @@
+---
+title: "Agent Governance Framework"
+docType: AAOV
+templateVersion: "1.0"
+---
+
+# Agent Governance Framework
+
+## Document Control
+
+[Standard: ID=ARC-{P}-AAOV-v{VERSION}]
+
+---
+
+## 1. Oversight Model
+
+### 1.1 Oversight Tiers
+
+| Tier | Model | When Applied | Human Role |
+|------|-------|-------------|-----------|
+| Tier 1 | Human-in-the-loop | High-risk decisions, output to end users | Approves each action |
+| Tier 2 | Human-on-the-loop | Routine operations with monitoring | Reviews dashboards, intervenes if needed |
+| Tier 3 | Human-out-of-the-loop | Automated, auditable tasks | Post-facto audit |
+
+### 1.2 Oversight Assignment
+
+| Agent ID | Risk Level | Oversight Tier | Justification |
+|----------|-----------|---------------|---------------|
+| AGT-001 | [Critical] | [Tier 1] | [Justification] |
+
+## 2. Approval Matrix
+
+| Risk Tier | Decision Type | Approver | SLA | Escalation |
+|-----------|---------------|----------|-----|-----------|
+| Critical | All | [Named person + Board] | [1 business day] | [Board Chair] |
+| High | Operational | [Team lead] | [4 hours] | [Director] |
+| Medium | Automated | [System] | [Immediate] | [Team lead] |
+| Low | Fully automated | [Agent] | [Immediate] | [Monitor] |
+
+## 3. Audit Requirements
+
+| Audit Type | Frequency | Scope | Retention |
+|------------|-----------|-------|-----------|
+| Full audit | Quarterly | All agent actions | [2 years] |
+| Spot check | Weekly | Sample of outputs | [1 year] |
+| Security audit | Monthly | Security-relevant actions | [3 years] |
+
+## 4. Monitoring KPIs
+
+| KPI | Target | Current | Status |
+|-----|--------|---------|--------|
+| Approval rate | [>95%] | [98%] | ✅ |
+| Escalation rate | [<5%] | [3%] | ✅ |
+| Mean time to audit | [<24h] | [12h] | ✅ |
+
+## 5. Escalation Procedures
+
+```mermaid
+flowchart TD
+    A[Agent detects anomaly] --> B{Risk level}
+    B -->|Low| C[Log and continue]
+    B -->|Medium| D[Notify human monitor]
+    B -->|High| E[Halt and escalate]
+    E --> F[Incident response]
+```
+
+## 6. Incident Response Plan
+
+| Phase | Action | Owner | Timeline |
+|-------|--------|-------|----------|
+| Detection | [Auto-monitoring triggers] | [System] | [Immediate] |
+| Containment | [Isolate agent] | [SRE] | [<15 min] |
+| Assessment | [Determine scope] | [Lead architect] | [<1h] |
+| Resolution | [Apply fix] | [Team] | [<4h] |
+| Post-mortem | [Root cause, prevention] | [Team] | [<1 week] |
+
+## 7. Compliance Mapping
+
+| Framework | Requirement | Status | Evidence |
+|-----------|-------------|--------|----------|
+| UK AI Playbook | [Req ID] | [Compliant/Partial] | [Evidence] |
+| EU AI Act | [Annex] | [Compliant/Partial] | [Evidence] |
+| NIST AI RMF | [Function] | [Compliant/Partial] | [Evidence] |
+
+## 8. Traceability
+
+[AAGI → AAGR → AAOV links]
+
+---
+[Generation footer]

arckit_cli-6.1.1.data/data/share/arckit/.arckit/templates/agent-integration-template.md

@@ -0,0 +1,159 @@
+---
+title: "Agent Integration Architecture"
+docType: AAIN
+templateVersion: "1.0"
+---
+
+# Agent Integration Architecture
+
+## Document Control
+
+| Field | Value |
+|-------|-------|
+| Document ID | ARC-{P}-AAIN-v{VERSION} |
+| Document Type | AAIN — Agent Integration Architecture |
+| Project | {PROJECT_NAME} ({PROJECT_ID}) |
+| Classification | {CLASSIFICATION} |
+| Status | {STATUS} |
+| Version | {VERSION} |
+| Created | {DATE} |
+| Last Modified | {DATE} |
+| Review Cycle | Monthly |
+| Next Review | {NEXT_REVIEW_DATE} |
+| Owner | {OWNER_NAME_AND_ROLE} |
+| Reviewed By | — |
+| Approved By | — |
+| Distribution | Architecture Team, AI Programme Board |
+
+---
+
+## 1. Integration Architecture
+
+### 1.1 Overview
+
+[Overview of multi-agent system — purpose, scope, and agents involved]
+
+### 1.2 Integration Pattern
+
+| Pattern | Description | When to Use |
+|---------|-------------|-------------|
+| Event-Driven | Agents communicate via events | Async, decoupled |
+| Request-Response | Direct synchronous calls | Tight coupling, real-time |
+| Message Queue | Asynchronous message passing | Buffered processing |
+| Shared State | Common state repository | Coordinated state |
+
+> **Selected patterns**: [List selected patterns with justification]
+
+---
+
+## 2. Inter-Agent Contracts
+
+| Contract ID | Source Agent | Target Agent | Interface | Protocol | SLA |
+|-------------|------------|--------------|----------|----------|-----|
+| CNT-001 | [Agent A] | [Agent B] | [Interface] | [gRPC/HTTP/Queue] | [<1s] |
+| CNT-002 | [Agent A] | [Agent C] | [Interface] | [gRPC/HTTP/Queue] | [<1s] |
+| CNT-003 | [Agent B] | [Agent C] | [Interface] | [gRPC/HTTP/Queue] | [<1s] |
+
+> **Minimum**: At least 3 agent contracts must be documented.
+
+### Contract Specification
+
+```json
+{
+  "contractId": "CNT-001",
+  "version": "1.0.0",
+  "input": {
+    "type": "object",
+    "properties": {
+      "taskId": { "type": "string" },
+      "payload": { "type": "object" }
+    }
+  },
+  "output": {
+    "type": "object",
+    "properties": {
+      "result": { "type": "object" },
+      "status": { "type": "string", "enum": ["success", "error"] }
+    }
+  }
+}
+```
+
+> **Repeat** contract specifications for each contract (CNT-002, CNT-003, etc.)
+
+---
+
+## 3. Message Protocol
+
+```mermaid
+sequenceDiagram
+    participant Orchestrator
+    participant Worker1
+    participant Worker2
+    participant SharedState
+    Orchestrator->>Worker1: Assign Task
+    Worker1->>SharedState: Read Context
+    Worker1->>Orchestrator: Return Result
+    Orchestrator->>Worker2: Assign Next Task
+```
+
+> **Note**: Update participant names and message flows to match actual agents and protocols.
+
+---
+
+## 4. Shared State Design
+
+| Store | Type | Purpose | Access Pattern |
+|-------|------|---------|----------------|
+| [Redis] | KV store | Session state | Read/Write |
+| [PostgreSQL] | Relational | Durable state | Read/Write |
+| [Qdrant] | Vector | Semantic search | Search |
+
+> **Note**: Update stores to match actual infrastructure. Document consistency model (eventual/strong) per store.
+
+---
+
+## 5. Failure Isolation
+
+| Boundary | Isolation Level | Failure Mode | Recovery |
+|----------|----------------|-------------|----------|
+| Agent process | [Container/Process] | [Crash, timeout] | [Restart, retry] |
+| Tool execution | [Sandbox/Timeout] | [API failure] | [Fallback, retry] |
+| Message delivery | [At-least-once] | [Duplicate] | [Dedup] |
+
+---
+
+## 6. Observability
+
+| Component | Metric | Alert |
+|-----------|--------|-------|
+| Agent health | [Uptime, latency] | [>99.9% SLA] |
+| Message queue | [Depth, throughput] | [Depth > 1000] |
+| Error rate | [Failed/Total] | [>1%] |
+
+---
+
+## 7. Traceability
+
+| Source | Reference | Link |
+|--------|-----------|------|
+| AAGR | [Agent Architecture Specification] | `ARC-{P}-AAGR-v{VER}` |
+| AAGI | [Agent Inventory] | `ARC-{P}-AAGI-v{VER}` |
+| AAOV | [Agent Governance Framework] | `ARC-{P}-AAOV-v{VER}` |
+| AASE | [Agent Security Architecture] | `ARC-{P}-AASE-v{VER}` |
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes | Approved By | Approval Date |
+|---------|------|--------|---------|-------------|--------------|
+| 1.0 | {DATE} | ArcKit AI | Initial creation from `/arckit:agent-integration` command | — | — |
+
+---
+
+**Generated by**: ArcKit `/arckit:agent-integration` command
+**Generated on**: {DATE}
+**ArcKit Version**: {ARCKIT_VERSION}
+**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
+**AI Model**: [Model Name]