qp-conductor 0.1.0__tar.gz

qp_conductor-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug Report
+about: Report a bug in qp-conductor
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## Describe the Bug
+
+A clear description of what the bug is.
+
+## To Reproduce
+
+```python
+from qp_conductor import GoalService, InMemoryStorage
+
+storage = InMemoryStorage()
+service = GoalService(storage=storage)
+# Minimal reproducer here
+```
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include the full traceback if applicable.
+
+## Environment
+
+- **OS**: (e.g., macOS 15, Ubuntu 24.04)
+- **Python**: (e.g., 3.12.4)
+- **qp-conductor version**: (e.g., 0.1.0)
+- **Install extras**: (e.g., `[vault]`, `[redis]`)
+
+## Additional Context
+
+Any other context about the problem.

qp_conductor-0.1.0/.github/ISSUE_TEMPLATE/capability_request.md

@@ -0,0 +1,45 @@
+---
+name: Capability Request
+about: Suggest a new capability for the registry
+title: "[Capability] "
+labels: capability
+assignees: ''
+---
+
+## Domain
+
+- [ ] Analysis
+- [ ] Planning
+- [ ] Creation
+- [ ] Investigation
+- [ ] Validation
+- [ ] Communication
+- [ ] Execution
+- [ ] Audio
+- [ ] Sysadmin
+- [ ] New domain
+
+## Description
+
+What would this capability do?
+
+## Use Case
+
+Who would use this and why?
+
+## Proposed YAML
+
+```yaml
+name: my_capability
+domain: analysis
+description: What this capability does
+risk_level: medium
+required_tools:
+  - tool_name
+dependencies: []
+estimated_duration_minutes: 10
+```
+
+## Additional Context
+
+Links to relevant tools, APIs, or documentation.

qp_conductor-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest an enhancement to qp-conductor
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+What problem does this solve? What use case is not currently supported?
+
+## Proposed Solution
+
+Describe your preferred approach.
+
+## Alternatives Considered
+
+What other approaches did you consider?
+
+## Additional Context
+
+Any other context, screenshots, or references.

qp_conductor-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Summary
+
+What does this PR do? Link to any related issues.
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that changes existing behavior)
+- [ ] New capability (YAML definition in the registry)
+- [ ] Documentation update
+- [ ] Test improvement
+
+## Checklist
+
+- [ ] Tests pass: `make test`
+- [ ] Linter passes: `make lint`
+- [ ] No deprecation warnings
+- [ ] Documentation updated (if applicable)
+- [ ] CHANGELOG.md updated (if user-facing change)
+- [ ] Safety constraints preserved (HIGH-risk never auto-approved)
+
+## How Has This Been Tested?
+
+Describe the tests that cover this change.

qp_conductor-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "ci"

qp_conductor-0.1.0/.github/workflows/python-ci.yaml

