loro-agent 0.1.0__tar.gz

loro_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install package and dev dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Test with coverage
+        run: python -m pytest --cov --cov-report=term-missing --cov-report=xml
+
+      - name: Compile Python files
+        run: python -m compileall src tests

loro_agent-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,60 @@
+name: Integration
+
+on:
+  workflow_dispatch:
+    inputs:
+      postgres:
+        description: "Run Postgres Testcontainers integration tests"
+        required: true
+        default: "true"
+        type: choice
+        options: ["true", "false"]
+      polaris:
+        description: "Run Polaris CLI integration tests against a preconfigured runner"
+        required: true
+        default: "false"
+        type: choice
+        options: ["true", "false"]
+
+jobs:
+  postgres:
+    if: ${{ inputs.postgres == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install integration dependencies
+        run: python -m pip install -e ".[dev,integration]"
+
+      - name: Run Postgres integration tests
+        env:
+          LORO_INTEGRATION_POSTGRES: "1"
+        run: python -m pytest -m integration tests/integration/test_postgres_memory_integration.py
+
+  polaris:
+    if: ${{ inputs.polaris == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install integration dependencies
+        run: python -m pip install -e ".[dev,data]"
+
+      - name: Run Polaris CLI integration tests
+        env:
+          LORO_INTEGRATION_POLARIS: "1"
+        run: python -m pytest -m integration tests/integration/test_polaris_cli_integration.py

loro_agent-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+dist/
+build/
+.env
+.env.*
+!.env.example
+.loro/config.local.toml
+.loro/audit.jsonl
+.loro/memory/
+.loro/shared-memory-drafts.jsonl
+.loro/sessions/
+/artifacts/
+*.log

loro_agent-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,186 @@
+# Loro Architecture
+
+Loro is a Python CLI agent harness for enterprise coding, governed data access, and productivity artifact generation. Its architecture is intentionally layered so the terminal UX, runtime loop, tools, memory, governance integrations, and artifacts can evolve independently.
+
+## System Context
+
+```mermaid
+flowchart LR
+  User["Enterprise user"] --> CLI["Loro CLI / TUI"]
+  CLI --> Runtime["Agent runtime"]
+  Runtime --> Models["Model provider adapters"]
+  Runtime --> Tools["Typed tool registry"]
+  Runtime --> Memory["Memory subsystem"]
+  Runtime --> Artifacts["Artifact generators"]
+  Runtime --> Audit["Audit log"]
+  Tools --> Files["File tools"]
+  Tools --> Shell["Shell tools"]
+  Tools --> Git["Git tools"]
+  Tools --> Polaris["Polaris wrapper"]
+  Memory --> Local["Local memory"]
+  Memory --> Shared["Shared enterprise memory"]
+  Shared --> Postgres["Postgres backend"]
+  Shared --> Iceberg["Iceberg backend"]
+  Polaris --> Catalog["Apache Polaris / Iceberg REST catalog"]
+```
+
+## Package Layout
+
+- `loro.cli`: Typer command surface and command-specific orchestration.
+- `loro.runtime`: task runtime, memory recall, audit events, and session persistence.
+- `loro.config`: layered configuration model and environment overrides.
+- `loro.permissions`: `allow` / `ask` / `deny` policy evaluation.
+- `loro.provider_profiles`: built-in AI provider profile registry.
+- `loro.providers`: provider lookup, validation, and local configuration writer.
+- `loro.tools`: local file, shell, and Git tools, with more tools expected behind typed interfaces.
+- `loro.tool_runtime`: explicit typed runtime tool-call parsing and execution.
+- `loro.artifacts`: document, presentation, spreadsheet, brief, and provenance generators.
+- `loro.memory`: local memory, shared-memory draft storage, schema generation, backend adapters, and shared-memory operations.
+- `loro.polaris`: controlled read-only wrapper around the Polaris CLI.
+- `loro.audit`: JSONL audit event writer.
+- `loro.serialization`: small helpers for JSON-safe CLI output.
+- `loro.sessions`: durable JSON session records.
+
+## Runtime Flow
+
+1. The CLI resolves config from system, user, project, local, `LORO_CONFIG`, and
+   `LORO_CONFIG_CONTENT`, then applies managed enterprise overlays last.
+2. The runtime loads local memory and, when enabled, searches shared enterprise memory for
+   relevant cited records.
+3. The runtime emits `runtime.task_started`.
+4. Explicit prompt tool directives are executed before the first model call.
+5. The runtime calls the configured model and parses provider-neutral tool directives from
+   the response.
+6. Approved tool calls are executed, audited, and sent back to the model as structured text.
+7. The loop repeats until the model responds without tool directives or `[runtime].max_steps`
+   is reached.
+8. The runtime creates a session summary, including tool execution payloads and stop reason,
+   and persists it to the configured session store.
+9. The runtime emits `runtime.task_completed`.
+10. Artifact and tool commands emit their own audit events with previews and metadata, not full sensitive payloads.
+
+The current model-directed loop uses text directives such as
+`@tool {"name": "file.read", "args": {"path": "README.md"}}`. Native provider tool-calling
+can map into the same internal `ToolCall` type as provider adapters mature. The runtime
+registry currently exposes file read/search, local memory search, permission-gated shell
+execution, read-only Polaris passthrough, artifact generation with provenance, approved file
+writes/replacements, and Git status/diff/show/add/commit helpers.
+
+## Configuration
+
+Loro config is loaded in increasing precedence:
+
+1. `/etc/loro/config.toml`
+2. `~/.config/loro/config.toml`
+3. `.loro/config.toml`
+4. `.loro/config.local.toml`
+5. File referenced by `LORO_CONFIG`
+6. Inline TOML from `LORO_CONFIG_CONTENT`
+7. Non-overridable managed overlays from `/etc/loro/managed.toml`, `LORO_MANAGED_CONFIG`,
+   and `LORO_MANAGED_CONFIG_CONTENT`
+
+Managed overlays use the same TOML schema as normal config but are re-applied after runtime
+overrides, making them suitable for enterprise permission denies, audit defaults, shared
+memory policy, and governed data configuration.
+
+## Permissions
+
+The permission engine evaluates requests as:
+
+- `allow`: tool may execute.
+- `ask`: tool requires an explicit CLI approval flag or future interactive approval.
+- `deny`: tool is blocked.
+
+Ordered permission rules can override per-tool defaults with case-insensitive glob matches
+on tool, action, and target. The first matching rule wins.
+
+Current examples:
+
+- `loro shell run --yes -- python -c "print('ok')"` requires `--yes` when shell policy is `ask`.
+- `loro file read` and `loro file search` are read-only and internally approved for the current CLI command.
+- Runtime file writes, Git mutations, and shell execution require explicit approval unless
+  policy sets the relevant action to `allow`.
+
+Future work should add richer data-scope matchers.
+
+## AI Providers
+
+Provider profiles are stored in `loro.providers`. Profiles capture:
+
+- Provider name and display name.
+- Default primary model.
+- Default small/fast model.
+- API key environment variable.
+- Base URL.
+- Protocol family.
+- Notes for special providers.
+
+Current profiles cover OpenAI, Anthropic, Gemini, Mistral, Groq, Cerebras, Together AI, Fireworks AI, DeepSeek, xAI, Perplexity, OpenRouter, Nous Portal, OpenCode Zen, OpenCode Go, Azure OpenAI, AWS Bedrock, Ollama, LM Studio, vLLM, and generic OpenAI-compatible endpoints.
+
+`loro configure` writes `.loro/config.local.toml`, keeping user-specific provider choices and endpoint details out of source control. `loro providers check` validates required environment variables. `loro providers request` prints a redacted request payload without performing network I/O. `loro.models` contains the request-building adapter layer for mock, OpenAI-compatible, Anthropic, Gemini, Ollama, and optional AWS Bedrock protocols. `loro.model_tools` normalizes native OpenAI-compatible `tool_calls`, Anthropic `tool_use`, Gemini `functionCall`, and Bedrock `toolUse` response payloads into the runtime's provider-neutral tool-call shape. Textual `@tool` directives remain supported for deterministic tests and providers without native tool calling.
+
+## Memory
+
+Loro has two memory planes:
+
+- Local memory: JSONL-backed today, private to the current environment, searchable by substring.
+- Shared memory: schema-first scaffolding for explicit user-approved enterprise memory.
+
+Shared memory writes must stay explicit. The agent can propose a memory, but only
+user-approved text should be staged or committed. Current code supports shared memory schema
+generation, draft records, proposal records, `memory shared-search`, `memory apply-schema`
+SQL dry runs, `memory commit-draft` SQL dry runs, Postgres readiness diagnostics, a Postgres
+adapter that can apply schema, execute explicit draft commits, and execute search when
+`psycopg` plus a DSN are available, and an Iceberg adapter that renders configured DDL plus
+append/search SQL. The Iceberg adapter can also execute search and explicit draft commits
+through a configured PyIceberg catalog, typically a Polaris-governed REST catalog. Runtime
+shared-memory recall includes citations so responses can identify the backend, tenant, scope,
+and memory id.
+
+## Artifact Generation
+
+Artifact commands use deterministic Python generators:
+
+- Documents: Markdown and DOCX.
+- Presentations: Markdown outline and PPTX.
+- Spreadsheets: XLSX and CSV.
+- Briefs: Markdown.
+
+Each artifact write produces a `.provenance.json` sidecar with prompt preview, generated paths, assumptions, timestamp, and generator metadata.
+
+## Polaris And Governed Data
+
+The Polaris integration is intentionally controlled:
+
+- `loro data catalogs` calls `polaris catalogs list` only when Polaris is enabled.
+- Typed `loro data` commands cover catalog, namespace, table, view, role, privilege, and policy discovery.
+- `loro data polaris ...` validates the resource/action pair against a read-only allowlist before executing.
+
+Future work should expose governed table context to the agent loop and add higher-level access explanations.
+
+## Persistence
+
+Runtime files are ignored by Git:
+
+- `.loro/audit.jsonl`
+- `.loro/memory/`
+- `.loro/sessions/`
+- `artifacts/`
+
+This keeps local usage out of source control while preserving inspectable state on disk.
+
+## Testing Strategy
+
+The MVP uses focused unit and CLI tests:
+
+- Artifact creation and provenance.
+- Audit JSONL writing.
+- Config merge and environment overrides.
+- Local memory search.
+- Session roundtrips.
+- File, shell, and Polaris tool behavior.
+- Typer CLI smoke behavior.
+- Postgres shared-memory SQL rendering and backend readiness checks.
+- Iceberg shared-memory DDL and SQL rendering.
+
+Integration tests for real Postgres, Iceberg, Polaris, and model providers should live behind optional test markers once those services are implemented.

loro_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Merced
+
+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.

loro_agent-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: loro-agent
+Version: 0.1.0
+Summary: Enterprise memory-sharing CLI agent harness for coding, governed data, and productivity work.
+Project-URL: Homepage, https://github.com/alexmerced-oss/loro
+Project-URL: Documentation, https://github.com/alexmerced-oss/loro/tree/main/docs
+Project-URL: Repository, https://github.com/alexmerced-oss/loro
+Project-URL: Issues, https://github.com/alexmerced-oss/loro/issues
+Author: Alex Merced
+License: MIT
+License-File: LICENSE
+Keywords: agents,cli,enterprise,iceberg,memory,polaris
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pydantic-settings>=2.5.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: python-docx>=1.1.2
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: typer>=0.12.5
+Requires-Dist: xlsxwriter>=3.2.0
+Provides-Extra: artifacts
+Requires-Dist: pandas>=2.2.0; extra == 'artifacts'
+Provides-Extra: aws
+Requires-Dist: boto3>=1.34.0; extra == 'aws'
+Provides-Extra: data
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'data'
+Requires-Dist: pyarrow>=17.0.0; extra == 'data'
+Requires-Dist: pyiceberg>=0.8.0; extra == 'data'
+Requires-Dist: sqlalchemy>=2.0.35; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.9; extra == 'dev'
+Provides-Extra: integration
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'integration'
+Requires-Dist: testcontainers[postgres]>=4.8.0; extra == 'integration'
+Description-Content-Type: text/markdown
+
+# Loro
+
+Loro is a Python CLI agent harness for enterprise coding, governed data work, and productivity tasks.
+
+"Loro" is Spanish for parrot: an intelligent, social bird that listens, learns, repeats useful knowledge, and helps information move across groups.
+
+## Install
+
+```bash
+python -m pip install loro-agent
+loro --version
+```
+
+Optional extras:
+
+```bash
+python -m pip install "loro-agent[data]" # Postgres, Iceberg, and PyArrow support
+python -m pip install "loro-agent[aws]"  # AWS Bedrock adapter support
+python -m pip install "loro-agent[dev]"  # Development and test tools
+```
+
+## What It Includes
+
+- A Typer-powered CLI entrypoint.
+- Configuration loading from system, user, project, local, runtime, and managed enterprise sources.
+- Permission decision primitives.
+- Local and shared memory interfaces.
+- Postgres and Iceberg shared memory adapters with explicit-only shared write flows.
+- PyIceberg execution support for governed Iceberg shared-memory search and draft commits.
+- Polaris client for read-only governed catalog discovery.
+- Artifact generation for Markdown/DOCX documents, PPTX presentations, XLSX/CSV spreadsheets, and Markdown briefs.
+- Artifact provenance sidecars that record prompt previews, generated paths, assumptions, and generator metadata.
+- JSONL audit logging for runtime tasks, memory writes, and artifact creation.
+- Durable session records with `loro sessions list` and `loro sessions show`.
+- Permission-gated file and shell tools.
+- Shared memory draft staging and Postgres/Iceberg schema output.
+- Shared memory backend diagnostics.
+- Safety scanner for obvious secrets before memory and artifact writes.
+- AI provider profiles and `loro configure` setup wizard.
+- Native tool-call normalization for OpenAI-compatible, Anthropic, Gemini, and Bedrock providers.
+
+## Configure A Provider
+
+Use the setup wizard or pass options directly:
+
+```bash
+loro providers list
+loro providers show openai
+export OPENAI_API_KEY="<your-key>"
+loro configure --provider openai --model gpt-4.1 --small-model gpt-4.1-mini
+loro providers check openai
+```
+
+For local Ollama:
+
+```bash
+loro configure --provider ollama --model llama3.2 --small-model llama3.2
+```
+
+`loro configure` writes `.loro/config.local.toml` by default. Keep provider secrets in
+environment variables.
+
+## Run Agentic Tasks
+
+```bash
+loro plan "Create a release readiness checklist"
+loro run "Inspect README.md and suggest the next three improvements."
+```
+
+Loro can use typed tools for file reads/searches, approved edits, approved shell commands,
+Git helpers, memory search, Polaris discovery, and artifact creation. Write-like tools are
+permission-gated.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+loro --help
+python -m pytest
+```
+
+## Examples
+
+```bash
+loro remember --local "Status briefs should include risks, blockers, next steps, and owner."
+loro remember --shared "Use the enterprise launch readiness template for launches."
+loro memory drafts
+loro memory commit-draft <draft-id>
+loro memory shared-search "launch readiness" --tenant-id acme
+loro memory propose "Use concise launch summaries" --target local
+loro memory propose "Use the enterprise launch readiness template" --target shared
+loro memory accept-proposal <proposal-id>
+loro memory schema --backend postgres
+loro memory backend-check
+loro docs create "Draft a project kickoff document"
+loro slides create "Quarterly platform update"
+loro sheets create "Launch readiness tracker"
+loro brief meeting "Prepare for roadmap sync"
+loro memory search "status briefs"
+loro sessions list
+loro file search "Polaris" --root .
+loro file read PRD.md --limit 1000
+loro shell run --yes -- python -c "print('hello from Loro')"
+loro safety scan "api_key = 'abc123456789'"
+loro providers list
+loro providers show nous-portal
+loro providers check nous
+loro providers request "hello" --provider nous --model hermes-3-405b
+loro configure --provider ollama --model llama3.2 --small-model llama3.2
+loro data schema events --catalog prod --namespace analytics
+loro data explain-access events --catalog prod --namespace analytics --catalog-role reader
+```
+
+Generated files are written to `artifacts/` by default. Use `--output-dir` to choose another location. Each generated artifact also gets a `.provenance.json` sidecar.
+
+Configuration can be layered from `.loro/config.toml`, `LORO_CONFIG`, and
+`LORO_CONFIG_CONTENT`. Enterprise-managed overlays can be supplied through
+`/etc/loro/managed.toml`, `LORO_MANAGED_CONFIG`, or `LORO_MANAGED_CONFIG_CONTENT`; those
+managed values are applied last.
+
+For shell commands, use `--` before the command when passing flags to the child process.
+
+Memory and artifact commands scan for obvious secrets by default. Use `--allow-sensitive` only when enterprise policy allows that content to be persisted.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [CLI Guide](docs/cli.md)
+- [Configuration](docs/configuration.md)
+- [AI Providers](docs/providers.md)
+- [Memory](docs/memory.md)
+- [Polaris And Iceberg](docs/polaris-iceberg.md)
+
+## License
+
+MIT