Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,10 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
[questions about Lens](docs/assistant.md#questions-about-lens-itself), [chat rooms](docs/chat-rooms.md), [email](docs/assistant-email.md), [speech providers](docs/speech-providers.md);
[checks](docs/requirements.md#ask-and-get-cited-answers))
- **Work toward a goal in projects.** A project has a name, a goal in your words, instructions and the namespaces it
draws on. Its coordinator conversation looks at the project as a whole and is told about every thread; each thread is
a conversation about one part of the work, scoped to the project's namespaces and marked done when finished. Every
answer in a project reads its goal and instructions. Agents start and change projects over MCP and the API.
draws on. Its coordinator conversation looks at the project as a whole: it is told about every thread, starts threads
with a brief that the assistant answers there in the background, reads them and marks them done. Each thread is a
conversation about one part of the work, scoped to the project's namespaces. Every answer in a project reads its goal
and instructions. Agents start and change projects over MCP and the API.
([Projects](docs/projects.md); [checks](docs/requirements.md#work-toward-a-goal-in-projects))
- **Extend the assistant.** Add tools (a prompt, a web request, a graph drawn on the canvas, or sandboxed Python),
skills, hooks and MCP servers, by code, on the canvas or just by asking. Remote MCP servers connect by address, and
Expand Down
4 changes: 3 additions & 1 deletion changelog.d/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,7 @@
and the namespaces it draws on. It comes with a coordinator conversation about the project as a whole, which is told
about every thread, and its threads are conversations scoped to its namespaces, marked done when finished; your own
conversations can be brought in or taken out, and deleting a project keeps them. Every answer in a project reads its
goal and instructions. `/api/v1/projects` and the MCP tools `list_projects`, `read_project`, `create_project` and
goal and instructions. The coordinator starts threads with a brief (`start_thread`), reads them and marks them done;
a brief, from it, you or an agent, is answered in the background as you, with your tools, approvals and budgets.
`/api/v1/projects` and the MCP tools `list_projects`, `read_project`, `create_project` and
`update_project` do it all for agents ([Projects](docs/projects.md)).
40 changes: 34 additions & 6 deletions docs/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,11 @@ case, a piece of code. You give it a name, the goal in your own words, instructi
it draws on. Every conversation in it reads all of that, so you don't explain the project again each time.

Status: **built**: projects with a goal, instructions and one or more namespaces; a coordinator conversation for the
project as a whole, told about every thread; threads, each a conversation in the project's namespaces, marked done when
finished; your own conversations brought in or taken out; through the REST API and MCP. **Planned**: the coordinator
starting threads with a brief and reading them, scheduled threads, a Projects page in the web app, chat rooms and email
routed to a project, members sharing one, and a project's own memory.
project as a whole, told about every thread, which starts threads with a brief, reads them and marks them done;
threads, each a conversation in the project's namespaces, marked done when finished; briefs answered in the background;
your own conversations brought in or taken out; through the REST API and MCP. **Planned**: scheduled threads, a
Projects page in the web app, chat rooms and email routed to a project, members sharing one, and a project's own
memory.

## What a project is

Expand Down Expand Up @@ -42,6 +43,33 @@ in Chat). Changing the project's namespaces changes every one of its conversatio
Deleting a project keeps its conversations, as ordinary ones in Chat. Deleting its coordinator conversation makes a
new one the next time the project is opened.

## The coordinator's tools

In a project's conversations the assistant has the tools of **This project** (one of the groups in the tool picker,
[Choosing tools](assistant.md#choosing-tools-namespaces-and-a-limit)):

| Tool | What it does |
| --- | --- |
| `project_threads` | the project's threads: each one's title, whether it's done, whether an answer is being written, its last message |
| `read_thread` | a thread's last messages |
| `start_thread` | from the coordinator: a new thread with a title and a brief, which is answered there in the background (below) |
| `finish_thread` | mark a thread done, or not done |

So you can say to the coordinator "split this into the wood, the tools and a weekend plan" and it starts a thread for
each, then reads what they found. One answer starts at most three threads. A brief written after the answer read text
from outside Lens (a document, a web page, another thread) could carry that text's instructions, so then
`start_thread` asks for your approval first, like the other tools that would act on it.

## Briefs

A thread can start with a brief: what to do, with everything it needs. The coordinator writes one with `start_thread`;
you or an agent give one with `brief` on `POST /api/v1/projects/{id}/threads` (or MCP `update_project`'s `new_thread`
and `brief`). It is asked as the thread's question and answered in the background, as you: with the tools you have
there (the conversation's choice of them) and the same approvals, every model call counted for the answer in the
[activity ledger](activity.md) and held to your budgets. The thread shows `answering` until the answer is saved, and
Stop (`POST /api/v1/chats/{id}/stop`) stops it between steps. If Lens stops while a brief is being answered, the thread
says so within a few minutes, so it's never left waiting: ask again.

## The API

| Call | What it does |
Expand All @@ -52,7 +80,7 @@ new one the next time the project is opened.
| `PATCH /api/v1/projects/{id}` | change its name, goal, instructions or namespaces, or archive it |
| `DELETE /api/v1/projects/{id}` | delete it; its conversations stay |
| `GET /api/v1/projects/{id}/threads` | its threads, the coordinator among them |
| `POST /api/v1/projects/{id}/threads` | a new thread (`title`), or bring in one of your conversations (`chat`) |
| `POST /api/v1/projects/{id}/threads` | a new thread (`title`), or bring in one of your conversations (`chat`); with a `brief`, asked and answered there in the background |
| `PATCH /api/v1/projects/{id}/threads/{chat}` | mark a thread done, or not (`done`) |
| `DELETE /api/v1/projects/{id}/threads/{chat}` | take a thread out of the project |

Expand All @@ -62,7 +90,7 @@ same for agents; the last two need a token with the write scope.

## Refine later

- The coordinator starting threads with a brief, reading them and marking them done, as its own tools.
- Threads answering their briefs at the same time as each other, with a limit per person.
- Scheduled threads: a prompt asked on a schedule, in a new thread each time or the same one.
- A Projects page in the web app.
- Chat rooms, Telegram, Slack and email routed to a project.
Expand Down
2 changes: 2 additions & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ request, to another check that proves the same thing; loosening a requirement or
| A project with a goal, instructions and namespaces, a coordinator conversation and threads scoped to its namespaces, marked done, brought in or taken out; deleting it keeps its conversations | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_a_project_with_a_goal_namespaces_and_threads`, `test_changing_its_namespaces_moves_its_conversations` |
| A project is its owner's alone and draws only on namespaces they can read | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_projects_are_their_owners_and_draw_on_readable_namespaces` |
| Every answer in a project reads its goal and instructions; the coordinator is told about the threads, as data | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_every_answer_in_a_project_reads_what_it_is_for` |
| The coordinator starts threads with a brief, reads them and marks them done; a thread can't start threads; it asks first after reading outside text, and starts a few per answer at most | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_the_coordinator_starts_threads_with_a_brief`, `test_starting_threads_after_reading_outside_text_asks_first` |
| A brief from the person, an agent or the coordinator is answered in the background as the person; one cut off by a stopped process is marked, never left waiting | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_a_brief_from_the_api_or_an_agent_is_answered_in_the_background`, `test_a_brief_cut_off_by_a_stop_is_marked_by_the_sweep` |
| Agents list, read, start and change projects over MCP | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_agents_use_projects_over_mcp` |

## Extend the assistant
Expand Down
11 changes: 8 additions & 3 deletions fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -2087,8 +2087,9 @@ def create_project(ctx: Context, name: str, goal: str | None, instructions: str
"update_project",
"Change a project",
"Change one of your projects: its name, goal, instructions or namespaces (its conversations draw on the new ones), "
"archive it, mark one of its threads done (thread_id, done), or start a thread (new_thread: its title; ask in it "
"with the web app or POST /api/v1/chats/{id}/messages). Only what you give changes. Needs a token with the write scope.",
"archive it, mark one of its threads done (thread_id, done), or start a thread (new_thread: its title) with a "
"brief Lens's assistant answers there in the background (read it with read_chat). Only what you give changes. "
"Needs a token with the write scope.",
Arg("project_id", "integer", "the project (from list_projects)", required=True),
Arg("name", "string", "its new name", max_length=120),
Arg("goal", "string", "its new goal", max_length=4000),
Expand All @@ -2098,6 +2099,7 @@ def create_project(ctx: Context, name: str, goal: str | None, instructions: str
Arg("thread_id", "integer", "a thread to mark done or not done"),
Arg("done", "boolean", "with thread_id: done or not"),
Arg("new_thread", "string", "start a thread with this title", max_length=120),
Arg("brief", "string", "with new_thread: what to do there, answered in the background by Lens's assistant", max_length=4000),
writes=True,
personal=True,
)
Expand All @@ -2112,8 +2114,11 @@ def update_project(
thread_id: int | None,
done: bool | None,
new_thread: str | None,
brief: str | None,
) -> dict[str, Any]:
_writer(ctx, "change projects")
if brief and not new_thread:
raise ToolError("give new_thread (its title) with brief")
changes = {"name": name, "goal": goal, "instructions": instructions, "namespaces": namespaces, "archived": archived}
started = None
if any(v is not None for v in changes.values()):
Expand All @@ -2123,7 +2128,7 @@ def update_project(
raise ToolError("give done (true or false) with thread_id")
project_routes.update_thread(project_id, thread_id, ThreadUpdate(done=done), ctx.user, ctx.db)
if new_thread:
started = project_routes.start_thread(project_id, ctx.user, ctx.db, ThreadCreate(title=new_thread)).id
started = project_routes.start_thread(project_id, ctx.user, ctx.db, ctx.cfg, ThreadCreate(title=new_thread, brief=brief)).id
out = _project(ctx, project_routes.get_project(project_id, ctx.user, ctx.db))
if started is not None:
out["started"] = {"chat_id": started, "url": f"{ctx.web}/chat/{started}"}
Expand Down
16 changes: 10 additions & 6 deletions fastapi_backend/app/api/v1/routes/projects.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

from fastapi import APIRouter, HTTPException, Query

from app.api.deps import Acl, CurrentUser, Db, Principal, Writer
from app.api.deps import Acl, Cfg, CurrentUser, Db, Principal, Writer
from app.domain import projects
from app.domain.store import DB
from app.schemas.common import Created, Ok
Expand Down Expand Up @@ -103,16 +103,20 @@ def list_threads(pid: int, user: CurrentUser, db: Db) -> list[ProjectThread]:


@router.post("/{pid}/threads")
def start_thread(pid: int, user: Writer, db: Db, body: ThreadCreate | None = None) -> Created:
"""A new thread: a conversation in the project's namespaces (ask in it with POST /chats/{id}/messages). With `chat`,
one of your conversations joins the project instead, drawing on its namespaces from then on."""
def start_thread(pid: int, user: Writer, db: Db, cfg: Cfg, body: ThreadCreate | None = None) -> Created:
"""A new thread: a conversation in the project's namespaces (ask in it with POST /chats/{id}/messages). With a
`brief`, it is asked there at once and answered in the background, as you, with your tools and approvals: GET
/chats/{id} shows the answer once it's written (the thread is `answering` until then). With `chat`, one of your
conversations joins the project instead, drawing on its namespaces from then on (with a brief, asked there next)."""
body = body or ThreadCreate()
p = own(db, pid, user)
try:
cid = body.chat if body.chat is not None else projects.start_thread(db, p, body.title)
if body.chat is not None:
projects.adopt(db, p, body.chat)
return Created(id=body.chat)
return Created(id=projects.start_thread(db, p, body.title))
if body.brief and body.brief.strip():
projects.brief(db, cfg, p, cid, body.brief, via="web" if user.via == "access" else "api")
return Created(id=cid)
except KeyError:
raise HTTPException(404, "no such conversation of yours") from None
except ValueError as e:
Expand Down
Loading
Loading