flanes 0.3.0__tar.gz

flanes-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to Fla
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/glimish/fla.git
+cd fla
+
+# Install in development mode with all dev dependencies
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+python -X utf8 -m pytest tests/ -v
+
+# Run fast tests only (skip stress/slow)
+python -X utf8 -m pytest tests/ -v -m "not stress and not slow"
+
+# Run a specific test file
+python -X utf8 -m pytest tests/test_cli.py -v
+```
+
+## Linting and Type Checking
+
+```bash
+# Lint
+ruff check fla/ tests/
+
+# Check formatting
+ruff format --check fla/ tests/
+
+# Auto-format
+ruff format fla/ tests/
+
+# Type check
+mypy fla/
+```
+
+## Code Style
+
+- Python 3.10+ (use `X | Y` union syntax, not `Union[X, Y]`)
+- Max line length: 100 characters (configured in `pyproject.toml`)
+- Linting: ruff with `E, F, W, I, N, UP` rules
+- No unused imports or variables
+
+## Pull Request Guidelines
+
+1. Fork the repo and create a branch from `main`
+2. Write tests for new functionality
+3. Run the full test suite and ensure it passes
+4. Run `ruff check` and `mypy` with no new errors
+5. Write a clear PR description explaining the change and why
+
+## Architecture
+
+See the [Architecture section in README.md](README.md#architecture) for an overview.
+The codebase is organized into layers:
+
+- **CLI / Agent SDK** (`cli.py`, `agent_sdk.py`) - User-facing interfaces
+- **Repository** (`repo.py`) - High-level operations
+- **Managers** (`workspace.py`, `state.py`) - Domain logic
+- **Content Store** (`cas.py`) - Content-addressed storage
+- **SQLite** - Persistence layer (WAL mode)
+
+## Reporting Issues
+
+Please file issues on GitHub with:
+- Steps to reproduce
+- Expected vs actual behavior
+- Python version and OS
+- Fla version (`fla --version`)

flanes-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kim Ranzani - Glimish
+
+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.

flanes-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md CONTRIBUTING.md
+recursive-include examples *
+recursive-include docs *
+recursive-include fla/web *.html *.css *.js

flanes-0.3.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: flanes
+Version: 0.3.0
+Summary: Fla: Feature Lanes for Agents - version control for agentic AI systems
+Author: Kim Ranzani (Glimish)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/glimish/fla
+Project-URL: Repository, https://github.com/glimish/fla
+Project-URL: Issues, https://github.com/glimish/fla/issues
+Project-URL: Documentation, https://github.com/glimish/fla/tree/main/docs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26; extra == "s3"
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.0; extra == "gcs"
+Provides-Extra: remote
+Requires-Dist: boto3>=1.26; extra == "remote"
+Requires-Dist: google-cloud-storage>=2.0; extra == "remote"
+Dynamic: license-file
+Dynamic: requires-python
+
+# Fla: Feature Lanes for Agents
+
+**Version Control for Agentic AI Systems**
+
+[![Tests](https://github.com/glimish/fla/actions/workflows/test.yml/badge.svg)](https://github.com/glimish/fla/actions/workflows/test.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Version control designed from the ground up for AI agents. Replaces git's line-diff model with intent-based snapshots, physically isolated workspaces, and evaluation gating.
+
+## Why Fla?
+
+Git assumes a single human making small, curated edits. AI agents break every part of that model.
+
+| | Git | Fla |
+|---|---|---|
+| **Unit of work** | Line diffs | Full world-state snapshots |
+| **Change metadata** | Free-text commit message | Structured intent + agent identity |
+| **Quality gate** | CI runs after merge | Evaluation gating before accept |
+| **Parallel agents** | Branch conflicts | Physically isolated workspaces |
+| **Cost tracking** | None | Per-transition token/API accounting |
+
+## Quick Demo
+
+```bash
+cd my-project
+fla init
+# Writes files, then commits in one step:
+fla commit --prompt "Add auth module" \
+  --agent-id coder-1 --agent-type feature_dev --auto-accept
+
+# Create isolated feature lane
+fla lane create feature-auth
+
+# Work in isolation, promote back to main
+fla promote --workspace feature-auth --target main --auto-accept
+
+# Query history
+fla history --lane main
+```
+
+Or use the Python SDK:
+
+```python
+from fla.agent_sdk import AgentSession
+
+session = AgentSession(
+    repo_path="./my-project",
+    agent_id="coder-alpha",
+    agent_type="feature_developer",
+)
+
+with session.work("Add authentication module", tags=["auth"], auto_accept=True) as w:
+    (w.path / "auth.py").write_text("def authenticate(): ...")
+    w.record_tokens(tokens_in=2000, tokens_out=1200)
+# On exit: snapshots -> proposes -> accepts (or rejects on exception)
+```
+
+See [`examples/`](examples/) for runnable demos.
+
+## Installation
+
+```bash
+pip install fla
+
+# Optional: remote storage backends
+pip install fla[s3]    # Amazon S3 (boto3)
+pip install fla[gcs]   # Google Cloud Storage
+```
+
+## Core Concepts
+
+**World States:** Immutable snapshots of the entire project. Agents propose new world states, not diffs.
+
+**Intents:** Structured metadata for every change: the instruction, who issued it, cost tracking, and semantic tags.
+
+**Transitions:** Proposals to move from one state to another. Must be *evaluated* before acceptance.
+
+**Lanes:** Isolated workstreams. Work is *promoted* into a target lane through evaluation, not merged.
+
+**Workspaces:** Main workspace is the repo root (git-style). Feature lanes get physically isolated directories under `.fla/workspaces/`.
+
+## Architecture
+
+```
++--------------------------------------------------+
+|                 CLI / Agent SDK                    |
+|       (fla commands / AgentSession API)            |
++--------------------------------------------------+
+|                  Repository                        |
+|   (propose, accept, promote, restore, etc)         |
++--------------------+-----------------------------+
+|  WorkspaceManager  |     WorldStateManager        |
+|  (isolation,       |  (states, transitions,        |
+|   locking,         |   lanes, history, trace,      |
+|   materialization) |   conflict detection)          |
++--------------------+-----------------------------+
+|             Content-Addressed Store                |
+|    (SHA-256 blobs + trees, dedup, integrity)       |
++--------------------------------------------------+
+|                    SQLite                           |
+|         (WAL mode, single-file database)           |
++--------------------------------------------------+
+```
+
+## Key Features
+
+- **Git-style main:** repo root IS the main workspace. Files stay where you expect them.
+- **Physical isolation:** feature workspaces are real directories. Parallel agents can't stomp on each other.
+- **Smart incremental updates:** workspace sync writes only changed files, not the entire tree.
+- **Cross-platform locking:** atomic `mkdir` locking works on Linux, macOS, and Windows.
+- **Conflict detection:** promote finds path-level collisions without content merging.
+- **Evaluators:** run pytest, ruff, or custom checks as gates before accepting transitions.
+- **Cost tracking:** per-transition token usage, wall time, and API call counts.
+- **Git bridge:** `fla export-git` / `fla import-git` for CI integration.
+- **Remote storage:** S3/GCS-backed sync for team collaboration.
+- **MCP server:** expose Fla as tools for LLM integration via Model Context Protocol.
+- **REST API:** `fla serve` starts a multi-threaded HTTP API.
+- **Garbage collection:** `fla gc` removes rejected states and unreachable objects.
+
+## Documentation
+
+- **[User Guide](docs/guide.md):** comprehensive reference for all features
+- **[Examples](examples/):** runnable demo scripts
+- **[Contributing](CONTRIBUTING.md):** development setup and guidelines
+
+## Workspace Layout
+
+```
+my-project/
++-- .fla/
+|   +-- config.json
+|   +-- store.db                        # SQLite database
+|   +-- main.json                       # main workspace metadata
+|   +-- workspaces/
+|       +-- feature-auth/               # isolated feature workspace
+|       +-- feature-auth.json
++-- app.py                              # YOUR FILES AT REPO ROOT
++-- lib/
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+python -X utf8 -m pytest tests/ -v
+```
+
+## License
+
+[MIT](LICENSE)

flanes-0.3.0/README.md

@@ -0,0 +1,151 @@
+# Fla: Feature Lanes for Agents
+
+**Version Control for Agentic AI Systems**
+
+[![Tests](https://github.com/glimish/fla/actions/workflows/test.yml/badge.svg)](https://github.com/glimish/fla/actions/workflows/test.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Version control designed from the ground up for AI agents. Replaces git's line-diff model with intent-based snapshots, physically isolated workspaces, and evaluation gating.
+
+## Why Fla?
+
+Git assumes a single human making small, curated edits. AI agents break every part of that model.
+
+| | Git | Fla |
+|---|---|---|
+| **Unit of work** | Line diffs | Full world-state snapshots |
+| **Change metadata** | Free-text commit message | Structured intent + agent identity |
+| **Quality gate** | CI runs after merge | Evaluation gating before accept |
+| **Parallel agents** | Branch conflicts | Physically isolated workspaces |
+| **Cost tracking** | None | Per-transition token/API accounting |
+
+## Quick Demo
+
+```bash
+cd my-project
+fla init
+# Writes files, then commits in one step:
+fla commit --prompt "Add auth module" \
+  --agent-id coder-1 --agent-type feature_dev --auto-accept
+
+# Create isolated feature lane
+fla lane create feature-auth
+
+# Work in isolation, promote back to main
+fla promote --workspace feature-auth --target main --auto-accept
+
+# Query history
+fla history --lane main
+```
+
+Or use the Python SDK:
+
+```python
+from fla.agent_sdk import AgentSession
+
+session = AgentSession(
+    repo_path="./my-project",
+    agent_id="coder-alpha",
+    agent_type="feature_developer",
+)
+
+with session.work("Add authentication module", tags=["auth"], auto_accept=True) as w:
+    (w.path / "auth.py").write_text("def authenticate(): ...")
+    w.record_tokens(tokens_in=2000, tokens_out=1200)
+# On exit: snapshots -> proposes -> accepts (or rejects on exception)
+```
+
+See [`examples/`](examples/) for runnable demos.
+
+## Installation
+
+```bash
+pip install fla
+
+# Optional: remote storage backends
+pip install fla[s3]    # Amazon S3 (boto3)
+pip install fla[gcs]   # Google Cloud Storage
+```
+
+## Core Concepts
+
+**World States:** Immutable snapshots of the entire project. Agents propose new world states, not diffs.
+
+**Intents:** Structured metadata for every change: the instruction, who issued it, cost tracking, and semantic tags.
+
+**Transitions:** Proposals to move from one state to another. Must be *evaluated* before acceptance.
+
+**Lanes:** Isolated workstreams. Work is *promoted* into a target lane through evaluation, not merged.
+
+**Workspaces:** Main workspace is the repo root (git-style). Feature lanes get physically isolated directories under `.fla/workspaces/`.
+
+## Architecture
+
+```
++--------------------------------------------------+
+|                 CLI / Agent SDK                    |
+|       (fla commands / AgentSession API)            |
++--------------------------------------------------+
+|                  Repository                        |
+|   (propose, accept, promote, restore, etc)         |
++--------------------+-----------------------------+
+|  WorkspaceManager  |     WorldStateManager        |
+|  (isolation,       |  (states, transitions,        |
+|   locking,         |   lanes, history, trace,      |
+|   materialization) |   conflict detection)          |
++--------------------+-----------------------------+
+|             Content-Addressed Store                |
+|    (SHA-256 blobs + trees, dedup, integrity)       |
++--------------------------------------------------+
+|                    SQLite                           |
+|         (WAL mode, single-file database)           |
++--------------------------------------------------+
+```
+
+## Key Features
+
+- **Git-style main:** repo root IS the main workspace. Files stay where you expect them.
+- **Physical isolation:** feature workspaces are real directories. Parallel agents can't stomp on each other.
+- **Smart incremental updates:** workspace sync writes only changed files, not the entire tree.
+- **Cross-platform locking:** atomic `mkdir` locking works on Linux, macOS, and Windows.
+- **Conflict detection:** promote finds path-level collisions without content merging.
+- **Evaluators:** run pytest, ruff, or custom checks as gates before accepting transitions.
+- **Cost tracking:** per-transition token usage, wall time, and API call counts.
+- **Git bridge:** `fla export-git` / `fla import-git` for CI integration.
+- **Remote storage:** S3/GCS-backed sync for team collaboration.
+- **MCP server:** expose Fla as tools for LLM integration via Model Context Protocol.
+- **REST API:** `fla serve` starts a multi-threaded HTTP API.
+- **Garbage collection:** `fla gc` removes rejected states and unreachable objects.
+
+## Documentation
+
+- **[User Guide](docs/guide.md):** comprehensive reference for all features
+- **[Examples](examples/):** runnable demo scripts
+- **[Contributing](CONTRIBUTING.md):** development setup and guidelines
+
+## Workspace Layout
+
+```
+my-project/
++-- .fla/
+|   +-- config.json
+|   +-- store.db                        # SQLite database
+|   +-- main.json                       # main workspace metadata
+|   +-- workspaces/
+|       +-- feature-auth/               # isolated feature workspace
+|       +-- feature-auth.json
++-- app.py                              # YOUR FILES AT REPO ROOT
++-- lib/
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+python -X utf8 -m pytest tests/ -v
+```
+
+## License
+
+[MIT](LICENSE)