ortim 0.9.4

Ortim — agentic dev pipeline with deterministic architecture, audit, and gated execution

Ortim

A disciplined, multi-agent AI software factory. Turn a one-paragraph brief into working, reviewed, audit-trailed code — without surrendering control to the LLM.

pip install ortim

Requires Python ≥ 3.11. After install, run ortim config init to pick a provider (DeepSeek / Anthropic / local Ollama) and store credentials — no .env setup needed.

---

Why this exists

Coding with a bare LLM ("write me X") fails the same way every time:

• It re-implements code you already have because it forgot.
• It tries a fix, the fix breaks something else, three turns later you've lost the original intent.
• It quietly invents library names. It silently skips tests. It tells you it ran the migration when it didn't.
• It picks microservices for a CRUD app, then asks for your approval on the same decision four times in a single session.
• You can't audit any of it. There is no record of why a choice was made — only the final diff.

Ortim treats AI coding as a production-engineering problem, not a prompting problem. A deterministic state machine, two mandatory human gates, a hash-chained audit log, scope-locked task DAGs, and module-boundary sandboxes turn an unreliable LLM into a reviewable software pipeline.

→ docs/why-ortim.md — what the structural differences buy you, with a side-by-side cost/quality comparison against vanilla LLM coding.

---

Quick start

# 1) Go to a project directory (greenfield or brownfield).
mkdir ~/dev/task-tracker && cd ~/dev/task-tracker

# 2) Initialize. Ortim creates a .ortim/ namespace here and auto-detects
#    whether the directory is a fresh start or an existing codebase.
ortim init "A small task tracker CLI in Python with SQLite, single user, local only."

# 3) Let Babel + Analyst draft a PRD from the brief.
ortim run

# 4) Review the PRD and approve gate G1.
ortim show --artifact prd
ortim advance prd_approved

# 5) Architect produces an RFC (tier, stack, modules, risks).
ortim run

# 6) Review the RFC and approve gate G2.
ortim show --artifact rfc
ortim advance rfc_approved

# 7) Orchestrator generates the task DAG; Worker + Reviewer execute it.
ortim run                    # DAG generation
ortim run-all --phase 1      # execute MVP tasks

# Observability
ortim status                 # state + history
ortim retro                  # token + USD cost rollup
ortim drift-check            # RFC ↔ DAG ↔ status integrity

Every command discovers the workspace from cwd (project mode, 0.9+). Run them inside the project directory, or use --project / -p <id> from anywhere. ortim ls lists every known workspace.

For a quick end-to-end walkthrough with no input:

ortim demo

→ Full tutorial: docs/tutorial/getting-started.md (~15 minutes from install to a finished project).

---

What it actually does

Pain point	Ortim's structural answer
Endless error loops	3-attempt budget per task with reviewer feedback injected into each retry; failures escalate to AWAITING_HITL instead of spinning forever.
Silent test/hook skips	Reviewer chain (Code → Security → Test → Perf) treats unverifiable differently from pass; a missing test runner trips a distinct mode, not a false approval.
Architecture drift	The Architect agent does not pick a tier — an LLM extracts characteristics from the PRD, a deterministic scorer (12 canonical tiers across web/mobile/desktop) picks the architecture.
Scope creep	PRD locks MVP vs deferred features (Phase 1 / Phase 2+). Orchestrator emits zero tasks for Phase 2; they wait for ortim extend in a later cycle.
Module-boundary leaks	Each task has a module_scope; the sandbox rejects writes outside it. Cross-module use is via imports, not file creation.
Hallucinated dependencies	Bootstrap installs only declared key_libraries; an Architect validator (item 40) catches phantom libs in §4 of the RFC before they poison the DAG.
Token waste in non-English flows	Babel translates a Turkish/etc. brief into a structured intent before any expensive call; "premium" models are reserved for Architect + Security Reviewer.
No audit trail	Every LLM call, state transition, gate decision, and hook output lands in a hash-chained JSONL (.ortim/audit.jsonl). ortim audit-verify detects tampering.
Approval fatigue	Two mandatory gates (G1 = PRD, G2 = RFC). Five conditional gates fire only when relevant (schema, external API, security finding ≥ medium, deploy, budget cap).
AI coding on existing codebases	ortim init in a directory with package.json / pyproject.toml / Cargo.toml / go.mod / pubspec.yaml auto-enters brownfield mode: import-graph extraction, scope-aware task generation.

---

Architecture at a glance

[brief]
   ↓  Babel       (any language → structured intent, token-frugal)
intent.json
   ↓  Analyst chain (IntentAnalyst + StackAnalyst + PRDAnalyst; M2 conversational)
PRD.md + stack.json
   ↓  G1 — human approval (mandatory)
   ↓  Architect    (Call 1: scorer inputs; Call 2: RFC with two-tier module breakdown)
RFC.md + golden_path_inputs.json
   ↓  G2 — human approval (mandatory)
   ↓  Orchestrator (TaskDAG; Hard Rule 13: DAG ⊂ RFC modules)
task_dag.json + .ortim/tasks/T-NNN.md
   ↓  Worker × N  (FILE_BLOCK output, git branch per task)
   ↓  Reviewer chain (Code → Security → Test → Perf; rubric-shaped verdicts)
   ↓  Hooks       (pre_commit / pre_deploy)
DONE

Two invariants worth naming:

