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)
