karajan-cli 0.1.0__tar.gz

karajan_cli-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: karajan-cli
+Version: 0.1.0
+Summary: An AI agent harness for software engineers. Built on opencode + LangGraph.
+License-Expression: MIT
+Keywords: ai,agents,langgraph,opencode,workflow,engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: litellm>=1.40.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tomli-w>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+
+# Karajan
+
+**An AI agent harness for software engineers.**
+Built on [opencode](https://opencode.ai) + [LangGraph](https://langchain-ai.github.io/langgraph/).
+
+> Named after Herbert von Karajan — the conductor who coordinates every musician
+> without playing a single instrument himself.
+
+```
+Research → Architect → [YOU] → PRD → [YOU] → Dev → Reviewer → QA ⟲ → [YOU] → Done
+```
+
+---
+
+## Install
+
+```bash
+pip install karajan
+```
+
+Or from source (development):
+
+```bash
+git clone https://github.com/TU_USER/karajan
+cd karajan
+pip install -e .
+```
+
+## Quick start
+
+```bash
+# 1. Go to your project
+cd ~/projects/my-app
+
+# 2. Initialize karajan
+karajan init --profile solo   # or: --profile team
+
+# 3. Fill in .agent/CONTEXT.md with your project details
+# 4. Copy .env.karajan.example to .env and add your API keys
+
+# 5. Run a workflow
+karajan task QR-42
+```
+
+---
+
+## Commands
+
+```bash
+karajan init [--profile solo|team]   # Initialize in current project
+karajan task <ticket>                # Run full workflow
+karajan status [ticket]              # Show active workflows
+karajan models [--provider X]        # List available models
+karajan profiles                     # List profiles and their defaults
+karajan config --show                # Show current project config
+karajan version                      # Show version
+```
+
+## Model switching (per run)
+
+```bash
+# Use profile defaults
+karajan task QR-42
+
+# Override reasoning model (Research, Architect, PRD, Reviewer)
+karajan task QR-42 --model anthropic/claude-sonnet-4-20250514
+
+# Override dev model (what opencode uses internally)
+karajan task QR-42 --dev-model ollama/qwen2.5-coder:14b
+
+# Override all three independently
+karajan task QR-42 \
+  --model google/gemini-2.0-flash \
+  --dev-model ollama/qwen2.5-coder:14b \
+  --qa-model ollama/qwen2.5:7b
+
+# Resume interrupted workflow
+karajan task QR-42 --from-stage dev
+```
+
+---
+
+## Profiles
+
+Profiles live in `karajan/profiles/` and ship with the package.
+No separate repos needed — everything in one place.
+
+```bash
+karajan profiles   # see all profiles and their defaults
+```
+
+| | `solo` | `team` |
+|--|--|--|
+| Use case | Personal side-projects | Company engineering team |
+| Tracker | GitHub Issues + Projects | Jira |
+| Dev CLI | opencode | Claude Code |
+| Reasoning model | Gemini Flash | Gemini Flash |
+| Dev model | Qwen2.5-Coder 14B (local) | Claude Sonnet |
+| QA model | Qwen2.5 7B (local) | Claude Haiku |
+| Observability | Local logs | Langfuse |
+
+---
+
+## Workflow
+
+```
+karajan task QR-42
+  → Fetches ticket (GitHub Issues or Jira)
+  → Research agent    — understands context and risks
+  → Architect agent   — designs technical plan
+  → [YOU review plan]                            ← HITL #1
+  → PRD agent         — documents the feature
+  → [YOU review PRD]                             ← HITL #2
+  → Dev agent         — opencode/Claude Code implements
+  → Reviewer agent    — code review
+  → QA agent          — validates, auto-retries Dev if fails (max 2x)
+  → PR opened in GitHub
+  → [YOU review PR]                              ← HITL #3
+  → Done
+```
+
+---
+
+## What karajan init creates
+
+```
+your-project/
+  .agent/
+    CONTEXT.md       ← what this project is
+    STACK.md         ← technologies and versions
+    DECISIONS.md     ← architecture decisions (ADRs)
+    CONSTRAINTS.md   ← what agents can't touch
+    TASKS.md         ← current work state
+    AGENTS.md        ← agent instructions
+  .agents/
+    architect.md     ← opencode architect agent definition
+    researcher.md    ← opencode research agent definition
+    reviewer.md      ← opencode reviewer agent definition
+    qa.md            ← opencode QA agent definition
+  .karajan/
+    config.toml      ← project-level config (profile, model overrides)
+  .env.karajan.example
+```
+
+---
+
+## Structure
+
+```
+karajan/
+  karajan/
+    cli.py              ← entry point (karajan command)
+    config.py           ← config loader with full hierarchy
+    graph.py            ← LangGraph orchestrator
+    profiles/
+      solo.toml         ← solo profile defaults
+      team.toml         ← team profile defaults
+    nodes/
+      research.py       ← Research node
+      architect.py      ← Architect node
+      prd.py            ← PRD node
+      dev.py            ← Dev node (opencode / Claude Code)
+      reviewer.py       ← Reviewer node
+      qa.py             ← QA node
+      hitl.py           ← Human-in-the-loop node
+    agents/
+      architect.md      ← opencode agent definition
+      researcher.md     ← opencode agent definition
+      reviewer.md       ← opencode agent definition
+      qa.md             ← opencode agent definition
+    commands/
+      init.py           ← karajan init
+      task.py           ← karajan task
+      status.py         ← karajan status
+      models.py         ← karajan models
+      config.py         ← karajan config
+    scripts/
+      tracker.py        ← GitHub Issues + Jira unified
+      github.py         ← PR creation
+  pyproject.toml        ← pip install config
+  README.md
+```
+
+---
+
+## Config hierarchy
+
+```
+CLI flags (--model, --dev-model, --profile)
+  > environment variables (KARAJAN_MODEL_*, GEMINI_API_KEY, etc.)
+    > .karajan/config.toml (per project)
+      > karajan/profiles/<profile>.toml (package defaults)
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [opencode](https://opencode.ai) (`npm install -g opencode`) — solo profile
+- [Claude Code](https://claude.ai/code) — team profile
+- Ollama (optional, for local models): https://ollama.com
+
+---
+
+## License
+
+MIT

karajan_cli-0.1.0/README.md

@@ -0,0 +1,208 @@
+# Karajan
+
+**An AI agent harness for software engineers.**
+Built on [opencode](https://opencode.ai) + [LangGraph](https://langchain-ai.github.io/langgraph/).
+
+> Named after Herbert von Karajan — the conductor who coordinates every musician
+> without playing a single instrument himself.
+
+```
+Research → Architect → [YOU] → PRD → [YOU] → Dev → Reviewer → QA ⟲ → [YOU] → Done
+```
+
+---
+
+## Install
+
+```bash
+pip install karajan
+```
+
+Or from source (development):
+
+```bash
+git clone https://github.com/TU_USER/karajan
+cd karajan
+pip install -e .
+```
+
+## Quick start
+
+```bash
+# 1. Go to your project
+cd ~/projects/my-app
+
+# 2. Initialize karajan
+karajan init --profile solo   # or: --profile team
+
+# 3. Fill in .agent/CONTEXT.md with your project details
+# 4. Copy .env.karajan.example to .env and add your API keys
+
+# 5. Run a workflow
+karajan task QR-42
+```
+
+---
+
+## Commands
+
+```bash
+karajan init [--profile solo|team]   # Initialize in current project
+karajan task <ticket>                # Run full workflow
+karajan status [ticket]              # Show active workflows
+karajan models [--provider X]        # List available models
+karajan profiles                     # List profiles and their defaults
+karajan config --show                # Show current project config
+karajan version                      # Show version
+```
+
+## Model switching (per run)
+
+```bash
+# Use profile defaults
+karajan task QR-42
+
+# Override reasoning model (Research, Architect, PRD, Reviewer)
+karajan task QR-42 --model anthropic/claude-sonnet-4-20250514
+
+# Override dev model (what opencode uses internally)
+karajan task QR-42 --dev-model ollama/qwen2.5-coder:14b
+
+# Override all three independently
+karajan task QR-42 \
+  --model google/gemini-2.0-flash \
+  --dev-model ollama/qwen2.5-coder:14b \
+  --qa-model ollama/qwen2.5:7b
+
+# Resume interrupted workflow
+karajan task QR-42 --from-stage dev
+```
+
+---
+
+## Profiles
+
+Profiles live in `karajan/profiles/` and ship with the package.
+No separate repos needed — everything in one place.
+
+```bash
+karajan profiles   # see all profiles and their defaults
+```
+
+| | `solo` | `team` |
+|--|--|--|
+| Use case | Personal side-projects | Company engineering team |
+| Tracker | GitHub Issues + Projects | Jira |
+| Dev CLI | opencode | Claude Code |
+| Reasoning model | Gemini Flash | Gemini Flash |
+| Dev model | Qwen2.5-Coder 14B (local) | Claude Sonnet |
+| QA model | Qwen2.5 7B (local) | Claude Haiku |
+| Observability | Local logs | Langfuse |
+
+---
+
+## Workflow
+
+```
+karajan task QR-42
+  → Fetches ticket (GitHub Issues or Jira)
+  → Research agent    — understands context and risks
+  → Architect agent   — designs technical plan
+  → [YOU review plan]                            ← HITL #1
+  → PRD agent         — documents the feature
+  → [YOU review PRD]                             ← HITL #2
+  → Dev agent         — opencode/Claude Code implements
+  → Reviewer agent    — code review
+  → QA agent          — validates, auto-retries Dev if fails (max 2x)
+  → PR opened in GitHub
+  → [YOU review PR]                              ← HITL #3
+  → Done
+```
+
+---
+
+## What karajan init creates
+
+```
+your-project/
+  .agent/
+    CONTEXT.md       ← what this project is
+    STACK.md         ← technologies and versions
+    DECISIONS.md     ← architecture decisions (ADRs)
+    CONSTRAINTS.md   ← what agents can't touch
+    TASKS.md         ← current work state
+    AGENTS.md        ← agent instructions
+  .agents/
+    architect.md     ← opencode architect agent definition
+    researcher.md    ← opencode research agent definition
+    reviewer.md      ← opencode reviewer agent definition
+    qa.md            ← opencode QA agent definition
+  .karajan/
+    config.toml      ← project-level config (profile, model overrides)
+  .env.karajan.example
+```
+
+---
+
+## Structure
+
+```
+karajan/
+  karajan/
+    cli.py              ← entry point (karajan command)
+    config.py           ← config loader with full hierarchy
+    graph.py            ← LangGraph orchestrator
+    profiles/
+      solo.toml         ← solo profile defaults
+      team.toml         ← team profile defaults
+    nodes/
+      research.py       ← Research node
+      architect.py      ← Architect node
+      prd.py            ← PRD node
+      dev.py            ← Dev node (opencode / Claude Code)
+      reviewer.py       ← Reviewer node
+      qa.py             ← QA node
+      hitl.py           ← Human-in-the-loop node
+    agents/
+      architect.md      ← opencode agent definition
+      researcher.md     ← opencode agent definition
+      reviewer.md       ← opencode agent definition
+      qa.md             ← opencode agent definition
+    commands/
+      init.py           ← karajan init
+      task.py           ← karajan task
+      status.py         ← karajan status
+      models.py         ← karajan models
+      config.py         ← karajan config
+    scripts/
+      tracker.py        ← GitHub Issues + Jira unified
+      github.py         ← PR creation
+  pyproject.toml        ← pip install config
+  README.md
+```
+
+---
+
+## Config hierarchy
+
+```
+CLI flags (--model, --dev-model, --profile)
+  > environment variables (KARAJAN_MODEL_*, GEMINI_API_KEY, etc.)
+    > .karajan/config.toml (per project)
+      > karajan/profiles/<profile>.toml (package defaults)
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [opencode](https://opencode.ai) (`npm install -g opencode`) — solo profile
+- [Claude Code](https://claude.ai/code) — team profile
+- Ollama (optional, for local models): https://ollama.com
+
+---
+
+## License
+
+MIT

karajan_cli-0.1.0/karajan/__init__.py

@@ -0,0 +1,4 @@
+"""Karajan package."""
+
+__version__ = "0.1.0"
+

karajan_cli-0.1.0/karajan/agents/architect.md

@@ -0,0 +1,23 @@
+---
+name: architect
+description: Technical planning agent. Designs solutions, writes ADRs, and produces implementation specs. Use before any coding task.
+model: google/gemini-2.0-flash
+temperature: 0.3
+mode: primary
+tools:
+  - read
+  - write
+permissions:
+  allow:
+    - read: "**"
+    - write: ".agent/DECISIONS.md"
+    - write: ".workflow-state/**"
+  deny:
+    - write: "src/**"
+    - write: "*.ts"
+    - write: "*.py"
+    - bash: "*"
+---
+
+You are a Software Architect with deep experience in TypeScript, Node.js, event-driven systems, and complex integrations.
+

karajan_cli-0.1.0/karajan/agents/qa.md

@@ -0,0 +1,13 @@
+---
+name: qa
+description: QA validation agent. Runs tests, verifies acceptance criteria, surfaces edge cases.
+model: ollama/qwen2.5:7b
+temperature: 0.1
+mode: primary
+tools:
+  - read
+  - bash
+---
+
+You are a QA Engineer.
+

karajan_cli-0.1.0/karajan/agents/researcher.md

@@ -0,0 +1,13 @@
+---
+name: researcher
+description: Technical research agent. Gathers context, finds patterns, identifies risks before design begins. Always runs before architect.
+model: google/gemini-2.0-flash
+temperature: 0.2
+mode: primary
+tools:
+  - read
+  - web_search
+---
+
+You are a Technical Research Specialist.
+

karajan_cli-0.1.0/karajan/agents/reviewer.md

@@ -0,0 +1,13 @@
+---
+name: reviewer
+description: Code review agent. Reviews diffs for correctness, conventions, and quality.
+model: google/gemini-2.0-flash
+temperature: 0.1
+mode: primary
+tools:
+  - read
+  - bash
+---
+
+You are a Tech Lead doing code review.
+

karajan_cli-0.1.0/karajan/cli.py

@@ -0,0 +1,102 @@
+"""Karajan CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Sequence
+
+from . import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="karajan",
+        description="An AI agent harness for software engineers. Built on opencode + LangGraph.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="Initialize in current project")
+    init_parser.add_argument("--profile", "-p", choices=["solo", "team"], default=None)
+    init_parser.add_argument("--force", "-f", action="store_true")
+
+    task_parser = subparsers.add_parser("task", help="Run full workflow")
+    task_parser.add_argument("ticket")
+    task_parser.add_argument("--model", "-m", default=None)
+    task_parser.add_argument("--dev-model", default=None)
+    task_parser.add_argument("--qa-model", default=None)
+    task_parser.add_argument("--from-stage", default=None)
+    task_parser.add_argument("--dry-run", action="store_true")
+
+    status_parser = subparsers.add_parser("status", help="Show active workflows")
+    status_parser.add_argument("ticket", nargs="?", default=None)
+
+    models_parser = subparsers.add_parser("models", help="List available models")
+    models_parser.add_argument("--provider", default=None)
+
+    config_parser = subparsers.add_parser("config", help="Show current project config")
+    config_parser.add_argument("--show", action="store_true")
+    config_parser.add_argument("--set", dest="set_key", default=None)
+
+    subparsers.add_parser("version", help="Show version")
+    subparsers.add_parser("profiles", help="List profiles and defaults")
+
+    logs_parser = subparsers.add_parser("logs", help="Show run logs and cost summary")
+    logs_parser.add_argument("ticket", nargs="?", default=None)
+    logs_parser.add_argument("--tail", "-n", type=int, default=20)
+    logs_parser.add_argument("--summary", "-s", action="store_true")
+
+    return parser
+
+
+def app(argv: Sequence[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        raise SystemExit(0)
+
+    if args.command == "init":
+        from .commands.init import run_init
+
+        run_init(profile=args.profile, force=args.force)
+    elif args.command == "task":
+        from .commands.task import run_task
+
+        run_task(
+            ticket=args.ticket,
+            model=args.model,
+            dev_model=args.dev_model,
+            qa_model=args.qa_model,
+            from_stage=args.from_stage,
+            dry_run=args.dry_run,
+        )
+    elif args.command == "status":
+        from .commands.status import run_status
+
+        run_status(ticket=args.ticket)
+    elif args.command == "models":
+        from .commands.models import run_models
+
+        run_models(provider=args.provider)
+    elif args.command == "config":
+        from .commands.config import run_config
+
+        run_config(show=args.show, set_key=args.set_key)
+    elif args.command == "version":
+        print(f"karajan v{__version__}")
+    elif args.command == "profiles":
+        from .commands.profiles import run_profiles
+
+        run_profiles()
+    elif args.command == "logs":
+        from .commands.logs import run_logs
+
+        run_logs(ticket=args.ticket, tail=args.tail, summary=args.summary)
+    else:
+        parser.error(f"Unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    app()
+

karajan_cli-0.1.0/karajan/commands/__init__.py

@@ -0,0 +1,2 @@
+"""Karajan command implementations."""
+

karajan_cli-0.1.0/karajan/commands/config.py

@@ -0,0 +1,89 @@
+"""Show or update Karajan config."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from ..config import dump_config_toml, load_config
+
+
+def run_config(show: bool = False, set_key: str = None):
+    config_path = Path(".karajan/config.toml")
+
+    if set_key:
+        _set_config_value(config_path, set_key)
+        return
+
+    if show or not config_path.exists():
+        config = load_config()
+        print(dump_config_toml(config.model_dump()))
+        return
+
+    print(config_path.read_text(encoding="utf-8"))
+
+
+def _set_config_value(config_path: Path, assignment: str):
+    if not config_path.exists():
+        print("No .karajan/config.toml found. Run karajan init first.")
+        raise SystemExit(1)
+    if "=" not in assignment:
+        print(f"Invalid config assignment: {assignment}")
+        raise SystemExit(1)
+    key, raw_value = (part.strip() for part in assignment.split("=", 1))
+    parts = [part for part in key.split(".") if part]
+    if not key or len(parts) != len(key.split(".")) or len(parts) > 2:
+        print(f"Invalid config path: {key}")
+        raise SystemExit(1)
+    with config_path.open("rb") as handle:
+        config = tomllib.load(handle)
+    target = _coerce_config_value(raw_value)
+    if len(parts) == 1:
+        if isinstance(config.get(parts[0]), dict):
+            print(f"Invalid config path: {key}")
+            raise SystemExit(1)
+        config[parts[0]] = target
+    else:
+        section, field = parts
+        section_data = config.get(section)
+        if section_data is None:
+            config[section] = {field: target}
+        elif isinstance(section_data, dict):
+            section_data[field] = target
+        else:
+            print(f"Invalid config path: {key}")
+            raise SystemExit(1)
+    _write_config(config_path, config)
+    print(f"✅ Set {key} = {_format_config_value(target)}")
+
+
+def _coerce_config_value(raw_value: str):
+    value = raw_value.strip()
+    lowered = value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    try:
+        return int(value)
+    except ValueError:
+        try:
+            return float(value)
+        except ValueError:
+            return value
+
+
+def _format_config_value(value) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _write_config(config_path: Path, config: dict):
+    try:
+        import tomli_w
+    except ModuleNotFoundError:
+        config_path.write_text(dump_config_toml(config), encoding="utf-8")
+        return
+    with config_path.open("wb") as handle:
+        tomli_w.dump(config, handle)