multi-agent-platform 0.1.0__tar.gz → 0.2.0__tar.gz

{multi_agent_platform-0.1.0/multi_agent_platform.egg-info → multi_agent_platform-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-agent-platform
-Version: 0.1.0
+Version: 0.2.0
 Summary: Multi-Agent experiment collaboration platform
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/quantaeye/multi-agent-platform
@@ -45,8 +45,20 @@ Dynamic: license-file
 
 # Multi-Agent Platform (MAP)
 
+[![PyPI version](https://img.shields.io/pypi/v/multi-agent-platform.svg)](https://pypi.org/project/multi-agent-platform/)
+[![Python 3.11+](https://img.shields.io/pypi/pyversions/multi-agent-platform.svg)](https://pypi.org/project/multi-agent-platform/)
+[![License: MIT](https://img.shields.io/pypi/l/multi-agent-platform.svg)](https://github.com/quantaeye/multi-agent-platform/blob/main/LICENSE)
+
 多 Agent 实验协作平台：以话题为中心，管理实验计划、评审讨论、执行日志与项目状态。
 
+## 安装
+
+```bash
+pip install multi-agent-platform
+```
+
+安装后即可使用 `map` CLI 和 `map-server` 命令。详见 [Quick Start 指南](docs/QUICKSTART.md)。
+
 **新用户？** 一键启动：`./scripts/quickstart.sh`，或阅读 [Quick Start 指南](docs/QUICKSTART.md)。
 
 ## 文档
@@ -138,7 +150,10 @@ map --persona host todos
 ## 快速开始
 
 ```bash
-# 安装依赖（含开发工具）
+# 从 PyPI 安装（用户）
+pip install multi-agent-platform
+
+# 或从源码开发安装（贡献者）
 pip install -e ".[dev]"
 
 # 运行数据库迁移
@@ -273,7 +288,7 @@ python -c "from map_client import MAPClient; print(MAPClient.from_env().get_me()
 ## MCP（IDE Agent）
 
 ```bash
-pip install -e ".[mcp]"
+pip install "multi-agent-platform[mcp]"
 export MAP_TOKEN=<your-token>
 
 # stdio — Cursor 本地子进程（默认）
@@ -296,3 +311,7 @@ map-mcp --transport streamable-http --host 0.0.0.0 --port 8080
 ## 后续
 
 v0.3–v0.6 与 v0.7 P3（CLI archive）已落地；当前主线为 **agent-runtime**（simple-waker 默认 + PersonaAgentClient；legacy runtime-waker 启动路径已退役，模块保留为 re-export 兼容层）。待推进项见 [docs/status-md-v10.md](docs/status-md-v10.md) 与 [架构文档](docs/ARCHITECTURE.md)。
+
+## License
+
+[MIT](LICENSE)

{multi_agent_platform-0.1.0 → multi_agent_platform-0.2.0}/README.md

@@ -1,7 +1,19 @@
 # Multi-Agent Platform (MAP)
 
+[![PyPI version](https://img.shields.io/pypi/v/multi-agent-platform.svg)](https://pypi.org/project/multi-agent-platform/)
+[![Python 3.11+](https://img.shields.io/pypi/pyversions/multi-agent-platform.svg)](https://pypi.org/project/multi-agent-platform/)
+[![License: MIT](https://img.shields.io/pypi/l/multi-agent-platform.svg)](https://github.com/quantaeye/multi-agent-platform/blob/main/LICENSE)
+
 多 Agent 实验协作平台：以话题为中心，管理实验计划、评审讨论、执行日志与项目状态。
 
+## 安装
+
+```bash
+pip install multi-agent-platform
+```
+
+安装后即可使用 `map` CLI 和 `map-server` 命令。详见 [Quick Start 指南](docs/QUICKSTART.md)。
+
 **新用户？** 一键启动：`./scripts/quickstart.sh`，或阅读 [Quick Start 指南](docs/QUICKSTART.md)。
 
 ## 文档
@@ -93,7 +105,10 @@ map --persona host todos
 ## 快速开始
 
 ```bash
-# 安装依赖（含开发工具）
+# 从 PyPI 安装（用户）
+pip install multi-agent-platform
+
+# 或从源码开发安装（贡献者）
 pip install -e ".[dev]"
 
 # 运行数据库迁移
@@ -228,7 +243,7 @@ python -c "from map_client import MAPClient; print(MAPClient.from_env().get_me()
 ## MCP（IDE Agent）
 
 ```bash
-pip install -e ".[mcp]"
+pip install "multi-agent-platform[mcp]"
 export MAP_TOKEN=<your-token>
 
 # stdio — Cursor 本地子进程（默认）
@@ -251,3 +266,7 @@ map-mcp --transport streamable-http --host 0.0.0.0 --port 8080
 ## 后续
 
 v0.3–v0.6 与 v0.7 P3（CLI archive）已落地；当前主线为 **agent-runtime**（simple-waker 默认 + PersonaAgentClient；legacy runtime-waker 启动路径已退役，模块保留为 re-export 兼容层）。待推进项见 [docs/status-md-v10.md](docs/status-md-v10.md) 与 [架构文档](docs/ARCHITECTURE.md)。
+
+## License
+
+[MIT](LICENSE)

{multi_agent_platform-0.1.0 → multi_agent_platform-0.2.0}/cli/commands/project.py

@@ -85,3 +85,68 @@ def project_status_show(
         lambda c: c.get_project_status_version(_resolve_project(c, project, project_key), version)
     )
 
+
+@project_app.command("export")
+def project_export(
+    output_dir: Path = typer.Option(
+        None,
+        "--output-dir",
+        "-o",
+        help="Output directory (default: .map/history/)",
+    ),
+    include_archived: bool = typer.Option(
+        True,
+        "--include-archived/--no-archived",
+        help="Include archived topics and experiments (default: yes)",
+    ),
+    project: uuid.UUID | None = typer.Option(None, "--project"),
+    project_key: str | None = typer.Option(None, "--project-key"),
+) -> None:
+    """Export project history (topics, experiments, decisions) to local Markdown.
+
+    The export is a read-only snapshot suitable for committing to Git,
+    so that topic discussions and experiment records travel with the code.
+
+    \b
+    Layout:
+        <output_dir>/
+          INDEX.md              # Browseable index
+          topics/<slug>.md      # One file per topic (with comments + decision)
+          experiments/<slug>.md # One file per experiment (with plans + reviews + logs)
+
+    \b
+    Examples:
+        map project export                      # Export to .map/history/
+        map project export -o ./docs/history    # Custom output directory
+        map project export --no-archived        # Skip archived items
+    """
+    from cli.main import _resolve_project, _run  # lazy: avoid cycle
+    from cli.project_export import export_project_history
+
+    if output_dir is None:
+        from cli.main import find_map_dir, _cli_options
+        map_dir = find_map_dir(_cli_options.get("project_root"))
+        if map_dir is not None:
+            output_dir = map_dir / "history"
+        else:
+            output_dir = Path(".map") / "history"
+
+    def action(c: MAPClient):
+        pid = _resolve_project(c, project, project_key)
+        result_dir = export_project_history(
+            c,
+            pid,
+            output_dir,
+            include_archived=include_archived,
+        )
+        # Count files for feedback
+        topic_files = list((result_dir / "topics").glob("*.md"))
+        exp_files = list((result_dir / "experiments").glob("*.md"))
+        typer.echo(
+            f"Exported {len(topic_files)} topic(s) and {len(exp_files)} experiment(s) "
+            f"to {result_dir}/"
+        )
+        return None
+
+    _run(action)
+

multi_agent_platform-0.2.0/cli/commands/sync.py

@@ -0,0 +1,169 @@
+"""``map sync ...`` sub-app — local cache sync commands.
+
+Commands:
+    map sync pull       — Pull project data from remote server to local cache
+    map sync status     — Show sync status (last pull time, cached counts)
+    map sync topics     — List cached topics (offline, from local cache)
+    map sync topic      — Show a cached topic by ID (offline, from local cache)
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+
+import typer
+from map_client.client import MAPClient
+
+sync_app = typer.Typer(help="Local cache sync commands (offline browsing)")
+
+
+def _require_cache_session():
+    """Open the local cache DB, exiting with a helpful hint if .map/ is missing."""
+    from cli.main import find_map_dir, _cli_options
+    from cli.local_cache import init_cache, get_cache_path
+
+    map_dir = find_map_dir(_cli_options.get("project_root"))
+    if map_dir is None:
+        typer.echo("Error: .map/ directory not found. Run `map bootstrap` first.", err=True)
+        raise typer.Exit(1)
+    db_path = get_cache_path(map_dir)
+    return map_dir, db_path, init_cache(db_path)
+
+
+@sync_app.command("pull")
+def sync_pull(
+    project: uuid.UUID | None = typer.Option(None, "--project"),
+    project_key: str | None = typer.Option(None, "--project-key"),
+    include_archived: bool = typer.Option(
+        True,
+        "--include-archived/--no-archived",
+        help="Include archived items (default: yes)",
+    ),
+) -> None:
+    """Pull project data from remote server into local cache (.map/cache.db).
+
+    After pulling, you can browse topics and experiments offline using
+    `map sync topics` and `map sync topic --id <uuid>`.
+    """
+    from cli.main import _resolve_project, _run
+    from cli.local_cache import pull_project_to_cache
+
+    map_dir, db_path, session = _require_cache_session()
+
+    def action(c: MAPClient):
+        pid = _resolve_project(c, project, project_key)
+        # Resolve project_key for sync_meta bookkeeping
+        from map_client.config import load_config
+
+        try:
+            pk = project_key or load_config().get("project_key") or ""
+        except Exception:
+            pk = project_key or ""
+
+        result = pull_project_to_cache(
+            session, c, pid, pk, include_archived=include_archived,
+        )
+        typer.echo(
+            f"Pulled {result['topics']} topic(s) and {result['experiments']} experiment(s) "
+            f"to {db_path}"
+        )
+        return None
+
+    try:
+        _run(action)
+    finally:
+        session.close()
+
+
+@sync_app.command("status")
+def sync_status(
+    project: uuid.UUID | None = typer.Option(None, "--project"),
+) -> None:
+    """Show local cache sync status."""
+    from cli.local_cache import get_sync_status
+
+    _, db_path, session = _require_cache_session()
+    if not db_path.exists():
+        typer.echo("No local cache found. Run `map sync pull` first.")
+        return
+
+    try:
+        statuses = get_sync_status(session, project)
+        if not statuses:
+            typer.echo("No sync records found. Run `map sync pull` first.")
+            return
+        for s in statuses:
+            typer.echo(f"Project: {s['project_key']} ({s['project_id']})")
+            typer.echo(f"  Last pull: {s['last_pull_at']}")
+            typer.echo(f"  Topics: {s['topic_count']}, Experiments: {s['experiment_count']}")
+    finally:
+        session.close()
+
+
+@sync_app.command("topics")
+def sync_topics(
+    project: uuid.UUID | None = typer.Option(None, "--project"),
+    project_key: str | None = typer.Option(None, "--project-key"),
+) -> None:
+    """List cached topics from local cache (offline)."""
+    from cli.local_cache import get_sync_status, list_cached_topics
+
+    _, db_path, session = _require_cache_session()
+    if not db_path.exists():
+        typer.echo("No local cache found. Run `map sync pull` first.")
+        return
+
+    try:
+        # If project_id not given, try to find it from sync_meta
+        if project is None:
+            statuses = get_sync_status(session)
+            if not statuses:
+                typer.echo("No cached projects. Run `map sync pull` first.")
+                return
+            # Use first project (or match by project_key)
+            if project_key:
+                for s in statuses:
+                    if s["project_key"] == project_key:
+                        project = uuid.UUID(s["project_id"])
+                        break
+            if project is None and len(statuses) == 1:
+                project = uuid.UUID(statuses[0]["project_id"])
+            if project is None:
+                typer.echo("Multiple projects cached. Specify --project or --project-key.")
+                for s in statuses:
+                    typer.echo(f"  {s['project_key']} ({s['project_id']})")
+                return
+
+        topics = list_cached_topics(session, project)
+        if not topics:
+            typer.echo("No cached topics. Run `map sync pull` first.")
+            return
+        typer.echo(f"{'ID':<36} {'Status':<12} {'Title'}")
+        typer.echo("-" * 80)
+        for t in topics:
+            typer.echo(f"{t['id']:<36} {t['status']:<12} {t['title']}")
+    finally:
+        session.close()
+
+
+@sync_app.command("topic")
+def sync_topic(
+    topic_id: uuid.UUID = typer.Option(..., "--id", help="Topic UUID"),
+) -> None:
+    """Show a cached topic from local cache (offline)."""
+    from cli.local_cache import get_cached_topic
+
+    _, db_path, session = _require_cache_session()
+    if not db_path.exists():
+        typer.echo("No local cache found. Run `map sync pull` first.")
+        return
+
+    try:
+        topic = get_cached_topic(session, topic_id)
+        if topic is None:
+            typer.echo(f"Topic {topic_id} not found in local cache.")
+            return
+        typer.echo(json.dumps(topic["data"], indent=2, default=str, ensure_ascii=False))
+    finally:
+        session.close()

multi_agent_platform-0.2.0/cli/local_cache.py

@@ -0,0 +1,255 @@
+"""Local SQLite cache for MAP project data — Plan A (read-only sync).
+
+This module provides a lightweight local cache that stores JSON snapshots
+of topics, experiments, and decisions pulled from a remote MAP server.
+The cache lives at ``.map/cache.db`` and enables offline browsing of
+project history.
+
+Architecture::
+
+    Remote MAP Server                  Local .map/cache.db
+    ┌──────────────────┐               ┌────────────────────┐
+    │  PostgreSQL /     │  ── pull ──>  │  sync_meta          │
+    │  SQLite           │   (JSON)      │  cached_topics      │
+    │                   │               │  cached_experiments │
+    └──────────────────┘               └────────────────────┘
+
+Design choices:
+- JSON blob storage (not full ORM) — keeps the cache schema-agnostic
+  and immune to server-side model changes
+- Upsert by UUID — repeated pulls update in place
+- ``sync_meta`` tracks last-pull timestamp per project for delta sync
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    String,
+    Text,
+    create_engine,
+    text,
+)
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class SyncMeta(Base):
+    """Tracks last-sync timestamp per project."""
+
+    __tablename__ = "sync_meta"
+
+    project_id = Column(String(36), primary_key=True)  # UUID as string
+    project_key = Column(String(64), nullable=False)
+    last_pull_at = Column(DateTime(timezone=True), nullable=False)
+    topic_count = Column(String(10), default="0")
+    experiment_count = Column(String(10), default="0")
+
+
+class CachedTopic(Base):
+    """A topic snapshot stored as JSON blob."""
+
+    __tablename__ = "cached_topics"
+
+    id = Column(String(36), primary_key=True)  # UUID as string
+    project_id = Column(String(36), nullable=False, index=True)
+    title = Column(String(512), nullable=False)
+    status = Column(String(32), nullable=False)
+    data_json = Column(Text, nullable=False)  # Full TopicRead as JSON
+    pulled_at = Column(DateTime(timezone=True), nullable=False)
+
+
+class CachedExperiment(Base):
+    """An experiment snapshot stored as JSON blob."""
+
+    __tablename__ = "cached_experiments"
+
+    id = Column(String(36), primary_key=True)  # UUID as string
+    project_id = Column(String(36), nullable=False, index=True)
+    title = Column(String(512), nullable=False)
+    phase = Column(String(32), nullable=False)
+    data_json = Column(Text, nullable=False)  # Full ExperimentBundleRead as JSON
+    pulled_at = Column(DateTime(timezone=True), nullable=False)
+
+
+def get_cache_path(map_dir: Path) -> Path:
+    """Return the cache database path inside ``.map/``."""
+    return map_dir / "cache.db"
+
+
+def init_cache(db_path: Path) -> Session:
+    """Initialize (or open) the local cache database and return a session."""
+    engine = create_engine(f"sqlite:///{db_path}", connect_args={"check_same_thread": False})
+    Base.metadata.create_all(engine)
+    SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
+    return SessionLocal()
+
+
+def pull_project_to_cache(
+    session: Session,
+    client: Any,  # MAPClient
+    project_id: uuid.UUID,
+    project_key: str,
+    *,
+    include_archived: bool = True,
+) -> dict[str, int]:
+    """Pull all topics and experiments from remote server into local cache.
+
+    Returns a dict with ``topics``, ``experiments`` counts.
+    """
+    now = datetime.now(timezone.utc)
+    pid_str = str(project_id)
+
+    # --- Pull topics ---
+    topic_count = 0
+    page = 1
+    while True:
+        batch = client.list_topics(
+            project_id,
+            page=page,
+            page_size=100,
+            include_archived=include_archived,
+        )
+        if not batch:
+            break
+        for summary in batch:
+            topic = client.get_topic(summary.id)
+            topic_json = topic.model_dump(mode="json") if hasattr(topic, "model_dump") else _to_dict(topic)
+            # Upsert
+            existing = session.get(CachedTopic, str(topic.id))
+            if existing:
+                existing.title = topic.title
+                existing.status = str(topic.status.value if hasattr(topic.status, "value") else topic.status)
+                existing.data_json = json.dumps(topic_json, default=str, ensure_ascii=False)
+                existing.pulled_at = now
+            else:
+                session.add(CachedTopic(
+                    id=str(topic.id),
+                    project_id=pid_str,
+                    title=topic.title,
+                    status=str(topic.status.value if hasattr(topic.status, "value") else topic.status),
+                    data_json=json.dumps(topic_json, default=str, ensure_ascii=False),
+                    pulled_at=now,
+                ))
+            topic_count += 1
+        if len(batch) < 100:
+            break
+        page += 1
+
+    # --- Pull experiments ---
+    experiment_count = 0
+    page = 1
+    while True:
+        batch = client.list_experiments(
+            project_id,
+            page=page,
+            page_size=100,
+            include_archived=include_archived,
+        )
+        if not batch:
+            break
+        for summary in batch:
+            bundle = client.get_experiment_bundle(summary.id)
+            bundle_json = bundle.model_dump(mode="json") if hasattr(bundle, "model_dump") else _to_dict(bundle)
+            exp = bundle.experiment if hasattr(bundle, "experiment") else bundle
+            phase_val = str(exp.phase.value if hasattr(exp.phase, "value") else exp.phase)
+            # Upsert
+            existing = session.get(CachedExperiment, str(exp.id))
+            if existing:
+                existing.title = exp.title
+                existing.phase = phase_val
+                existing.data_json = json.dumps(bundle_json, default=str, ensure_ascii=False)
+                existing.pulled_at = now
+            else:
+                session.add(CachedExperiment(
+                    id=str(exp.id),
+                    project_id=pid_str,
+                    title=exp.title,
+                    phase=phase_val,
+                    data_json=json.dumps(bundle_json, default=str, ensure_ascii=False),
+                    pulled_at=now,
+                ))
+            experiment_count += 1
+        if len(batch) < 100:
+            break
+        page += 1
+
+    # --- Update sync_meta ---
+    meta = session.get(SyncMeta, pid_str)
+    if meta:
+        meta.last_pull_at = now
+        meta.topic_count = str(topic_count)
+        meta.experiment_count = str(experiment_count)
+        meta.project_key = project_key
+    else:
+        session.add(SyncMeta(
+            project_id=pid_str,
+            project_key=project_key,
+            last_pull_at=now,
+            topic_count=str(topic_count),
+            experiment_count=str(experiment_count),
+        ))
+
+    session.commit()
+    return {"topics": topic_count, "experiments": experiment_count}
+
+
+def get_sync_status(session: Session, project_id: uuid.UUID | None = None) -> list[dict[str, Any]]:
+    """Return sync status for all projects (or a specific one)."""
+    query = session.query(SyncMeta)
+    if project_id is not None:
+        query = query.filter(SyncMeta.project_id == str(project_id))
+    results = []
+    for meta in query.all():
+        results.append({
+            "project_id": meta.project_id,
+            "project_key": meta.project_key,
+            "last_pull_at": meta.last_pull_at.isoformat() if meta.last_pull_at else None,
+            "topic_count": int(meta.topic_count or "0"),
+            "experiment_count": int(meta.experiment_count or "0"),
+        })
+    return results
+
+
+def list_cached_topics(session: Session, project_id: uuid.UUID) -> list[dict[str, Any]]:
+    """List cached topics (lightweight metadata, no JSON blob)."""
+    rows = session.query(CachedTopic).filter(CachedTopic.project_id == str(project_id)).all()
+    return [
+        {
+            "id": r.id,
+            "title": r.title,
+            "status": r.status,
+            "pulled_at": r.pulled_at.isoformat() if r.pulled_at else None,
+        }
+        for r in rows
+    ]
+
+
+def get_cached_topic(session: Session, topic_id: uuid.UUID) -> dict[str, Any] | None:
+    """Get a single cached topic with full JSON data."""
+    row = session.get(CachedTopic, str(topic_id))
+    if row is None:
+        return None
+    return {
+        "id": row.id,
+        "title": row.title,
+        "status": row.status,
+        "data": json.loads(row.data_json) if row.data_json else None,
+        "pulled_at": row.pulled_at.isoformat() if row.pulled_at else None,
+    }
+
+
+def _to_dict(obj: Any) -> dict[str, Any]:
+    """Fallback serialization for non-Pydantic objects."""
+    if hasattr(obj, "__dict__"):
+        return {k: v for k, v in obj.__dict__.items() if not k.startswith("_")}
+    return {"value": str(obj)}

{multi_agent_platform-0.1.0 → multi_agent_platform-0.2.0}/cli/main.py

@@ -39,6 +39,7 @@ from cli.commands.notification import inbound_event_app, notification_app
 from cli.commands.persona import persona_app
 from cli.commands.project import project_app
 from cli.commands.runtime import runtime_app
+from cli.commands.sync import sync_app
 from cli.commands.topic import mention_app, todo_app, topic_app
 from cli.e2e_collab import e2e_app
 from server.domain.models import AgentRole
@@ -63,6 +64,7 @@ app.add_typer(action_app, name="action")
 app.add_typer(feedback_app, name="feedback")
 app.add_typer(docs_app, name="docs")
 app.add_typer(e2e_app, name="e2e")
+app.add_typer(sync_app, name="sync")
 
 _transport: httpx.BaseTransport | None = None
 _cli_options: dict[str, Any] = {"persona": None, "project_root": None, "format": "yaml"}