lohra 0.0.1__tar.gz

lohra-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcelus Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lohra-0.0.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: lohra
+Version: 0.0.1
+Summary: Lohra — self-improving AI agent runtime: CLI, orchestration envelope (--json), OpenAI-compatible server; optional desktop app
+License: MIT
+Project-URL: Homepage, https://github.com/marcelusfernandes/lohra
+Keywords: ai,agent,workflows,orchestration,self-improving,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.40.0; extra == "openai"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# Lohra
+
+**A self-improving AI agent runtime** — persistent memory, self-authored skills, and a
+declarative multi-agent workflow harness with Claude-Code-grade rigor. Runs headless:
+CLI, structured orchestration envelope, and an OpenAI-compatible server. No UI required.
+
+```bash
+pip install lohra          # Python 3.11–3.13
+lohra chat "hello"
+```
+
+## Four entry points, none of them a UI
+
+| Port | Command | For |
+|---|---|---|
+| Human CLI | `lohra chat` | you, in a terminal |
+| Orchestration envelope | `lohra chat --json` | other agents/scripts — one parseable JSON per turn (input/output/reasoning/tool_calls/usage) |
+| OpenAI-compatible API | `lohra serve` | any OpenAI client becomes a Lohra client |
+| WS/REST gateway | `lohra dashboard` | optional, only if a UI attaches |
+
+## What makes it interesting
+
+- **Dynamic workflows as inert data**: the agent authors a typed DAG (10 node types —
+  `agent`, `parallel`, `pipeline`, `loop_until_dry`, `verify`, `judge_panel`, `gate`,
+  `completeness_check`, `checkpoint`, nested `workflow`) that an interpreter runs.
+  No agent-authored code is ever executed; escape is inexpressible, not forbidden.
+- **Failure is never silent**: every failure path produces a fault with its cause;
+  run status is honest (`complete | degraded | failed | cancelled | paused`).
+- **Never pay twice**: content-addressed per-cell cache — a resumed run replays
+  completed work at zero token cost, across process restarts.
+- **Human in the loop**: `checkpoint` nodes pause a run until a person answers —
+  in another terminal, another process, another day. Durable state + single-winner leases.
+- **Cost control**: token budgets with soft pre-spawn gates, quota pauses with
+  auto-resume, per-node model/effort/provider routing, operator-owned model tiers.
+- **Self-improving**: persistent memory, self-authored skills, and a workflow library
+  that turns clean runs into reusable templates and bad runs into recorded priors.
+- **Leaf sandbox**: filesystem allowlist (ro/rw), egress allowlist, and taint tracking —
+  operator policy, never the spec.
+
+## Configuration
+
+State lives in `~/.lohra` (or per-workspace via `--profile`):
+`.env` (API keys) · `workflow_policy.json` (leaf fs/egress) · `workflow_tiers.json`
+(model tiers). Providers out of the box: Anthropic, OpenAI, OpenRouter, DeepSeek, Groq, Together,
+Gemini, Ollama — plus an opt-in subscription mode (see the ToS warning in `lohra auth`).
+
+MIT license. Alpha software — built and validated live, but young.

lohra-0.0.1/README.md

@@ -0,0 +1,47 @@
+# Lohra
+
+**A self-improving AI agent runtime** — persistent memory, self-authored skills, and a
+declarative multi-agent workflow harness with Claude-Code-grade rigor. Runs headless:
+CLI, structured orchestration envelope, and an OpenAI-compatible server. No UI required.
+
+```bash
+pip install lohra          # Python 3.11–3.13
+lohra chat "hello"
+```
+
+## Four entry points, none of them a UI
+
+| Port | Command | For |
+|---|---|---|
+| Human CLI | `lohra chat` | you, in a terminal |
+| Orchestration envelope | `lohra chat --json` | other agents/scripts — one parseable JSON per turn (input/output/reasoning/tool_calls/usage) |
+| OpenAI-compatible API | `lohra serve` | any OpenAI client becomes a Lohra client |
+| WS/REST gateway | `lohra dashboard` | optional, only if a UI attaches |
+
+## What makes it interesting
+
+- **Dynamic workflows as inert data**: the agent authors a typed DAG (10 node types —
+  `agent`, `parallel`, `pipeline`, `loop_until_dry`, `verify`, `judge_panel`, `gate`,
+  `completeness_check`, `checkpoint`, nested `workflow`) that an interpreter runs.
+  No agent-authored code is ever executed; escape is inexpressible, not forbidden.
+- **Failure is never silent**: every failure path produces a fault with its cause;
+  run status is honest (`complete | degraded | failed | cancelled | paused`).
+- **Never pay twice**: content-addressed per-cell cache — a resumed run replays
+  completed work at zero token cost, across process restarts.
+- **Human in the loop**: `checkpoint` nodes pause a run until a person answers —
+  in another terminal, another process, another day. Durable state + single-winner leases.
+- **Cost control**: token budgets with soft pre-spawn gates, quota pauses with
+  auto-resume, per-node model/effort/provider routing, operator-owned model tiers.
+- **Self-improving**: persistent memory, self-authored skills, and a workflow library
+  that turns clean runs into reusable templates and bad runs into recorded priors.
+- **Leaf sandbox**: filesystem allowlist (ro/rw), egress allowlist, and taint tracking —
+  operator policy, never the spec.
+
+## Configuration
+
+State lives in `~/.lohra` (or per-workspace via `--profile`):
+`.env` (API keys) · `workflow_policy.json` (leaf fs/egress) · `workflow_tiers.json`
+(model tiers). Providers out of the box: Anthropic, OpenAI, OpenRouter, DeepSeek, Groq, Together,
+Gemini, Ollama — plus an opt-in subscription mode (see the ToS warning in `lohra auth`).
+
+MIT license. Alpha software — built and validated live, but young.