• The LLM never picks a tier. Architect Call 1 emits parameters; ortim/architecture/golden_paths.py does rule-based scoring (12 tiers: T0–T6 web, M0–M2 mobile, D0–D1 desktop).
• DAGs are runtime-validated. If the LLM emits a cycle, a missing dependency, or an off-RFC module, validators retry up to 3× then escalate to AWAITING_HITL.

Full specification: Ortim_Architecture.md (currently mixed TR/EN; full English translation tracked under Phase 4).

---

Multi-provider routing

Ortim routes each agent role to its own LLM provider. Most production setups use DeepSeek-only for budget reasons; route Architect and Security Reviewer to Anthropic when judgement matters. No API key at hand? Use Ollama locally.

Recommended path — ortim config init (0.9.4+). Interactive wizard writes ~/.ortim/config.toml. No .env required, works from any directory:

ortim config init                # pick provider → model → key, once
ortim config show                # verify what's resolved, with source per field
ortim config set-role architect --provider anthropic   # role override

Or set env vars (still supported — ~/.ortim/config.toml only fills gaps, never overrides):

# .env — minimal
DEEPSEEK_API_KEY=sk-...

# Hybrid — premium reasoning where it pays off
ANTHROPIC_API_KEY=sk-ant-...
ARCHITECT_PROVIDER=anthropic
SECURITY_REVIEWER_PROVIDER=anthropic

Per-invocation override — highest precedence:

ortim run --provider ollama --model qwen2.5-coder:7b
ortim demo --provider ollama          # try the demo with zero API keys

Resolution order: --provider flag → shell / .env env var → ~/.ortim/config.toml → hardcoded default.

Approximate costs on observed proof-point runs (TR brief, 6–8 tasks, 80 %+ first-attempt approval):

• DeepSeek-only: $0.02–0.05 per planning chain, $0.02–0.04 per task execution.
• Hybrid (Architect + SecRev on Anthropic): $0.05–0.10 planning, $0.04–0.08 per task.
• Ollama-only: $0.00 (local; throughput depends on hardware).

Supported providers: anthropic, deepseek, ollama (local), any OpenAI-compatible endpoint.

---

CLI cheatsheet

# Health + setup
ortim doctor
ortim config init                  # one-time provider/key wizard
ortim config show                  # what's active + where it came from

# New project (project mode — cwd-aware)
mkdir ~/dev/cool && cd ~/dev/cool
ortim init "<brief>"
ortim run                          # Babel + Analyst → MVP_SCOPE_LOCKING
ortim scope --lock                 # accept default phase split + advance to G1
ortim show --artifact prd
ortim advance prd_approved
ortim run                          # Architect → RFC_AWAITING_APPROVAL
ortim advance rfc_approved
ortim run                          # Orchestrator → tasks_ready
ortim run-all --phase 1            # Worker × N

# Observability
ortim status
ortim tasks
ortim retro
ortim drift-check
ortim show --artifact rfc

# Iteration
ortim refine "<feedback>"          # dialog-mode refine
ortim extend "<new feature>"       # DONE project → delta cycle

# Workspace management (from anywhere)
ortim ls                           # all known workspaces; '*' = active
ortim use <id|name>                # set active pointer (registry-backed)
ortim status -p <id>               # target a specific workspace
ortim workspace archive <id>
ortim workspace cleanup --older-than 30 --archived-only --yes

Full reference: ortim --help.

---

State machine

intake → babel → intake_dialog → stack_dialog → prd_dialog → prd_drafting
       → prd_awaiting_approval → prd_approved
                 ↑ G1 (mandatory)
       → rfc_drafting → rfc_awaiting_approval → rfc_approved
                              ↑ G2 (mandatory)
       → tasks_generating → tasks_ready → executing → done

Conditional gates fire mid-execution: G3 schema/migration, G4 external API call, G5 security severity ≥ medium, G6 deploy, G7 budget cap. Each pauses the task in AWAITING_HITL; ortim advance <state>_approved resumes.

---

License

• Core (this repo): FSL-1.1-Apache-2.0 — Functional Source License, automatically converts to Apache-2.0 after two years. Production use is free; building a competing service against the same APIs is the only thing restricted, and only for two years.
• Enterprise (enterprise/ — multi-tenant orchestrator, SSO, audit retention, SLA): Commercial. Currently a stub; first beta enterprise pilot is being scoped.

---

More documentation

• Why Ortim — value framing, comparison vs vanilla LLM coding, when to use this vs Cursor/Aider/Claude Code.
• Getting started — ~15-minute end-to-end tutorial (greenfield + brownfield).
• Failure recovery runbook — what to do when a task lands in AWAITING_HITL, budget gate trips, schema migration fails, etc.
• Architecture spec — full master specification (TR/EN mixed; English-only revision is in flight).
• Golden paths — reference docs for each of the 12 tiers.
• Skill authoring guide — how to inject project-specific patterns into Worker/Reviewer prompts.
• Changelog.
• Türkçe arşiv: docs/tr/ — original Turkish-language tutorial and runbook (kept in sync best-effort; the English version is canonical).

---

Development

git clone https://github.com/orhanurullah/ortim.git
cd ortim
python -m venv .venv
.venv/Scripts/activate            # Windows
# source .venv/bin/activate       # macOS/Linux
pip install -e .[dev]

ruff check .
mypy ortim
pytest

735 unit + integration tests, 22 deselected end-to-end baselines (real-LLM fixtures, opt-in with -m e2e). Full suite runs in ~37 seconds.

---

Issues + contact

• Issues: github.com/orhanurullah/ortim/issues
• License questions or commercial inquiries: [e-mail]