@@ -0,0 +1,62 @@
+name: Python CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: mypy src/qp_conductor/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v --tb=short --cov=qp_conductor --cov-report=term-missing
+
+  publish:
+    needs: [lint, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

qp_conductor-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting & Type Checking
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Database
+*.db
+*.sqlite

qp_conductor-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-07
+
+### Added
+- Initial release
+- **Goal Analyzer**: Natural language to capability requirements with intent classification (GOAL/SPECIFICATION/HYBRID/AMBIGUOUS)
+- **Capability Composer**: Requirements to dependency-ordered execution plan via topological sort
+- **Autonomy Calculator**: YAML-configured oversight levels (L0 blocked through L4 fully autonomous)
+- **Conductor**: Multi-agent orchestration with parallel execution and Capsule sealing
+- **Checkpoint Manager**: Human approval gates with async wait pattern
+- **Adaptation Engine**: Self-improvement via signal capture, pattern mining, safety validation, adapter creation
+- **Drift Detector**: Behavioral consistency monitoring via cosine distance on embedding fingerprints
+- **Organizational Memory**: Learn from past goals (in-memory + optional Vault backend)
+- **Persistent Scheduler**: Cron-based recurring workflows
+- **Priority Inbox**: Risk-sorted task approval (HIGH risk first, LOW confidence first, OLDEST first)
+- **Auto-Approval Rules**: Pattern-based with safety constraints (HIGH-risk tasks never auto-approved)
+- **Goal State Machine**: 25 transitions covering the full goal lifecycle
+- **Task State Machine**: 14 transitions from PENDING through COMPLETED/FAILED
+- **42 capabilities** across 9 domains (analysis, planning, creation, investigation, validation, communication, execution, audio, sysadmin)
+- **Goal Service**: Create, clarify, cancel, update progress
+- **Task Service**: Approve, decline, skip, retry, batch operations
+- **Auto-Approve Service**: Rule CRUD with safety enforcement
+- **InMemoryStorage**: Zero-dependency storage backend for development
+- **Protocol interfaces**: LLM, Agent, AgentRegistry, CapsuleChain, Seal, KillSwitch, Vault
+- **Safety gates**: Forbidden patterns (injection), forbidden agents (auditor, deployer), HIGH-risk never auto-approved
+- **Hub Genome parser**: YAML to autonomous business configuration
+- 459 tests with 90% coverage threshold
+
+### Security
+- HIGH-risk tasks always require human review
+- Security agents (auditor, deployer) cannot receive prompt modifications
+- Shell injection, SQL injection, path traversal, and secret leakage patterns blocked
+- Kill switch checked on every agent iteration
+
+[unreleased]: https://github.com/quantumpipes/conductor/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/quantumpipes/conductor/releases/tag/v0.1.0

qp_conductor-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at conduct@quantumpipes.io.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.0.

qp_conductor-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to qp-conductor
+
+Thank you for your interest in contributing to qp-conductor. This document explains how to get involved.
+
+## Repository Structure
+
+```
+conductor/
+├── src/qp_conductor/       <- Source code
+│   ├── core/               <- GoalAnalyzer, CapabilityComposer, AutonomyCalculator, CheckpointManager
+│   ├── models/             <- Goal, Task, Workflow, Capability, AutoApprove dataclasses
+│   ├── state_machines/     <- GoalStateMachine (25 transitions), TaskStateMachine (14 transitions)
+│   ├── capabilities/       <- CapabilityRegistry + 42 YAML definitions across 9 domains
+│   ├── goals/              <- GoalService, TaskService, AutoApproveService
+│   ├── storage/            <- StorageProtocol + InMemoryStorage
+│   ├── adaptation/         <- AdaptationEngine, SignalCapture, SafetyGates
+│   ├── drift/              <- BehavioralDriftDetector (cosine distance)
+│   ├── memory/             <- OrganizationalMemory (in-memory + optional Vault)
+│   ├── scheduler/          <- Cron scheduler
+│   ├── genome/             <- Hub Genome parser
+│   ├── cli/                <- Typer CLI
+│   ├── integrations/       <- FastAPI mount
+│   └── protocols.py        <- Protocol interfaces for all external integration
+├── tests/                  <- Test suite (459 tests)
+└── INTEGRATION.md          <- Cross-package integration guide
+```
+
+## Getting Started
+
+```bash
+git clone https://github.com/quantumpipes/conductor.git
+cd conductor
+pip install -e ".[dev]"
+make test
+```
+
+## Types of Contributions
+
+### Bug Fixes
+
+- Open an issue describing the bug
+- Include a minimal reproduction case
+- Submit a PR with a test that fails before the fix and passes after
+
+### New Capabilities
+
+Add a YAML file to `src/qp_conductor/capabilities/registry/`:
+
+```yaml
+name: my_capability
+domain: analysis
+description: What this capability does
+risk_level: medium
+required_tools:
+  - tool_name
+dependencies: []
+estimated_duration_minutes: 10
+```
+
+No code changes required. The registry auto-discovers YAML files.
+
+### New Storage Backends
+
+Implement the `StorageProtocol` in `src/qp_conductor/storage/`:
+
+```python
+class StorageProtocol(Protocol):
+    async def save_goal(self, goal: Goal) -> None: ...
+    async def get_goal(self, goal_id: str) -> Goal | None: ...
+    async def save_task(self, task: Task) -> None: ...
+    # ... see storage/protocol.py for full interface
+```
+
+### Documentation
+
+Improvements to README, INTEGRATION.md, examples, and tutorials.
+
+## Code Standards
+
+- **Type hints** on all function signatures
+- **Docstrings** on all public classes and methods
+- **Tests** for all new functionality (target 90% coverage)
+- **Async-first**: all I/O operations must be async
+- **Protocol-based**: never import directly from external packages (Core, Capsule, Vault)
+- **Safety-first**: HIGH-risk operations always require human review
+
+## Running Tests
+
+```bash
+make test          # Run full test suite with coverage
+make lint          # Run ruff linter
+make typecheck     # Run mypy type checker
+make test-all      # All of the above
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch from `main`
+3. Write tests alongside your code
+4. Ensure `make test-all` passes
+5. Submit a pull request
+
+## Security
+
+If you discover a security vulnerability, please report it privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

qp_conductor-0.1.0/INTEGRATION.md

@@ -0,0 +1,161 @@
+# qp-conductor Integration Guide
+
+> How Conductor integrates with every other repos/ package.
+
+---
+
+## Protocol-Based Architecture
+
+Conductor uses **structural subtyping (Protocols)** for all external dependencies. This means:
+- Conductor never `import`s from Core, Capsule, or Vault directly
+- Any object matching the Protocol interface works (duck typing)
+- Consumers wire up the real implementations at initialization
+
+```python
+from qp_conductor.protocols import (
+    LLMProtocol,        # Core's CapabilityRouter.chat()
+    AgentProtocol,       # Core's Agent
+    AgentRegistryProtocol,  # Agent lookup by type
+    CapsuleChainProtocol,   # qp-capsule's CapsuleChain.add()
+    SealProtocol,        # qp-capsule's Seal
+    KillSwitchProtocol,  # Core's KillSwitch
+    VaultProtocol,       # qp-vault's AsyncVault
+)
+```
+
+---
+
+## Integration Map
+
+### quantumpipes (Core) v1.1.0
+
+| Conductor Needs | Core Provides | Protocol | How to Wire |
+|-----------------|---------------|----------|-------------|
+| LLM inference | `CapabilityRouter.chat()` | `LLMProtocol` | Pass router instance |
+| Agent execution | `Agent.execute(task)` -> `LoopResult` | `AgentProtocol` | Pass Agent instance |
+| Agent stop | `Agent.stop()` | `AgentProtocol` | Built into protocol |
+| Kill switch check | `KillSwitch.check()` / `.check_raise()` | `KillSwitchProtocol` | `KillSwitch.get()` singleton |
+| Joy scoring | `JoyCalculator.compute()` | Direct import (optional) | Optional dependency |
+| Novelty detection | `NoveltyCalculator` | Direct import (optional) | Optional dependency |
+
+**Key API notes:**
+- `Agent.execute(task: str, session_id: str | None)` returns `LoopResult` (success, result, error, capsules, iterations, duration_ms)
+- `CapabilityRouter.chat(messages: list[dict], **kwargs)` returns `dict` with `content`, `model`, `usage`
+- `KillSwitch` is a singleton: `KillSwitch.get()`. Once killed, cannot be undone.
+
+### qp-capsule v1.5.3
+
+| Conductor Needs | Capsule Provides | Protocol | How to Wire |
+|-----------------|------------------|----------|-------------|
+| Chain capsules | `CapsuleChain.add(capsule)` | `CapsuleChainProtocol` | Pass chain instance |
+| Seal capsules | `Seal.seal(capsule)` / `.verify(capsule)` | `SealProtocol` | Pass seal instance |
+| Create capsules | `Capsule(type=..., trigger=..., ...)` | Direct dataclass | Import Capsule from qp-capsule |
+
+**Key API notes:**
+- `Capsule` has 6 sections: TriggerSection, ContextSection, ReasoningSection, AuthoritySection, ExecutionSection, OutcomeSection
+- `CapsuleType` enum: AGENT, TOOL, SYSTEM, KILL, WORKFLOW, CHAT, VAULT, AUTH
+- `Seal` requires filesystem access to `~/.quantumpipes/key` for Ed25519 keys
+- Chain links `previous_hash` and `sequence` automatically
+
+### qp-vault v1.2.0
+
+| Conductor Needs | Vault Provides | Protocol | How to Wire |
+|-----------------|---------------|----------|-------------|
+| Store memories | `AsyncVault.add(source, name, trust_tier, layer, metadata)` | `VaultProtocol` | Pass vault instance |
+| Search memories | `AsyncVault.search(query, tenant_id, top_k)` | `VaultProtocol` | Pass vault instance |
+| Get content | `AsyncVault.get_content(resource_id)` | `VaultProtocol` | Pass vault instance |
+
+**Key API notes:**
+- `search()` returns `list[SearchResult]` with trust-weighted relevance scores
+- `add()` accepts `trust_tier` (CANONICAL, WORKING, EPHEMERAL, ARCHIVED) and `layer` (OPERATIONAL, STRATEGIC, COMPLIANCE)
+- Organizational memories should use `trust_tier=WORKING`, `layer=STRATEGIC`
+
+### Hub v1.0.1
+
+Hub renders Conductor data but does NOT depend on Conductor directly. Hub talks to Core's FastAPI, which uses Conductor internally.
+
+| Hub Feature | What It Renders | Data Source |
+|-------------|----------------|-------------|
+| Priority Inbox | Pending review tasks sorted by risk/confidence/age | `TaskService.get_pending_review_tasks()` |
+| Goal Progress | Goal status, progress bars, outcome achievement | `Goal.to_dict()` |
+| Workflow Visualization | Phase execution timeline | `Workflow.to_dict()` |
+| Capsule Chain | Audit trail of orchestration decisions | Capsule viewer (existing) |
+| Autonomy Indicator | Current autonomy level with reasoning | `AutonomyDecision.to_dict()` |
+
+### Conduit v0.1.0
+
+Conductor does not integrate with Conduit directly. Conduit manages infrastructure (DNS, TLS, routing). If Conductor schedules a deployment workflow, the Deployer agent would interact with Conduit via tools.
+
+### Tunnel v0.1.0
+
+Conductor does not integrate with Tunnel directly. Tunnel provides VPN access. Conductor operates within the network that Tunnel secures.
+
+---
+
+## Wiring Example
+
+```python
+from quantumpipes import Agent, AgentConfig, KillSwitch
+from quantumpipes.intelligence import CapabilityRouter
+from qp_capsule import Capsule, CapsuleChain, CapsuleStorage, Seal
+from qp_vault import AsyncVault
+
+from qp_conductor import Goal, GoalStateMachine
+from qp_conductor.capabilities.registry_loader import CapabilityRegistry
+from qp_conductor.core.capability_composer import CapabilityComposer
+from qp_conductor.core.autonomy_calculator import AutonomyCalculator
+from qp_conductor.core.goal_analyzer import GoalAnalyzer
+from qp_conductor.core.checkpoint_manager import CheckpointManager
+
+# Initialize external dependencies
+router = CapabilityRouter(providers={...})
+agent = Agent(config=AgentConfig(model="llama3.2:3b"))
+kill_switch = KillSwitch.get()
+capsule_chain = CapsuleChain(CapsuleStorage("conductor.db"))
+seal = Seal()
+vault = await AsyncVault.create(path="./vault")
+
+# Initialize Conductor components with protocols
+registry = CapabilityRegistry()
+analyzer = GoalAnalyzer(
+    capability_registry=registry,
+    llm_service=router,        # Satisfies LLMProtocol
+)
+composer = CapabilityComposer(capability_registry=registry)
+calculator = AutonomyCalculator(capability_registry=registry)
+checkpoints = CheckpointManager()
+
+# Create and analyze a goal
+goal = Goal(description="Prepare Q4 tax filings")
+sm = GoalStateMachine(goal)
+sm.start_planning()
+
+analysis = await analyzer.analyze(goal.description, goal_id=str(goal.id))
+plan = await composer.compose(analysis)
+decision = calculator.calculate(analysis=analysis, plan=plan)
+
+print(f"Plan: {len(plan.steps)} steps, autonomy L{decision.numeric_level}")
+```
+
+---
+
+## Future Phase Integration Notes
+
+### Phase 3 (Goal/Task Services)
+- GoalService needs LLMProtocol for intent extraction
+- TaskService needs no external deps (pure state machine + storage)
+- AutoApproveService needs no external deps
+
+### Phase 4 (Adaptation Engine)
+- SignalCapture needs CapsuleChainProtocol for adapter audit
+- AdapterStore needs SealProtocol for Ed25519 signing
+- SafetyGates needs no external deps (pure validation)
+
+### Phase 5 (Drift + Memory + Scheduler)
+- DriftDetector needs LLMProtocol for embedding generation (or a separate EmbeddingProtocol)
+- OrganizationalMemory needs VaultProtocol for storage and search
+- Scheduler needs no external deps (SQLite built-in)
+
+### Phase 6 (CLI + FastAPI)
+- CLI wraps all services
+- FastAPI module uses same Protocols for dependency injection