lohra-0.0.1/lohra/__init__.py

@@ -0,0 +1,7 @@
+"""Lohra — self-improving AI agent with a desktop app.
+
+Backend package: agent core, provider abstraction, tool system, memory/skills,
+and the FastAPI gateway. See docs/ARCHITECTURE.md for the full design.
+"""
+
+__version__ = "0.0.1"

lohra-0.0.1/lohra/agent/__init__.py

@@ -0,0 +1,18 @@
+"""Agent core: conversation loop, transports, prompt assembly.
+
+See docs/specs/01-agent-core.md.
+"""
+
+from lohra.agent.agent import Agent
+from lohra.agent.client import AnthropicClient, ModelClient
+from lohra.agent.loop import run_conversation
+from lohra.agent.system_prompt import SystemPromptSnapshot, build_system_prompt
+
+__all__ = [
+    "Agent",
+    "AnthropicClient",
+    "ModelClient",
+    "run_conversation",
+    "SystemPromptSnapshot",
+    "build_system_prompt",
+]

lohra-0.0.1/lohra/agent/agent.py

@@ -0,0 +1,123 @@
+"""Agent — the live session controller.
+
+Unlike the canonical response types (frozen, immutable), the Agent is a
+stateful session object: it caches the frozen system prompt (Invariante #1),
+holds the interrupt flag, and resolves per-call configuration. The spec models
+this same mutable state (``agent._cached_system_prompt``,
+``agent._interrupt_requested``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping
+
+from lohra.agent.aux import AuxClient
+from lohra.agent.client import ModelClient
+from lohra.agent.context import ContextEngine
+from lohra.agent.system_prompt import SystemPromptSnapshot, build_system_prompt
+from lohra.memory.store import MemoryStore
+from lohra.providers.base import ProviderProfile
+from lohra.skills.store import SkillStore
+from lohra.providers.transports.base import Transport, get_transport
+
+DEFAULT_MAX_ITERATIONS = 8
+
+# A tool executor: (name, parsed args) -> JSON-string result envelope.
+ToolDispatch = Callable[[str, dict[str, Any]], str]
+
+
+@dataclass
+class Agent:
+    """A conversation session bound to one provider/model/client."""
+
+    model: str
+    provider: ProviderProfile
+    client: ModelClient
+
+    # system-prompt inputs (frozen into the snapshot on first use)
+    identity: str | None = None  # SOUL.md persona; None -> built-in identity
+    system_message: str | None = None
+    context_files: tuple[tuple[str, str], ...] = ()
+    environment_hints: Mapping[str, str] = field(default_factory=dict)
+    # memory + skills snapshots are captured once and frozen into the prompt
+    # (Invariante #1)
+    memory_store: MemoryStore | None = None
+    skill_store: SkillStore | None = None
+
+    # tools: definitions sent to the model + an executor for tool_use turns.
+    # Both unset = chat-only (Phase 1 behavior).
+    tool_definitions: tuple[dict, ...] = ()
+    tool_dispatch: ToolDispatch | None = None
+
+    # forced structured output (workflow §5.2): when set to a tool def, the turn
+    # sends ONLY that tool and forces tool_choice; the tool's arguments ARE the
+    # answer. None (default) -> byte-identical normal behavior. Set per-leaf via
+    # the core.spawn `configure` hook; never on a frozen prompt (rides in tools=).
+    forced_tool: dict | None = None
+
+    # loop configuration
+    max_iterations: int = DEFAULT_MAX_ITERATIONS
+    max_tokens: int | None = None
+    temperature: float | None = None
+    # reasoning effort (provider-specific; emitted only where supported — OpenAI/
+    # Responses). None → unchanged. Mutable per spawn like ``model``.
+    effort: str | None = None
+
+    # context compression (both set = preflight compaction enabled)
+    context_window: int = 200_000
+    context_engine: ContextEngine | None = None
+    aux_client: AuxClient | None = None
+
+    # mutable session state (never part of construction)
+    _cached_system_prompt: SystemPromptSnapshot | None = field(
+        default=None, init=False, repr=False
+    )
+    _interrupt_requested: bool = field(default=False, init=False, repr=False)
+
+    @property
+    def transport(self) -> Transport:
+        """The transport for this provider's api_mode; fail fast if unregistered."""
+        transport = get_transport(self.provider.api_mode)
+        if transport is None:
+            raise LookupError(
+                f"no transport registered for api_mode {self.provider.api_mode!r} "
+                f"(provider {self.provider.name!r})"
+            )
+        return transport
+
+    def system_prompt(self) -> SystemPromptSnapshot:
+        """Restore-or-build the frozen snapshot (built once, then reused).
+
+        The memory snapshot is captured here on first use and frozen into the
+        prompt; mid-session memory writes hit disk but never this prompt.
+        """
+        if self._cached_system_prompt is None:
+            memory_snapshot, user_profile = "", ""
+            if self.memory_store is not None:
+                snapshot = self.memory_store.snapshot()
+                memory_snapshot, user_profile = snapshot["memory"], snapshot["user"]
+            skills_index = self.skill_store.snapshot() if self.skill_store is not None else ""
+            self._cached_system_prompt = build_system_prompt(
+                identity=self.identity,
+                system_message=self.system_message,
+                context_files=self.context_files,
+                environment_hints=self.environment_hints,
+                memory_snapshot=memory_snapshot,
+                user_profile=user_profile,
+                skills_index=skills_index,
+            )
+        return self._cached_system_prompt
+
+    def resolve_max_tokens(self) -> int | None:
+        """Explicit override wins; otherwise the provider profile owns the default."""
+        if self.max_tokens is not None:
+            return self.max_tokens
+        return self.provider.get_max_tokens(self.model)
+
+    def request_interrupt(self) -> None:
+        """Signal the loop to stop at the next safe boundary."""
+        self._interrupt_requested = True
+
+    def clear_interrupt(self) -> None:
+        self._interrupt_requested = False

