Metadata-Version: 2.4
Name: ortim
Version: 0.9.4
Summary: Ortim — agentic dev pipeline with deterministic architecture, audit, and gated execution
Author-email: "ortim.dev" <contact@ortim.dev>
License: FSL-1.1-Apache-2.0
Project-URL: Homepage, https://ortim.dev
Project-URL: Documentation, https://ortim.dev/docs
Project-URL: Source, https://github.com/orhanurullah/ortim
Project-URL: Issues, https://github.com/orhanurullah/ortim/issues
Project-URL: Changelog, https://github.com/orhanurullah/ortim/blob/main/CHANGELOG.md
Keywords: llm,agents,code-generation,ai-pipeline,orchestration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.commercial
License-File: NOTICE
Requires-Dist: anthropic>=0.39.0
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pathspec>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# 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.

[![PyPI](https://img.shields.io/pypi/v/ortim.svg)](https://pypi.org/project/ortim/)
[![Python](https://img.shields.io/pypi/pyversions/ortim.svg)](https://pypi.org/project/ortim/)
[![License: FSL-1.1-Apache-2.0](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue.svg)](LICENSE)

```bash
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](docs/why-ortim.md)** — what the structural differences buy you, with a side-by-side cost/quality comparison against vanilla LLM coding.

---

## Quick start

```bash
# 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:

```bash
ortim demo
```

→ Full tutorial: **[docs/tutorial/getting-started.md](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](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:

```bash
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):

```ini
# .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:

```bash
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

```bash
# 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](LICENSE) — 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](LICENSE.commercial). Currently a stub; first beta enterprise pilot is being scoped.

---

## More documentation

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

---

## Development

```bash
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](https://github.com/orhanurullah/ortim/issues)
- License questions or commercial inquiries: `contact@ortim.dev`