lohra-0.0.1/lohra/agent/aux.py

@@ -0,0 +1,55 @@
+"""Auxiliary client — routes side tasks to a cheap, fast model (spec §8).
+
+Compaction summaries and session titles don't need the main model. AuxClient
+wraps a ModelClient + transport at the provider's aux model (e.g. Haiku) and
+exposes ``summarize`` / ``title``, plus ``summarizer()`` to hand the compressor
+a plain Callable[[str], str].
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from lohra.agent.client import ModelClient
+from lohra.providers.transports.base import Transport
+
+SUMMARY_SYSTEM = (
+    "You are compacting a long conversation to fit the context window. Summarize "
+    "the transcript below into a concise but complete reference. Under these "
+    "headings, keep only what is still relevant: Active Task; Goal; Completed "
+    "Actions (results, not narration); Active State (files/vars/decisions in "
+    "play); Blocked/Open; Key Decisions (and why); Pending User Asks; Remaining "
+    "Work. Be factual and terse. Never invent details."
+)
+
+TITLE_SYSTEM = (
+    "Write a short (≤6 words) title for this conversation. Reply with the title "
+    "only — no quotes, no punctuation at the end."
+)
+
+
+class AuxClient:
+    def __init__(self, *, client: ModelClient, transport: Transport, model: str) -> None:
+        self._client = client
+        self._transport = transport
+        self._model = model
+
+    def complete(self, system: str, user: str, *, max_tokens: int = 1024) -> str:
+        kwargs: dict[str, Any] = self._transport.build_kwargs(
+            model=self._model,
+            messages=[{"role": "user", "content": user}],
+            system=system,
+            max_tokens=max_tokens,
+        )
+        response = self._transport.normalize_response(self._client.create(**kwargs))
+        return (response.content or "").strip()
+
+    def summarize(self, transcript: str) -> str:
+        return self.complete(SUMMARY_SYSTEM, transcript)
+
+    def title(self, transcript: str) -> str:
+        return self.complete(TITLE_SYSTEM, transcript, max_tokens=32)
+
+    def summarizer(self) -> Callable[[str], str]:
+        """A plain callable for ContextCompressor.compress(summarize=...)."""
+        return self.summarize